diff --git a/.yoi/tickets/open/20260607-230044-relax-implementation-planning-readiness/artifacts/.gitkeep b/.yoi/tickets/open/20260607-230044-relax-implementation-planning-readiness/artifacts/.gitkeep new file mode 100644 index 00000000..e69de29b diff --git a/.yoi/tickets/open/20260607-230044-relax-implementation-planning-readiness/item.md b/.yoi/tickets/open/20260607-230044-relax-implementation-planning-readiness/item.md new file mode 100644 index 00000000..d90e8b2d --- /dev/null +++ b/.yoi/tickets/open/20260607-230044-relax-implementation-planning-readiness/item.md @@ -0,0 +1,99 @@ +--- +id: 20260607-230044-relax-implementation-planning-readiness +slug: relax-implementation-planning-readiness +title: Relax implementation planning readiness toward intent and reviewability +status: open +kind: task +priority: P2 +labels: [workflow, ticket, orchestrator, preflight, review] +workflow_state: queued +created_at: 2026-06-07T23:00:44Z +updated_at: 2026-06-07T23:03:58Z +assignee: null +legacy_ticket: null +queued_by: workspace-panel +queued_at: 2026-06-07T23:03:35Z +--- + +## Background + +Current Intake / Preflight / Orchestrator workflow wording tends to require implementation strategy to be narrowed too early. In practice, the most reliable implementation investigation often happens when the implementation Pod/coder reads the code and attempts the change in the scoped worktree. + +The higher-level planning/intake stage should prioritize clarifying intent, constraints, and reviewable outcomes rather than over-specifying the implementation approach. Reviewers need enough intent and acceptance criteria to judge whether the implementation matches the user's/project's intent; coders should retain room to discover the best local implementation path unless a design decision is explicitly fixed. + +Current problem: + +- Intake/Planning `ready` and Orchestrator `implementation_ready` are easy to interpret as requiring a nearly fixed implementation plan. +- Orchestrator may over-classify tickets as `preflight_needed` when some uncertainty could safely be resolved by the coder during implementation and checked by reviewer. +- This creates extra preflight churn and can make the workflow feel stalled. + +Desired direction: + +- Clarify intent first. +- Keep implementation judgment available to the coder where safe. +- Make reviewer validation against intent the key quality gate. +- Treat explicit design decisions/invariants as binding when present. +- Use preflight for genuine design-boundary/product/API/authority uncertainty, not every implementation unknown. + +## Goal + +Adjust Ticket Intake/Planning, Orchestrator routing, and Preflight workflow guidance so readiness is based on clear intent and reviewability, while preserving coder discretion for implementation details unless constrained by explicit decisions. + +## Requirements + +### Readiness semantics + +- Define `ready` as ready for Orchestrator routing, not necessarily fully implementation-planned. +- Define implementation handoff readiness as: + - user/project intent is clear; + - observable acceptance criteria are clear enough; + - important constraints/invariants/non-goals are captured; + - reviewer can judge whether the resulting implementation satisfies the intent; + - known binding design decisions are recorded; + - unresolved questions are either non-blocking implementation details or explicitly listed as escalation conditions. +- Avoid requiring Intake/Planning to pre-decide local implementation tactics when they can be safely discovered by the coder. + +### Orchestrator routing + +- Narrow `preflight_needed` so it is reserved for real design/product/API/authority-boundary uncertainty, not ordinary code investigation or implementation tactic selection. +- Make `implementation_ready` allow bounded implementation uncertainty when: + - intent and acceptance criteria are clear; + - coder can investigate safely within scope; + - reviewer can evaluate against recorded intent; + - escalation conditions are defined. +- Keep `preflight_needed` for cases where implementing would implicitly decide product/API/UX/authority boundaries or violate known design constraints. +- Require Orchestrator to record whether implementation latitude is allowed and what must be escalated. + +### Coder/reviewer handoff + +- Update intent packet guidance to distinguish: + - Binding decisions / invariants the coder must follow. + - Implementation latitude the coder may decide through code investigation. + - Escalation conditions that require returning to Orchestrator/human. +- Reviewer instructions should emphasize judging the implementation against intent, constraints, and acceptance criteria, not whether it followed an unrecorded preferred approach. +- If a design approach is explicitly stated in the Ticket/thread, reviewer should verify the implementation follows it or records a justified deviation. + +### Workflow/docs updates + +- Update `.yoi/workflow/ticket-intake-workflow.md`. +- Update `.yoi/workflow/ticket-orchestrator-routing.md`. +- Update `.yoi/workflow/ticket-preflight-workflow.md`. +- Update `.yoi/workflow/multi-agent-workflow.md` if needed to reflect coder latitude and reviewer intent-checking. +- Adjust role prompt wording/tests if generated prompt guidance currently over-demands pre-decided implementation plans. + +## Non-goals + +- Do not remove preflight; narrow when it is required. +- Do not allow coders to make product/API/authority decisions silently. +- Do not weaken explicit design decisions or invariants recorded by humans/Orchestrator. +- Do not change Ticket state machine names in this ticket unless it is already being handled by the planning-state rename work. + +## Acceptance criteria + +- Workflows clearly distinguish ready-for-routing, implementation handoff, and fully specified implementation plan. +- Orchestrator routing guidance no longer treats ordinary implementation investigation as automatic `preflight_needed`. +- Intent packet template includes sections for binding decisions, implementation latitude, and escalation conditions. +- Reviewer guidance focuses on intent/constraints/acceptance criteria and explicit decisions. +- Example wording makes clear that coder investigation is acceptable when intent is clear and risks are bounded. +- Existing Ticket/preflight tests or prompt tests are updated if affected. +- `target/debug/yoi ticket doctor`, `cargo fmt --check`, and `git diff --check` pass. diff --git a/.yoi/tickets/open/20260607-230044-relax-implementation-planning-readiness/thread.md b/.yoi/tickets/open/20260607-230044-relax-implementation-planning-readiness/thread.md new file mode 100644 index 00000000..8276f1e0 --- /dev/null +++ b/.yoi/tickets/open/20260607-230044-relax-implementation-planning-readiness/thread.md @@ -0,0 +1,65 @@ + + +## Created + +Created by LocalTicketBackend create. + +--- + + + +## Intake summary + +Updated/verified existing Ticket as ready for Orchestrator routing. Intent: relax Intake/Planning/Orchestrator/Preflight workflow guidance so readiness is based on clear intent, reviewable acceptance criteria, explicit constraints, and escalation conditions, while preserving bounded coder implementation latitude. Acceptance criteria are observable across workflow wording, intent packet guidance, reviewer guidance, affected prompt/tests if any, and validation commands. needs_preflight: true because this changes workflow policy and orchestration semantics; risk_flags: workflow-policy, orchestration-semantics, reviewer-handoff, prompt-guidance. No duplicate Ticket was created. + +--- + + + +## State changed + +Intake completed for existing Ticket. Requirements and acceptance criteria are sufficient for Orchestrator routing; implementation must not start until the user queues the ready Ticket and Orchestrator accepts it. + +--- + + + +## State changed + +Ticket queued for Orchestrator routing. + + +--- + + + +## Decision + +Routing decision: preflight_needed + +Reason: +- This Ticket intentionally changes workflow policy and orchestration semantics for Intake, Orchestrator routing, Preflight, and multi-agent coder/reviewer handoff. +- Intake explicitly marked `needs_preflight: true` with risk flags `workflow-policy`, `orchestration-semantics`, `reviewer-handoff`, and `prompt-guidance`. +- The desired direction is clear, but implementation should first fix the policy boundary: when bounded coder implementation latitude is acceptable, what remains a binding design/authority decision, and how reviewers should judge deviations. + +Evidence checked: +- Ticket body requirements, non-goals, acceptance criteria, and affected workflow paths. +- Intake summary and `ready -> queued` event. +- Workspace state: no existing branch/worktree for this slug; an unrelated active child worktree/Pod exists for `parse-ticket-frontmatter-as-yaml`; unrelated untracked Ticket directories are present. +- Visible Pods: intake peer for this Ticket is idle; no coder/reviewer Pods are active for this Ticket. + +Next action: +- Run `ticket-preflight-workflow` before implementation delegation. +- Preflight should record a concise wording/design boundary for: + - implementation latitude versus binding decisions/invariants; + - when `preflight_needed` remains mandatory; + - what Orchestrator must put in IntentPacket as latitude and escalation conditions; + - how reviewer instructions should judge against intent/constraints/acceptance rather than unrecorded tactics. +- Do not transition `queued -> inprogress`, create `.worktree/relax-implementation-planning-readiness`, or spawn coder/reviewer Pods until preflight records implementation readiness. + +Escalate if: +- The wording would weaken authority/product/API/design-boundary gates rather than only narrowing unnecessary preflight churn. +- The change conflicts with current Ticket workflow state semantics or role-launch contracts. +- Prompt/resource changes are required beyond workflow docs and need separate validation scope. + +---