flow-patch

name	flow-patch
description	Small bounded changes with micro-spec, inline TDD, and per-task review. Invoke with /flow-patch.
disable-model-invocation	true
metadata	{"flow":{"command":"/flow-patch"}}

Flow Patch

Triggered by: /flow-patch

For single bounded changes — too small for a full spec doc. Implement inline in this session so the user sees work in real time. Review after each task via subagents.

When to use

Use /flow-patch	Redirect to /flow-spec
≤3 files, one concern	>3 files or multiple concerns
Clear success criteria	Needs design exploration
Bug fix with known cause	Architectural change

Branch rule

Read and follow flow-shared/references/session-gate.md then flow-shared/references/branch-gate.md (resolve via path resolver in flow/SKILL.md). Session gate before any STATE write; branch and workspace confirmation before implementation.

Patch on main/master: use branch-gate On main menu (branch here vs worktree) — never commit patch work on main without explicit approval.

Patch on a feature branch: default continue on current branch when phase: done or no STATE; use branch-gate Continuing on current feature branch (patch) — not the execute-style switch/worktree 1/2 menu. User may opt into worktree or new branch explicitly.

Branch and workspace confirmation is a blocking user gate — same weight as micro-spec approval. Micro-spec approval does not satisfy branch or workspace confirmation.

Process

1. Micro-spec (required)

If docs/flow/STATE.md or the user points to a brainstorm brief at docs/flow/brainstorms/..., read it first and carry forward agreed decisions into the micro-spec.

Brainstorm handoff: If you continued from brainstorm §7 (user picked patch, or spec→patch override), you are already in patch workflow — do not tell the user to invoke /flow-patch. If the brief's scope exceeds patch criteria, read flow-spec/SKILL.md via path resolver and follow spec — do not tell the user to invoke /flow-spec.

Write inline before any code. Break work into one or more tasks with bite-sized steps:

## Micro-spec

