Implementation Planning

Purpose

Convert a drafted spec into the artifacts an AI Developer session needs to execute: a letter-decision matrix, a numbered task chain, a verification-gate contract, and a saved handoff prompt.

When to invoke

• Active phase is Plan or Decisions (per FLOW_RULES state announcement)
• A spec exists at docs/specs/<slug>/spec.md with status DRAFT and clarify questions resolved
• Operator says "plan this" / "draft decisions" / "let's break this into tasks"

Do not invoke when

• Spec status is still DRAFT with unresolved clarify questions (re-invoke requirements-specification instead)
• decisions are locked (decisions.md Lock status: LOCKED) and decisions/tasks already exist (use code-review or validation-and-qa instead)
• Operator wants to skip planning and start coding directly — STOP. FR-02 (plan before edit) requires written tasks.

Documentation tier gate (FR-23)

Before drafting any planning artifact, apply the tier from flow-skills/documentation-budget/SKILL.md (don't duplicate it). Create each artifact ONLY when its trigger holds:

Invoke this skill only after the lane assessment identifies an objective Full trigger. If assessment is incomplete after bounded read-only diagnosis, stop at BLOCKED-AT-lane-assessment; do not infer Full or Lightweight. Never weaken a safety artifact required by policy to save docs. Lightweight work takes the change-note path in requirements-specification.

Required inputs

Procedure

1. Re-read spec.md and the acceptance criteria.
2. For Fusebase Apps tickets, read docs/fusebase-cli-edition.md and list the CLI domain skills that should inform decisions, tasks, gate probes, or deploy handoff. Cite the relevant skill names; do not duplicate their runtime instructions in Flow artifacts.
3. Identify architectural choices that need explicit decisions. Each choice gets a letter (e.g., G1, G2, ... where G is the ticket's letter prefix).
4. Draft decisions.md using templates/decisions.md — ONLY if step 3 surfaced a real decision with alternatives (FR-23; otherwise omit the file). For each decision: recommendation, reasoning, alternatives considered (with rejection reasons), lock status PENDING. If the decision needs divergent product/UI/workflow alternatives, invoke flow-skills/design-discovery-ideation/SKILL.md first so the options are meaningfully different, not cosmetic variants.
5. For frontend/UI tickets, add an implementation-ready design brief to decisions or the implement handoff: selected direction, product identity, routes/screens/workflows, data types and fields, API/helper names and signatures when known, applicable stack conventions/project frontend rules, stable test selector strategy, trust-critical real interactions, explicit non-goals, and the applicable quality-pattern IDs from the spec ACs (QP-xx — flow-skills/app-quality-patterns; the implementer reads the cited category before building). Non-UI tickets with QP-cited ACs (e.g., data-integrity QP-10..14) carry the IDs in the implement handoff instead.
6. Draft tasks.md using templates/tasks.md. Number tasks T<n>, T<n+1>, ... starting from current T-counter. Mark dependency edges. Identify the verification-gate task (T<gate>) and deploy task (T<deploy>). Pair each task's steps with their verification per flow-skills/zoom-out/references/karpathy-guidelines.md §4; AC links, dependency edges and the gate contract stay as defined here. Module-size check (FR-25): every task names its target file(s). For each target over the policies/module-size.yml ceiling (or that the task would push over it), the task must either (a) state the extraction — new module name + the responsibility seam — or (b) carry a one-line exemption with reason for operator approval. "Where does this code live" is decided here, at Plan — mid-implement it is never asked, which is exactly how monoliths accrete. Full rule: flow-skills/module-size-discipline/SKILL.md.
7. Draft verification-gate.md using templates/verification-gate.md — when Full lane or gate policy requires it (FR-23). If user-facing/operator-facing smoke is needed, invoke flow-skills/smoke-testing/SKILL.md before writing S1..Sn. Include: gate-report required fields, outcome-based smoke prompts, probe list, rollback procedure.
8. Run cross-artifact consistency check: every AC mapped to at least one task; every locked decision cited in at least one task; every task lands a worker-undisturbed check or notes N/A; every task's Inputs: names the tool or access that reads each required input, and the agent planned to run it has that tool — the <name>-project variant counts when policies/agent-tools.yml gives it the tool (task-delegation § Agent tool reach). An unavailable required input becomes a clarify question (FR-11) before lock — never a build-time fallback; PENDING-OPERATOR-SMOKE / SHIPPED-pending-operator-smoke are verification states only.
9. Present decisions for lock in chat (Mode A — comparison table when there are 3+ alternatives). End with explicit lock prompt: "Reply 'lock' to approve all as recommended, OR 'redirect <Letter><n>' to change."
10. Wait for operator lock confirmation per FR-11. Implicit approval ("ok", "looks good") does NOT count.
11. After lock: increment letter prefix and T-counter in AGENTS.md. Update tasks.md SHAs to LOCKED.
12. Draft implementer handoff from templates/handoff-implement.md (canonical); save to docs/tmp/handoff/<YYYY-MM-DD>-<slug>-implement.md BEFORE outputting in chat (FR-04). Per FR-23, the handoff points to canonical spec.md / decisions.md / tasks.md (cite paths + AC/decision IDs); it must NOT reprint their contents.
13. Tell operator: "Implement handoff saved to <path>. Open that file, paste into a fresh AI agent session as AI Developer."

Worked example

A completed lane assessment declares public-contract at src/api/orders.ts:18, so the ticket enters Full. The Product Owner maps the contract outcome to AC1, records the operator's API-shape decision in B1, splits implementation and compatibility verification into separate T-tasks, and saves one implement handoff that points to those owners. A no-trigger assessment would not reach this skill; an incomplete assessment would stop at BLOCKED-AT-lane-assessment.

Output artifacts

Failure cases

Escalation path

• 12+ tasks needed → propose ticket split via requirements-specification re-invoke
• Cross-cutting refactor with subtle interactions → propose architect escalation via workflows/architect-escalation.md
• Product/UI direction unclear or operator asks for options → invoke design-discovery-ideation before locking decisions
• Stack/framework expertise gap → invoke repo-onboarding-context-map for the unfamiliar area first

Anti-patterns

• Do NOT lock decisions on operator's behalf (FR-11)
• Do NOT skip the cross-artifact consistency check
• Do NOT output the handoff prompt in chat without saving to disk first (FR-04)
• Do NOT increment letter prefix or T-counter before operator confirms lock
• Do NOT include code edits in tasks.md beyond the file-and-scope description; the implementer writes the code
• Do NOT create decisions.md when no real decision was made (FR-23) — a single-option "decision" is not a decision
• Do NOT reprint spec ACs, full problem statement, or product rationale in tasks.md or the handoff (FR-23) — point to the canonical owner
• Do NOT create verification-gate.md when neither Full lane nor gate policy requires it (FR-23)
• Do NOT plan a task onto an over-ceiling file without an extraction or an explicit exemption (FR-25) — defaulting new code into the existing big file is how monoliths grow

Clean-room note

Original Fusebase Flow content. Designed after reviewing public AI coding workflow patterns; no third-party code, prompts, skill files, or hook scripts are copied. See docs/source-map.md.