ideation

Ideation

Transform unstructured brain dumps into structured, actionable implementation artifacts through a confidence-gated workflow.

Critical: Use AskUserQuestion Tool

ALWAYS use the AskUserQuestion tool when asking clarifying questions. Do not ask questions in plain text. The tool provides structured options and ensures the user can respond clearly.

Use AskUserQuestion for:

• Clarifying questions during confidence scoring (Phase 2)
• Project name confirmation before writing artifacts
• Contract approval
• Workflow choice (PRDs vs straight to specs)
• Phase review feedback before spec generation
• Any decision point requiring user input

Workflow Pipeline

INTAKE → CODEBASE EXPLORATION → CONTRACT FORMATION → PHASING → SPEC GENERATION → HANDOFF
              ↓                        ↓                  ↓            ↓               ↓
         Understand              confidence < 95%?    PRDs or     Repeatable?    Analyze deps
         existing code                ↓               straight      ↓               ↓
                                 ASK QUESTIONS        to specs?   Template +    Sequential?
                                      ↓                           per-phase     Parallel?
                                 (loop until ≥95%)                deltas        Agent Team?

Phase 1: Intake

Accept whatever the user provides:

• Scattered thoughts and half-formed ideas
• Voice dictation transcripts (messy, stream-of-consciousness)
• Bullet points mixed with rambling
• Topic jumping and tangents
• Contradictions and unclear statements
• Technical jargon mixed with vague descriptions

Don't require organization. The mess is the input.

Acknowledge receipt and begin analysis. Do not ask for clarification yet.

Anti-Sycophancy Rules

These rules apply during intake analysis (Phase 1) and contract formation (Phase 3). The goal is to challenge weak premises before they become expensive specs.

Banned Phrases

Do not say these during analysis or contract formation:

• "That's an interesting approach" — take a position instead
• "There are many ways to think about this" — pick one and state why
• "You might want to consider..." — say "This is wrong because..." or "This works because..."
• "That could work" — say whether it WILL work based on available evidence
• "I can see why you'd think that" — if the premise is weak, say it's weak and why

Required Behaviors

• Take a position on every brain dump. After analyzing the input, state what you think is strong and what's weak. Don't just extract signals — evaluate them.
• Challenge vague demand. If the brain dump says "users want X" without evidence, push back: "What evidence supports this? Who specifically wants it?"
• Name undefined terms. If the brain dump uses vague terms ("better UX", "more intuitive", "cleaner"), demand specifics: "What does 'better' mean here? Faster? Fewer clicks? Different layout?"
• Flag hypothetical users. If no concrete user or use case is named, note it as a gap during confidence scoring. "Developers will love this" is not evidence.
• Score conservatively when pushback reveals gaps. If challenging the brain dump exposes vague or missing justification, lower the relevant confidence dimension. Don't inflate scores to compensate for a well-written but unsubstantiated brain dump.

Phase 2: Codebase Exploration

Before scoring confidence or generating any artifacts, understand the existing codebase. This is critical — specs written without understanding existing patterns, architecture, and conventions will be generic and wrong.

2.1 Determine if Exploration is Needed

Exploration is needed when:

• The brain dump references existing code, features, or systems
• The project directory contains source code (not a greenfield project)
• The user mentions extending, modifying, or integrating with existing functionality

Skip exploration for greenfield projects with no existing code.

2.2 Explore the Codebase

Use the Agent tool with subagent_type: "Explore" or direct Glob/Grep/Read to understand:

1. Project structure — What frameworks, languages, and patterns are in use?
2. Relevant existing code — What modules/files relate to the brain dump's scope?
3. Conventions and patterns — How are similar features implemented? What abstractions exist?
4. Testing patterns — How is the codebase tested? What infrastructure exists?
5. Configuration and build — What tools, package managers, and CI/CD are in use?
6. Feedback infrastructure — What fast-feedback tools exist? Test runner config, dev server setup, storybook, API testing scripts, CI shortcuts. These directly inform feedback loop design in specs: if the project has Storybook, prefer it as the UI playground; if it has a test runner with watch mode, use that for the inner-loop command. See references/feedback-loop-guide.md for the full infrastructure-to-playground mapping.

