issue-to-prd

issue-to-prd

ICM procedure: convert a new GitHub issue into a structured PRD or post clarifying questions.

Invocation

/issue-to-prd {repo} {issue_number}

Example: /issue-to-prd fellowship-dev/pylot 123

When to use

• A new issue arrives and needs structuring (triggered by challenge-new-issue event rule)
• A human answered open-questions and re-challenge fires (triggered by rechallenge-after-answers)
• Manual invocation to structure a specific issue

What it does

11-stage ICM procedure:

1. 00-automation-guard — refuse no-automation / epic / closed issues, before reading anything
2. 01-read-issue — fetch issue data (title, body, labels, comments)
3. 01b-triage-challenge — search for an existing mechanism serving the same need and check the ask against its smallest version → delete-retire / close / re-scope / prd; non-prd stops the pipeline (stages 02-07 skipped)
4. 02-context-completeness — audit implicit context gaps a fresh agent would miss
5. 03-assess-clarity — check against 8-section gap checklist → clear or needs-questions
6. 04-failure-modes — predict how an agent can go astray → guardrails for PRD
7. 05-test-plan — test strategy + prerequisites (pre-merge and post-merge)
8. 05b-prototype-gate — is this UI exploration? → skip / ask / dispatch / picked
9. 05c-outcomes-baseline — detect a causal goal/eval/outcome contract in the issue; only then fetch GET /outcomes/summary for that named metric's baseline (fail-open)
10. 06-ask-or-structure — decision: post questions (exit) OR draft PRD (Measurable Impact included only when a contract exists, else "not applicable")
11. 07-publish — rewrite issue body with PRD, apply labels

Exit paths

• Guard path (stage 00): no reads, no writes, status=success, stops
• Triage path (stage 01b): posts one comment naming the verdict and its cited evidence, applies wontfix or needs-rescope, stops (stages 02-07 skipped) — never fires without a citation
• Questions path (stage 06): posts GH comment, adds open-questions label, stops
• PRD path (stage 07): rewrites issue body, adds prd-ready (+ ready-to-work unless prototype variants are pending)

Prototype variants

Stage 05b can dispatch a mission that pushes proto/<issue>-a|b|c branches and posts one options comment with screenshots and boot instructions, for the owner to pick from. It is gated hard: auto-detection can only ever ask a question; only an explicit owner signal (the prototype-options label, or a "build the prototype" answer) dispatches. See stages/05b-prototype-gate/CONTEXT.md.

Stage handoffs

Each stage writes to its output/handoff.md. Downstream stages read upstream handoffs. All output directories at stages/{stage}/output/.

Execution

Run stages sequentially. Read the CONTEXT.md for each stage before executing it. Stage 00 is a hard gate — if it aborts, run nothing else. Stage 01b is a hard gate — on any verdict but prd, run nothing after it (stages 02-07 skipped). Stage 05c always runs (fail-open) — it never gates stage 06. After stage 06, skip stage 07 if questions were posted.

Reference files

• shared/prd-template.md — PRD structure (used by stage 06); ## Measurable Impact section is conditional on stage 05c's contract verdict
• shared/failure-modes.md — common agent pitfall catalog (used by stage 04)
• shared/prototype-mission-brief.md — self-contained brief for the variant mission (stage 05b)
• stages/03-assess-clarity/references/gap-checklist.md — 8-section checklist
• stages/05b-prototype-gate/references/gate-checklist.md — prototype gate + worked classifications
• stages/05c-outcomes-baseline/CONTEXT.md — causal contract detection + scoped, fail-open baseline formatting