**Problem:** [what's wrong or needed]
**Success criteria:** [how we know it's done]
**Files:** [expected touch list]
**Out of scope:** [what we will NOT do]
**Testing:** [RED-GREEN for behavior changes | no new tests + manual checks for presentation-only — see `tdd-red-green.md`]

### Task 1: [name]

- [ ] Step 1: Write failing test …
- [ ] Step 2: Verify RED …
- [ ] Step 3: Implement …
- [ ] Step 4: Verify GREEN …
- [ ] Step 5: Commit

Single-task patches are fine. Multi-step work gets one review cycle per task, not per checkbox.

Micro-spec failures (never write these): TBD/TODO, "add tests", "handle edge cases", steps without code or commands, vague success criteria.

Micro-spec self-review — fix inline until all blocking checks pass. Do not proceed to §2 while blocked.

Calibration: Contradictions and unmapped success criteria are blocking. Wording polish is advisory.

• General: No placeholders; no internal contradictions; no unrequested scope (YAGNI)
• Success criteria audit: Each success criterion must cite Problem, Files, or a task step that satisfies it. Missing backing → fix or remove the criterion
• Out of scope: Task steps must not touch anything listed under Out of scope

2. Micro-spec gate (required)

Run micro-spec self-review internally (§1). Do not proceed to §2 while blocked. Then present the micro-spec and send only this gate — do not combine with workspace setup or Task 1:

Micro-spec ready.

1. Approve micro-spec — proceed to workspace setup
2. Request changes — tell me what to revise
3. Stop — no implementation

Do not expose internal self-review checklist names (criteria mapping counts, structure trees, Status/Blocked) in the gate message — the user reviews the micro-spec content, not the agent's audit worksheet. Do not ask the user to find contradictions you should have caught in self-review.

Stop until the user picks 1, approves the micro-spec explicitly, or requests changes (2). Option 3 ends the patch. If they request changes, update micro-spec and re-run self-review.

"Yes" / "approve" / "proceed" / "1" after this gate counts as micro-spec approval only — not branch or workspace confirmation. If the user bundles other permissions in the same message (e.g. "yes, reset STATE.md"), handle each permission separately; micro-spec approval still does not skip §3.

After micro-spec approval (§3): send the patch workspace gate from branch-gate.md (Workspace ready + options 1–3) in a separate message — do not reuse the micro-spec gate template or freeform confirm phrases.

3. Session and workspace gate (required)

Follow flow-shared/references/session-gate.md then flow-shared/references/branch-gate.md (resolve via path resolver in flow/SKILL.md).

Order:

1. Session gate — if STATE shows active unrelated work (occupied phase, not done), stop before any STATE write; send session gate only.
2. Branch/workspace by checkout:
   • main/master: send branch-gate On main menu (1 branch here / 2 worktree). Stop until user picks 1 or 2.
   • Feature branch, phase: done or no STATE: send branch-gate Continuing on current feature branch (patch) numbered menu only — do not send unrelated switch/worktree 1/2 menu or freeform "reply continue/yes/work here". Stop until user picks 1, 2, or 3 (or names a branch with 3).
   • Feature branch, active unrelated lane (after session gate if needed): follow session outcome — worktree via worktree-setup.md, or resume; do not invent a new branch without user approval.

Do not in the same turn: create/switch branches, create worktrees, update STATE, or start implementation (Task 1, code edits, TDD steps).

Forbidden rationalizations: "User said yes", "micro-spec approved", "unrelated topic needs new branch", "work here" means switch branch here", "feature branch off main is obvious", "STATE reset permission covers workspace" — none of these satisfy this gate.

After confirmation:

• Patch workspace pick 1 (or continue / yes / same branch / work here on the patch continuing gate): no git switch -c; record workspace: in-place, branch: = current branch in docs/flow/STATE.md
• On main menu pick 1, or patch workspace pick 3, or user named a new branch: create or switch in current workspace; workspace: in-place
• On main menu pick 2, patch workspace pick 2, or session gate option 2: follow flow-shared/references/worktree-setup.md

Update phase: patch in docs/flow/STATE.md, then proceed to step 4.

4. Save micro-spec and artifact commit (required)

After branch/workspace confirmation — before Task 1 or TDD:

1. Save the approved micro-spec to:

docs/flow/patches/YYYY-MM-DD-<topic>.md

Use the same markdown structure as the inline micro-spec (Problem, Success criteria, Files, Out of scope, Testing, tasks).

2. Record patch: path in docs/flow/STATE.md.

3. Read and follow flow-shared/references/artifact-commit-gate.md (resolve via path resolver in flow/SKILL.md) — commit brainstorm (if any) and patch file on the confirmed feature branch. Include brainstorm: from STATE when present.

If resuming with artifacts already committed on the branch, skip to step 5.

5. Inline execution (per task)

Implement in this session — do not dispatch an implementer subagent. User should see edits and test runs live.

Read flow-shared/references/tdd-red-green.md (resolve via path resolver in flow/SKILL.md).

Hard gate — per task

NO TASK N+1 UNTIL TASK N SPEC ✅ AND CORRECTNESS ✅ APPROVED

Applies to every task including Task 2 onward on multi-task micro-specs (e.g. code-review follow-ups). Task 1 completing both reviews does not waive reviews on later tasks.

End-of-lane verify runs after all tasks pass this gate. Verify does not replace per-task spec or correctness review.

Continuous patch execution means continue this gate sequence without handoffs — not skip reviews, not batch commits then "catch up" reviews once.

One task at a time. One reviewer role at a time.

Task N gate (all steps required, in order):

  [ ] 1. Inline TDD — micro-spec steps 1–4 (RED → verify RED → implement → verify GREEN)
  [ ] 2. Self-review
  [ ] 3. Spec compliance reviewer    → ✅
  [ ] 4. Correctness reviewer        → ✅ Approved
  [ ] 5. Commit (micro-spec step 5)
  [ ] 6. Mark Task N complete in TodoWrite and `- [x]` for Task N in the patch file

Only then start Task N+1 step 1.

Stop until — before every Task N (including N ≥ 2): Re-read this gate checklist. Confirm which step you are on. If you cannot point to spec ✅ and correctness ✅ Approved for Task N−1, do not start Task N TDD or mark Task N in_progress.

Rationalization	Response
"Same pattern as Task 1 — skip reviews on 2–5"	Every task gets full dual review; pattern reuse is not an exception
"Code-review follow-up / review-fix patch — verify covers it"	Verify is additional; per-task diff reviews are mandatory
"Tests pass / TodoWrite complete — good enough"	Tests and TodoWrite do not waive spec or correctness
"Spec ✅ — start next task; correctness can wait"	Forbidden — one role at a time; both reviews before Task N+1
"User said keep going / finish the patch"	Continue gates, not skip them
"Task 5 is test-only — skip backfill on 2–4"	No task-size exception; backfill missing reviews before new work
"Combined branch review instead of per-task"	Branch review is verify menu option 2 — not a patch shortcut
"Review-fix from verify option 2 — parent review covers this patch"	Parent branch review does not carry forward; each task gets spec + correctness
"Implement all tasks, one commit at the end"	Forbidden — one commit per task after that task's reviews
"Diff-review subagent at end = per-task reviews"	End-of-patch subagent is not spec or correctness reviewer per task

For each task:

1. Mark task in_progress in TodoWrite

2. Follow each micro-spec step exactly; run verifications as specified (Step 2 must show RED failure before Step 3)

3. Self-review before dispatching reviewers:

   • All task requirements implemented, nothing extra (YAGNI)
   • Tests verify real behavior, not mocks
   • TDD cycle followed (watched test fail before implementing)
   • Names clear; files focused
   • No task step touches anything under micro-spec Out of scope

4. Record BASE_SHA (commit before task) and HEAD_SHA (current). SHAs are diff anchors only — for git diff BASE..HEAD; never git checkout a SHA (detached HEAD). Dispatch spec compliance reviewer — read flow-shared/prompts/spec-reviewer.md (resolve via path resolver in flow/SKILL.md); paste full task text + micro-spec context + both SHAs. Loop: fix inline → refresh HEAD_SHA → re-review until ✅

   Forbidden: Approving from your own implementer report without an independent diff review. Passing tests do not replace spec review.

   Do not start step 5 or the next task until spec review is ✅.

5. Refresh HEAD_SHA if fixes landed after spec review. Reuse BASE_SHA. Dispatch correctness reviewer (task mode) — read flow-shared/prompts/correctness-reviewer.md (resolve via path resolver in flow/SKILL.md). Reviewer returns Block / Fix / Suggest. Loop until ✅ Approved:

   • Block or Fix present: fix inline → refresh HEAD_SHA → return to spec compliance review on the updated diff → then rerun correctness
   • Suggest only: ✅ Approved — Suggest is advisory, do not block Reviewers do not edit code.

   Any code change after spec compliance approval invalidates that approval. Do not rerun correctness alone after a Block/Fix cleanup, even when the cleanup was requested by the correctness reviewer and tests pass.

   Do not commit, mark complete, or start the next task until reviewer returns ✅ Approved.

6. Commit per micro-spec task Step 5 — on the user-confirmed feature branch only. One commit per task (or as the micro-spec specifies). Refresh HEAD_SHA after commit.

7. Mark task completed in TodoWrite and - [x] for Task N in docs/flow/patches/… (only after step 6)

Forbidden: Starting Task N+1 TDD while Task N is still in spec or correctness review — even if tests pass or the user says keep going.

Forbidden: Marking a task complete in TodoWrite or - [x] in the patch file before spec ✅, correctness ✅ Approved, and commit — checklist must not get ahead of the gate.

Forbidden: Marking a task complete or starting the next task with uncommitted changes from that task — commit per micro-spec Step 5 first.

Forbidden: Batching inline work for tasks 2–5 then backfilling reviews once, or only reviewing Task 1.

Fixes after ❌: orchestrator implements fixes inline, then re-dispatches the reviewer — reviewers do not edit code.

Stop when blocked, ambiguous, or verify steps complete and user menu presented. Do not guess.

6. Verify (auto-run)

When all micro-spec tasks are complete, immediately continue into verify — do not hand off or wait for the user to invoke /flow-verify.

Pre-verify checkpoint (required): Count tasks N in the micro-spec. Confirm N task commits on the feature branch since the artifact commit (or as the micro-spec specifies). If work is bundled into fewer commits, or any task lacks spec ✅ and correctness ✅ evidence → backfill reviews and split commits per task before step 1 below.

1. Read flow-verify/SKILL.md and flow-shared/references/verify-gate.md (resolve via path resolver in flow/SKILL.md)
2. Follow verify-gate process — full test suite, requirements checklist against micro-spec
3. Update docs/flow/STATE.md: phase: verify when starting (per verify-gate)
4. If verify fails → route to /flow-debug if root cause is unclear, or reopen/create a reviewed patch task for same-topic fixes. The fix must run spec compliance and correctness review, then commit, before verify is rerun. Do not present the done menu while verify is failing
5. If verify passes → present the verify user menu per verify-gate.md

Before presenting the menu: on the feature branch, run git status. If there are uncommitted changes from any task → do not claim patch or verify complete. Commit per micro-spec task Step 5, then re-run verify steps 2–5.

Do not run verify option 2 (branch review) automatically — only when the user chooses it from the menu.

Forbidden: Stopping with a "Run /flow-verify" handoff when patch tasks succeeded.

Forbidden: Presenting ad hoc "next steps" or a custom merge/PR menu — use the exact verify user menu from verify-gate.md (numbered options 1–4). Manual QA notes may appear above the menu, not instead of it.

Redirect rules

• User scope grows during patch → stop and switch to /flow-spec
• Path or mirror layout needs a full tree → /flow-spec
• Root cause unclear → /flow-debug first

Red flags — never

• Treat micro-spec "yes" as branch/workspace confirmation — §2 and §3 are separate gates; send workspace menu only after micro-spec approval
• Propose a branch/workspace and start Task 1 in the same turn — workspace gate requires waiting for user reply
• Create a worktree for unrelated work without offering workspace choice
• Send execute-style switch/worktree 1/2 menu on a feature branch when phase: done or no STATE — use patch continuing gate; stay on current branch unless user opts into isolation
• Send freeform workspace confirm ("reply continue/yes/work here") instead of the numbered patch workspace gate
• Map "work here" to switching to a proposed new branch — on patch continuing gate option 1 means stay on current branch
• Skip micro-spec approval or branch/workspace confirmation
• Skip spec or correctness review — including when the user says the patch is tiny, done, or keep going
• Skip reviews after Task 1 on multi-task micro-specs because later tasks look repetitive or small
• Mark TodoWrite or patch - [x] before reviews + commit — only mark complete after spec ✅, correctness ✅, and commit
• Mark TodoWrite complete before both reviews ✅ — gate order beats checklist momentum
• Treat full verify as substitute for per-task spec + correctness reviews
• Batch tasks 2–5 then backfill reviews — forbidden; each task completes the full gate before the next
• Proceed without re-reading §5 hard gate before each Task N (including N ≥ 2)
• Rerun only correctness after correctness-review fixes — any changed diff needs spec compliance again before correctness can approve
• git checkout <commit-sha> — detaches HEAD; commits miss the feature branch. Stay on the branch name; use SHAs only in git diff
• Trust self-review or passing tests instead of dispatching reviewers
• Skip artifact commit before Task 1 when flow artifact files exist uncommitted on the branch
• Dispatch implementer subagent (patch is inline only)
• Hand off verify instead of running it after all tasks complete
• Fix verify failures with unreviewed inline edits — same-topic fixes need a reviewed patch task before verify can pass
• Replace the verify user menu with custom next steps — merge/PR/iterate lists are not substitutes for options 1–4
• Claim patch or verify complete with uncommitted changes on the feature branch — commit per micro-spec task Step 5 first