ideation

name	ideation
description	Transform raw brain dumps (dictated freestyle) into structured implementation artifacts. Use when user has messy ideas, scattered thoughts, or dictated stream-of-consciousness, or when they want to plan a feature, spec something out, or turn rough ideas into actionable specs. Produces contracts and implementation specs written to ./docs/ideation/{project-name}/.

Ideation

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

Critical: Structured Questions at Decision Points

At every decision point, ask the user with structured options. If the ask_user_question tool is available, use it — it provides a TUI with selectable options. Otherwise, present numbered options in plain text.

Structured questions are required 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        Subagents?

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.

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 subagent tool to run the scout agent, or explore directly with grep/find/read/bash 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%, ask clarifying questions with structured options.

Effective question format (applies to both ask_user_question tool and plain text):

• Provide 2-4 options per question when choices are clear
• Note when multiple answers apply
• Keep questions focused and specific
• 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. 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. Write contract.md using references/contract-template.md
5. Ask the user for 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

Ask the user:

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:

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.

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"

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.

Ask the user:

Do these specs look correct?

1. **Approved** - Specs look good, proceed to execution handoff
2. **Adjust approach** - Implementation strategy needs changes
3. **Missing components** - Some files or steps are missing
4. **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, analyze orchestration options and hand off for implementation.

5.1 Analyze Orchestration Strategy

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	Parallel subagents — use /chain or /parallel commands
Mixed dependencies	Hybrid — sequential for dependent chain, parallel 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 /skill:execute-spec commands. Mark which are sequential vs parallel.
3. Parallel Execution Commands — only if 2+ phases are parallelizable. Ready-to-use /chain or /parallel commands for pi-subagents. Omit this subsection entirely for fully sequential projects.

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

Coordinate on shared files ({list}) to avoid merge conflicts —
only one subagent 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
and commands. Open `contract.md` to pick up implementation from
any session.

Then show the first step — either the first /skill:execute-spec command for sequential execution, or the /chain//parallel command for parallel execution.

Parallel execution context (include when the execution plan has parallel phases):

For parallel phases, use pi-subagents:

  /chain scout "analyze codebase" -> worker "execute spec-phase-2.md" -> reviewer "review"
  /parallel worker "execute spec-phase-3.md" -> worker "execute spec-phase-4.md"

Each subagent gets its own context window and works independently.

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

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

• Ask clarifying questions at every decision point with structured options.
• 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.