Plan

request-devflow-plan:plan

Produce a complete DevFlow plan folder through reconnaissance and interview. Reference files live in references/ next to this skill. Everything generated — questions, findings, documents, summaries — is written in the user's conversation language; the structures in the references are normative, their language is not.

Flow

Phase 1 — Intake

• Collect the goal statement and all known constraints. If $ARGUMENTS were provided, treat them as intake.
• Ask where the plan folder should live (default docs/<short-name>-plan/).
• If the user states their own quality bar or standards, record them verbatim — the closing review recites them.

Phase 2 — Reconnaissance

Read the target repo before asking anything:

• CLAUDE.md, README.md, package manifests — project shape
• existing docs/SPEC/ and docs/diagrams/ — documentation base
• test framework and scale; run the baseline gates once to confirm testability
• single repo or multi-repo? greenfield or established? (greenfield → Sprint 0 includes foundation work, see references/devflow-distilled.md)
• docs/*/issue-handoff.md from this or earlier plans — every open item folds into intake and must be scheduled or explicitly re-deferred with a reason

Phase 3 — Blindspot pass (before the interview)

From intake plus recon, surface the unknown unknowns: things the user likely has not considered that would change the architecture, data model, or scope. Present them as findings. The decision-bearing ones become the first interview questions; pure fixes fold into the plan directly.

Phase 4 — Interview

Follow references/interview-guide.md:

• One question at a time (a single AskUserQuestion, ≤4 options, one marked recommended)
• Data-model forks first, then permissions/security, deployment/ops, scope boundaries
• Never ask what code evidence or existing convention already answers
• Record every answer immediately into the 02-decisions.md draft
• Close with a wrap-up scan (1–2 catch-up questions)

Phase 5 — Document generation

Split the work into sprints per references/granularity-rules.md (two tiers Phase → Sprint, 4–12 commits per sprint, anti-over-splitting rules) and calibrate ceremony per references/devflow-distilled.md. Then generate the full set per references/plan-templates.md: README, 00-iron-rules, 01-current-state, 02-decisions, one doc per sprint (eight fixed sections), diagram-spec-workflow, final-audit, PROGRESS, implementation-notes, audit-log (empty skeleton), kickoff-prompts (from references/kickoff-templates.md, unit names filled in), maintainer-guide. The plan's last unit is always the built-in acceptance unit — a gate unit with no commits whose spec is the final-audit doc.

While generating:

• Everything is plan specification, not implementation — example-level code at most
• Write each file to disk as it is produced and keep the README doc map current — if the session dies mid-generation, a fresh session resumes by diffing the doc map against the files on disk and regenerating only what is missing
• Update the PROGRESS skeleton as each sprint doc lands
• Define SPEC authority explicitly in the diagram-spec-workflow doc
• Gate blocks use the target repo's native shell and tooling (PowerShell vs POSIX syntax accordingly)

Phase 6 — Closing reviews (mandatory before delivery)

Run all four passes in references/quality-audit.md:

1. Recite-the-standard self-audit plus machine cross-reference checks
2. Junior walkthrough — a day-one engineer follows every sprint doc
3. Blindspot scan — stale premises, exploitable loose wording
4. Fresh-subagent zero-trust re-review — fatal and severe defects must reach 0 before delivery

Phase 7 — Delivery

Output the summary: plan path, file list, sprint count, decision count, total commits — then the Next steps block (see below).

Next steps block (every run ends with one)

Print full, copy-paste-ready command lines — always the complete /request-devflow-plan:<command> <args> form with this plan's actual unit numbers substituted. Shorthand (kickoff sprint 0) and unfilled placeholders (<unit>) in the printed output are both violations. Recommended command first; alternatives after it, each with one line on when to choose it. When the next command must run in a fresh context, print an advisory line — run /clear (or open a new session) first — immediately before the command lines. Example of a correct block after a full plan with sprints 0–4:

Next steps
Run /clear (or open a new session) to empty the context, then:
▶ /request-devflow-plan:kickoff sprint 0        — start the first unit
  /request-devflow-plan:kickoff sprint 0-2      — batch three units, one review at the end
  /request-devflow-plan:kickoff phase 1         — batch a whole phase (plans with phases)

Per mode:

• Full plan → recommend kickoff of the first unit, as above.
• Remediation mode → recommend /request-devflow-plan:kickoff sprint <actual remediation unit number>; second line: after its sign-off run /request-devflow-plan:audit in another fresh session (report -rK).
• Amendment mode → recommend /request-devflow-plan:kickoff sprint <actual next un-executed unit number> — execution continues under the amended plan.

Remediation mode (after a FAIL audit)

When the target repo already has a plan folder whose latest acceptance audit is FAIL — or the user asks to remediate audit findings — run this variant instead of the full flow. The model is deliberately uniform: no defect is ever fixed off the books, no matter how small.

Remediation mode handles FAIL verdicts only — PASS WITH FINDINGS routes its non-blocking findings to issue-handoff.md or GitHub issues (see the audit skill), never here.

1. Read the plan folder, the failing audit report, and audit-log.md. Skip recon already covered by the plan's current-state doc; verify only what the audit contradicts. Root-cause trigger: at the 2nd consecutive FAIL, open with a root-cause interview before anything else — was the previous defect analysis wrong? is a final-audit metric missing? is an upstream locked decision flawed? was it an execution violation? Record the answer in the Decision Log; it shapes the pair.
2. Consolidate ALL blocking defects from the report into ONE remediation unit at the plan's top level (phase N+1 in a phase-structured plan, sprint N+1 in a flat one — numbering always continues). No routing by size: even a one-commit fix travels inside the remediation unit. Scope freezes to the defect list — new finds go to the Deferred Ledger for the next round to judge.
3. Interview only the genuinely new forks the defects expose (same one-question rule) — a fork is new only when no existing D-XX answers it; check the decisions file before asking. Everything else inherits the locked decisions.
4. Generate the document pair:
   • Remediation unit doc (N+1) — full eight-section anatomy. §3 current-state evidence cites the audit defect list (severity, location) plus fresh investigation; §5 commit table covers every defect (a regression fix starts with a red test reproducing it; doc/diagram sync rides the same commit as the behavior it documents; fix forward — history is never rewritten); §6 acceptance = each defect's originally failing metric goes green.
   • Acceptance unit (N+2) — the paired re-acceptance, appended to the unit map and PROGRESS; no new doc (its spec is the final-audit doc plus the delta). A fresh-session zero-trust audit of everything from the first unit through N+1; report suffixed -r2, -r3, ….
5. Update the README unit map, PROGRESS (a normal section for N+1; a verdict entry — report path, verdict, date — for N+2), and append a final-audit delta section (new or changed metrics only).
6. Run the Phase 6 closing reviews scoped to the new and touched documents.
7. Deliver with the loop stated: kickoff N+1 as a normal unit → after sign-off, run N+2 as a fresh audit session → FAIL again → rerun this mode (appends the N+3/N+4 pair) → repeat until an acceptance unit passes. Only then handoff.

Amendment mode (mid-plan scope or decision changes)

When the maintainer wants to change requirements or overturn a locked decision mid-plan — a new want, not a defect:

1. Interview the change only (same one-question rule): what changes, why, and the forks it opens.
2. Supersede, never delete: the overturned decision stays in 02-decisions.md marked "superseded by D-YY"; the new decision records what it replaces. Decision lineage is part of the audit trail.
3. Regenerate only the un-executed sprint docs the change touches; executed work is never rewritten — if the change invalidates shipped behavior, the fix is forward work inside the amended sprints.
4. Propagate: README unit map, final-audit metrics (edits annotated with the amendment), kickoff-prompts unit names, PROGRESS.
5. Re-run the Phase 6 closing reviews scoped to the touched documents — hand-edits that skip this step are exactly how cross-reference drift happens.
6. Log one Decision Log line for the amendment event itself (date, what changed, why).

Never

• Write full implementation code in the plan (example-level only)
• Skip any closing review pass
• Deliver with unresolved fatal defects from the subagent re-review
• Put an undiscussed design decision into the plan as if it had been interviewed