2.3 Record Findings

Retain exploration context for use in later phases. These inform:

• Confidence scoring — better understanding of the problem space
• Contract — realistic scope boundaries based on actual architecture
• Specs — "Pattern to follow" references, accurate file paths, correct abstractions

Do not write exploration findings to files. They're context for the ideation process, not an artifact.

Phase 3: Contract Formation

3.1 Analyze the Brain Dump

Extract from the raw input + codebase exploration:

1. Problem signals: What pain point or need is being described?
2. Goal signals: What does the user want to achieve?
3. Success signals: How will they know it worked?
4. Scope signals: What's included? What's explicitly excluded?
5. Contradictions: Note any conflicting statements
6. Codebase constraints: What does the existing architecture enable or limit?

3.2 Calculate Confidence Score

Read references/confidence-rubric.md for detailed scoring criteria.

Score conservatively. When uncertain between two levels, choose the lower one. One extra round of questions costs minutes; a bad contract costs hours. Do not inflate scores to move forward faster.

Score each dimension (0-20 points):

Dimension	Question
Problem Clarity	Do I understand what problem we're solving and why it matters?
Goal Definition	Are the goals specific and measurable?
Success Criteria	Can I write tests or validation steps for "done"?
Scope Boundaries	Do I know what's in and out of scope?
Consistency	Are there contradictions I need resolved?

Total: /100 points

3.3 Confidence Thresholds

Score	Action
< 70	Major gaps. Ask 5+ questions targeting lowest dimensions.
70-84	Moderate gaps. Ask 3-5 targeted questions.
85-94	Minor gaps. Ask 1-2 specific questions.
≥ 95	Ready to generate contract.

3.4 Ask Clarifying Questions

When confidence < 95%, MUST use AskUserQuestion tool to ask clarifying questions. Structure questions with clear options when possible.

Using AskUserQuestion effectively:

• Provide 2-4 options per question when choices are clear
• Use multiSelect: true when multiple answers apply
• Keep question headers short (max 12 chars)
• Include descriptions that explain implications of each choice

Question strategy:

• Target the lowest-scoring dimension first
• Be specific, not open-ended
• Offer options when possible ("Is it A, B, or C?")
• Reference what was stated ("You mentioned X, did you mean...?")
• Limit to 3-5 questions per round
• After each round, recalculate confidence

See references/confidence-rubric.md for question templates by dimension and best practices.

3.5 Generate Contract

When confidence ≥ 95%, generate the contract document.

1. Use AskUserQuestion to confirm project name if not obvious from context
2. Convert to kebab-case for directory name
3. Create output directory: ./docs/ideation/{project-name}/
4. Check for prior contract (lineage detection):
   • Check if ./docs/ideation/{project-name}/contract.md already exists
   • If it does, read its Created date and rename it to contract-{created-date}.md
   • Set the new contract's Supersedes field to the renamed file path
   • If no prior contract exists, set Supersedes to "None"
5. Write contract.md using references/contract-template.md
6. Use AskUserQuestion to get approval:

Question: "Does this contract accurately capture your intent?"
Options:
- "Approved" - Contract is accurate, proceed
- "Needs changes" - Some parts need revision
- "Missing scope" - Important items are not captured
- "Start over" - Fundamentally off track, re-analyze

If not approved: Revise the contract based on feedback. Do not re-score confidence unless the feedback reveals a fundamental misunderstanding — in that case, return to Phase 3.2 and re-score. Otherwise, edit contract.md directly and re-present for approval. Iterate until approved.

Do not proceed until contract is explicitly approved.

Phase 4: Phasing & Specification

After contract is approved, determine phases and generate specs. PRDs are optional.

4.1 Choose Workflow

Use AskUserQuestion to ask:

