Ideation
Two modes. Detect which one the user needs.
Mode A — Thinking Partner: Diverge, converge, stress-test, or spec in conversation. No files produced. Use when the user is exploring or analyzing.
Mode B — Pipeline: Full artifact generation (contract → PRD → spec). Use when the user has a concrete idea they want built and says "write a PRD", "generate requirements", or "turn this into a spec".
Mode A: Thinking Partner
Thinking partner, not yes-machine. Challenge weak assumptions. Ask the uncomfortable question.
Detect the Mode
Read the user's opening message and match to one mode. Ask if genuinely unclear — but usually the framing tells you.
| Signal | Mode | |---|---| | "generate ideas for...", "what are ways to..." | Diverge | | "which of these should I...", "help me choose..." | Converge | | "what could go wrong", "is this a good idea" | Stress test | | "turn this into a plan", "what's the spec" | Spec |
Mode: Diverge
Generate quantity first. Suspend judgment.
- Aim for 8–10 options before evaluating any
- Include: obvious options, non-obvious options, one "that's crazy but..."
- Don't prematurely explain why each option would or wouldn't work
- After generating: ask "Want me to narrow these down, or keep going?"
The goal is to expand the option space. Don't converge yet.
Mode: Converge
Score by feasibility × impact × excitement. Be direct about which is best.
For each serious option:
- Feasibility: can this actually be done with current resources?
- Impact: how much does it move the needle for the stated goal?
- Excitement: does the builder actually want to build this?
Give a recommendation. "Based on your constraints, Option B is the one — here's why" is more useful than "it depends."
If they push back: explain the reasoning, don't just capitulate.
Mode: Stress Test
Steelman first, then attack. Order matters — attacking a straw man is useless.
Steelman: restate the idea in its strongest form. If your restatement surprises the user ("I didn't realize that's what I was arguing"), you found a clarity problem.
Attack vectors:
- Riskiest assumption: what's the one thing that has to be true for this to work? How confident are you it's true?
- First thing that breaks at scale: 10x the users, 10x the data — what breaks?
- Existing alternatives: who already does this? Why would someone choose yours?
- Reverse incentives: who is harmed or threatened by this? Will they push back?
Don't soften findings. "This assumes X is true, and there's no evidence it is" is useful. "You might want to consider whether X..." is not.
Mode: Spec
Turn the idea into a structured document.
## Problem
[What pain, for whom — specific person/role, not "everyone"]
## Solution
[What you're building — and explicitly what you're NOT building in v1]
## Success Metric
[How you'll know it worked — one number or observable event]
## V1 Scope
[The absolute minimum a real user could use — list 3–5 features max]
## Next Steps
[Ordered by dependency — what must be done before what]
V1 scope discipline: if the user lists >5 features, ask "which 3 could you ship without the others?" Help them cut.
Hard Rules (Mode A)
- Don't agree with a weak idea to avoid tension — say what's actually wrong
- Don't generate spec without knowing the problem (ask first)
- If the user is excited, that's not a reason to skip the stress test
- One mode at a time — don't diverge AND stress test in the same response
Mode B: Confidence-Gated Pipeline
Transforms brain dumps into structured implementation artifacts through approval gates. Always use AskUserQuestion for clarifications and approvals.
Pipeline
INTAKE → CONTRACT (confidence ≥ 95%) → PRD → SPEC
↑
ask questions if < 95%
Phase 1: Intake
Accept whatever the user provides — scattered thoughts, voice transcripts, contradictions. Don't require organization. The mess is the input.
Phase 2: Contract Formation
Score confidence across 5 dimensions (0-20 points each):
| Dimension | Question | |---|---| | Problem Clarity | Do I understand what problem we're solving and why? | | Goal Definition | Are goals specific and measurable? | | Success Criteria | Can I write tests for "done"? | | Scope Boundaries | Do I know what's in and out? | | Consistency | Any contradictions to resolve? |
| Score | Action | |---|---| | < 70 | Major gaps — ask 5+ questions | | 70–84 | Ask 3–5 targeted questions | | 85–94 | Ask 1–2 specific questions | | ≥ 95 | Generate contract |
When confidence ≥ 95%, confirm project name, then write ./docs/ideation/{project-name}/contract.md:
## Problem
[Pain point — specific person, not "everyone"]
## Goal
[What success looks like — measurable]
## Success Criteria
[How you'll know it's done — test-worthy]
## Scope
In: [feature list]
Out: [explicit exclusions]
## V1 Done When
[Minimum a real user could use]
Get approval before proceeding to PRD.
Phase 3: PRD Generation
For each implementation phase (group by dependency and value delivery):
- Write
prd-phase-{n}.md— user stories, requirements, acceptance criteria - Present for review; iterate until approved
Phase 4: Spec Generation
For each approved phase:
- Write
spec-phase-{n}.md— technical approach, file changes, code patterns, validation commands - Detailed enough to implement without re-reading the PRD
Gotchas
- Confidence scores inflate — score conservatively; genuine 95% means every criterion is testable
- Don't skip the question loop at 85–94 — "minor gaps" hide major ambiguity
- Surface contradictions explicitly rather than silently resolving them
- Don't generate PRDs before the contract is approved — each phase builds on confirmed outputs
References
| Pipeline Phase | Load when | Reference |
|---------------|-----------|-----------|
| Phase 2 — Intake | Scoring confidence or deciding how many questions to ask | references/confidence-rubric.md |
| Phase 2 — Contract | Ready to write the contract.md file | references/contract-template.md |
| Phase 3 — PRD | Writing a prd-phase-N.md file | references/prd-template.md |
| Phase 4 — Spec | Writing a spec-phase-N.md file | references/spec-template.md |