Question: "How should we proceed from the contract?"
Options:
- "Straight to specs" — Recommended for technical projects.
  Contract defines what, specs define how. Faster.
- "PRDs then specs" — Recommended for large scope or cross-functional
  teams. Adds a requirements layer for stakeholder alignment.

4.2 Determine Phases

Regardless of PRD choice, analyze the contract and break scope into logical implementation phases.

Small-project shortcut: If the scope is small enough to implement in a single phase (1-3 components, touches fewer than ~10 files), skip phasing entirely. Generate a single spec.md (no phase number needed) and proceed directly to handoff. Not every project needs multiple phases — don't force structure where simplicity suffices.

Phasing criteria (for multi-phase projects):

• Dependencies (what must be built first?)
• Risk (tackle high-risk items early)
• Value delivery (can users benefit after each phase?)
• Complexity (balance phases for consistent effort)

Typical phasing:

• Phase 1: Core functionality / infrastructure
• Phase 2+: Features, enhancements, additional integrations
• Phase N: Future considerations

Detect repeatable patterns: If 3+ phases follow the same structure with different inputs (e.g., "add SDK support for {language}"), note this — it affects how specs are generated (see 4.4).

4.3 Generate PRDs (only if user chose "PRDs then specs")

For each phase, generate prd-phase-{n}.md using references/prd-template.md.

Include:

• Phase overview and rationale
• User stories for this phase
• Functional requirements (grouped)
• Non-functional requirements
• Dependencies (prerequisites and outputs)
• Acceptance criteria

Present all PRDs for review. Use AskUserQuestion:

Question: "Do these PRD phases look correct?"
Options:
- "Approved" - Phases and requirements look good, proceed to specs
- "Adjust phases" - Need to move features between phases
- "Missing requirements" - Some requirements are missing or unclear
- "Start over" - Need to revisit the contract

Iterate until user explicitly approves.

4.4 Generate Implementation Specs

Generate specs using references/spec-template.md. How specs are generated depends on whether phases are repeatable:

Standard phases (each is unique)

For each phase, generate a full spec-phase-{n}.md with:

• Technical approach
• File changes (new and modified)
• Implementation details with code patterns
• Testing requirements
• Error handling
• Validation commands
• Feedback strategy (top-level inner-loop command and playground type)
• Per-component feedback loops (where applicable)

Reference existing code: When the codebase exploration (Phase 2) identified relevant patterns, include "Pattern to follow: path/to/similar/file.ts" in the spec's implementation details. This gives the executing agent concrete examples to follow.

Designing feedback loops: For each iterative component, define a playground (environment to interact with), experiment (parameterized check), and check command (fastest single validation). Match the feedback mechanism to the component type — data layers use tests, UI uses dev server, APIs use curl scripts, config/types skip loops entirely. See references/feedback-loop-guide.md for the full component-type mapping and design criteria.

Naming failure modes: For each non-trivial component, ask: "How would this fail?" Fill in the spec's Failure Modes table with named failures, data shadow paths (nil, empty, stale data), and edge cases (concurrent access, oversized input, missing permissions). The goal is not exhaustive error handling — it's ensuring the spec has no blind spots. Components that are trivial (config, types, constants) skip failure mode enumeration, same as feedback loops.

Repeatable phases (3+ phases follow the same pattern)

When multiple phases share the same structure (e.g., "add support for {SDK}"), avoid generating N nearly-identical full specs. Instead:

1. Generate one full template spec — spec-template-{pattern-name}.md — with detailed implementation steps, using placeholders for the variable parts.

2. Generate lightweight per-phase delta files — spec-phase-{n}.md — containing only:

   • Phase-specific inputs (e.g., language name, package manager, framework)
   • Deviations from the template (what's different about this phase)
   • Any phase-specific concerns or edge cases
   • Reference to the template: "Follow spec-template-{pattern-name}.md with the inputs below"

Example for SDK integrations:

spec-template-sdk-integration.md:

# SDK Integration Template

## Pattern
For each SDK, create:
1. `src/{language}/{language}-installer-agent.ts` — FrameworkConfig following existing pattern
2. `skills/workos-{sdk-name}/SKILL.md` — Agent skill fetching SDK README
3. `tests/fixtures/{language}/{framework}-example/` — Minimal project fixture
4. `tests/evals/graders/{language}.grader.ts` — Extending BaseGrader

## Implementation Details
{Detailed steps with {placeholders} for variable parts}

## Validation
{Common validation steps}

spec-phase-5.md:

# Spec: Ruby SDK (workos-ruby)

**Template**: ./spec-template-sdk-integration.md

## Inputs
- Language: Ruby
- Framework: Rails
- Package manager: Bundler (`bundle add`)
- Manifest file: Gemfile
- SDK package: workos
- Detection: `rails` gem in Gemfile or `config/routes.rb` exists

## Deviations from template
- Rails has strong conventions — files go in specific locations
- Initializer pattern: `config/initializers/workos.rb`
- Env vars: `.env` with dotenv-rails, or Rails credentials

## Phase-specific concerns
- CI needs Ruby 3.x installed for eval fixtures

This approach:

• Saves significant context window space
• Makes the per-phase differences obvious
• Avoids copy-paste errors across specs
• Makes it easy to update the shared pattern in one place

4.5 Present Phases for Review

Whether using PRDs or straight-to-specs, present the phase breakdown and specs for user approval before proceeding to handoff.

Before presenting specs, evaluate feedback loop quality using the Spec Feedback Quality checklist from references/confidence-rubric.md. Self-review each spec:

• Strong: All iterative components have feedback loops, inner-loop command defined, trivial components correctly skipped → present spec as-is
• Adequate: Most components have loops but some gaps → present spec with a note about what's missing
• Weak: No Feedback Strategy section, or complex components missing loops entirely → revise spec before presenting

If Weak, fix the gaps first. Don't present a spec without feedback loops for its iterative components.

Use AskUserQuestion:

Question: "Do these specs look correct?"
Options:
- "Approved" - Specs look good, proceed to execution handoff
- "Adjust approach" - Implementation strategy needs changes
- "Missing components" - Some files or steps are missing
- "Revisit phases" - Phase breakdown needs restructuring

If not approved, revise the relevant specs based on feedback and re-present. Iterate until approved.

Phase 5: Execution Handoff

After specs are generated, create task list, analyze orchestration options, and hand off for implementation.

5.1 Analyze Orchestration Strategy

Do not create tasks during ideation handoff — they are ephemeral and will be lost when the user starts a fresh session. Each /execute-spec session creates its own granular implementation tasks.

Analyze the phase dependency graph to determine the best execution strategy.

Detect parallelizable phases:

• Examine which phases are blocked by what
• If 2+ phases share the same single blocker (e.g., all blocked only by Phase 1), they are parallelizable
• If phases form a linear chain (Phase 2 → Phase 3 → Phase 4), they are sequential
• Mixed graphs have both parallel and sequential segments

Determine recommended strategy:

Pattern	Recommendation
All phases sequential (chain)	Sequential execution — one session at a time
2+ independent phases	Agent team — lead orchestrates teammates in parallel
Mixed dependencies	Hybrid — sequential for dependent chain, agent team for independent group

5.2 Write Execution Plan to Contract

Append the ## Execution Plan section to the contract file (./docs/ideation/{project-name}/contract.md). This makes the contract fully self-contained — someone can pick it up cold and know exactly how to execute.

Use the Execution Plan section from the contract template. Fill in:

1. Dependency Graph — ASCII art showing which phases block which. Keep it simple.
2. Execution Steps — ordered list with the exact /execute-spec commands. Mark which are sequential vs parallel.
3. Agent Team Prompt — only if 2+ phases are parallelizable. Ready-to-paste prompt for delegate mode. Omit this subsection entirely for fully sequential projects.

Shared file detection: Before writing the agent team prompt, scan spec files' "Modified Files" sections. If multiple specs modify the same files, include a coordination note in the prompt:

Coordinate on shared files ({list}) to avoid merge conflicts —
only one teammate should modify a shared file at a time.

Batching: If more than 5 parallelizable phases, note in the execution steps to start with the highest-priority batch first.

5.3 Present Handoff Summary

After writing the execution plan, present a brief conversational summary.

Always include:

Ideation complete. Artifacts written to `./docs/ideation/{project-name}/`.

The contract includes the full execution plan — dependency graph,
commands, and agent team prompt (if parallel). Open `contract.md`
to pick up implementation from any session.

Then show the first step — either the first /execute-spec command for sequential execution, or a pointer to the agent team prompt in the contract for parallel execution.

Agent team context (include when the execution plan has an agent team prompt):

The agent team prompt is in the contract's Execution Plan section.
To use it: start a new Claude Code session, enter delegate mode
(Shift+Tab), and paste the prompt from the contract.

Agent teams let a single lead session automatically spawn and coordinate multiple teammates — the user starts one claude session, and the lead handles spawning, task assignment, plan approval, and synthesis. No manual terminal juggling.

Why delegate mode? Pressing Shift+Tab restricts the lead to coordination-only tools: spawning teammates, messaging, managing tasks, and approving plans. This prevents the lead from implementing tasks itself and ensures work is distributed to teammates.

Why one session? The lead automatically spawns each teammate as a separate Claude Code instance. Each teammate gets its own context window, loads project context (CLAUDE.md, MCP servers, skills), and works independently. You interact with the lead and it coordinates everything — use Shift+Up/Down to message individual teammates if needed.

Ensure agent teams are enabled in .claude/settings.json or ~/.claude/settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

5.4 Why Fresh Sessions?

• Ideation consumes significant context (contract, specs, exploration)
• Execution benefits from clean context focused on the spec
• Human review between phases catches issues early
• Each phase is independently committable
• Each session creates granular implementation tasks scoped to that phase

Output Artifacts

All artifacts written to ./docs/ideation/{project-name}/:

contract.md                        # Lean contract (problem, goals, success, scope)
prd-phase-1.md                     # Phase 1 requirements (only if PRDs chosen)
...
spec-phase-1.md                    # Phase 1 implementation spec (always full)
spec-template-{pattern}.md         # Shared template for repeatable phases (if applicable)
spec-phase-{n}.md                  # Per-phase delta referencing template (if repeatable)
...

Bundled Resources

References

• references/contract-template.md - Template for lean contract document
• references/prd-template.md - Template for phased PRD documents
• references/spec-template.md - Template for implementation specs
• references/confidence-rubric.md - Detailed scoring criteria for confidence assessment and spec feedback quality
• references/feedback-loop-guide.md - Component-type mapping and design criteria for spec feedback loops
• references/workflow-example.md - End-to-end workflow walkthrough

Examples

Completed artifact examples for reference when generating output:

• examples/contract-example.md - A filled-in contract for a bookmark feature
• examples/prd-example.md - A filled-in PRD for the same feature (Phase 1)
• examples/spec-example.md - A filled-in spec for the same feature

When generating artifacts, reference these examples for tone, structure, and level of detail.

Important Notes

• ALWAYS use AskUserQuestion tool for clarifications and approvals. Never ask questions in plain text.
• Explore the codebase before scoring confidence (unless greenfield).
• Score confidence conservatively. When uncertain, score lower.
• Never skip the confidence check. Don't assume understanding.
• Always write artifacts to files. Don't just display them.
• Each phase should be independently valuable.
• Specs should be detailed enough to implement without re-reading PRDs or the contract.
• Keep contracts lean. Heavy docs slow iteration.
• Reference existing code patterns in specs — "Pattern to follow" with real file paths.
• Use template + delta for repeatable phases — don't generate N identical specs.
• Small projects don't need phases. If scope is 1-3 components, generate a single spec.