ideation

Ideation: Ideas Into Structured Documents

Help turn rough ideas into structured, validated idea documents through natural collaborative dialogue. Start by understanding the current project context, then ask questions one at a time to refine the idea. Once the idea is clear, present approaches with feasibility evaluation and get user approval.

Do NOT skip to implementation. The purpose of this skill is to produce a well-thought-out idea document that can feed into requirements definition (e.g., USDM) or be tracked as a task. Even if the idea seems simple, unexamined assumptions cause the most wasted work.

Process

Complete these steps in order:

Step 1: Explore Context

Investigate all information sources referenced in the user's input before proceeding.

1a: External References

Scan the user's input for external references — app names, technology names, URLs, specifications, standards, protocols, services, or documents. If any are found:

• URLs: Fetch and read the linked content to understand scope, API surface, constraints, or specifications
• Named technologies/services: Search for official documentation, capabilities, limitations, and integration patterns
• Existing apps or products: Research their features, behavior, and design to understand what the user is referencing
• Standards/protocols: Look up the specification to understand requirements and constraints

Do NOT proceed to Step 2 until all external references are investigated. Misunderstanding an external reference propagates errors into every subsequent step.

1b: Project Context

Review the current project to understand what already exists:

• Check project files, documentation, and recent commits
• Identify existing solutions, patterns, and conventions
• Note constraints, dependencies, and technical boundaries

This grounds the ideation in reality rather than starting from a blank slate.

Step 2: Ask Clarifying Questions

Understand the idea through focused dialogue:

• Ask one question at a time — do not overwhelm with multiple questions
• Prefer multiple choice questions when feasible — easier to answer than open-ended
• Focus on understanding: purpose, target users, constraints, success criteria
• Be ready to revisit earlier questions if new information changes the picture

Continue until you have a clear understanding of what the user wants and why.

Step 3: Propose Approaches

Present 2-3 different approaches with trade-offs:

• Lead with your recommended approach and explain why
• Present options conversationally with reasoning
• Each approach must include a feasibility evaluation:
  • Differentiation: How does this differ from existing solutions?
  • Technical risks and constraints: What could go wrong technically?
  • Pre-mortem: "If this idea fails, what would be the cause?"
• Apply YAGNI — remove unnecessary features from all approaches

Step 4: Present and Validate

Once the user selects an approach (or a combination):

• Present the idea in sections, scaled to complexity
• Ask after each section whether it looks right so far
• Be ready to go back and revise if something does not make sense

Step 5: Write Idea Document

After the user approves the idea, generate the document.

Save to: .docs/ideas/YYYY-MM-DD-<topic>.md

The document must contain these sections:

Section	Content
What	What it does, the problem it solves
Why	Rationale, user benefit, business value
Scope	In scope / out of scope boundaries
Stakeholders	Target users, affected systems
Approaches	The explored alternatives with trade-offs and feasibility evaluation
Decision	The selected approach and rationale

See templates/idea-document.md for the output template.

These sections are structured to serve as input for requirements definition tools (e.g., USDM):

• What maps to Requirements
• Why maps to Reasons
• Scope maps to Descriptions (context, constraints)
• Stakeholders informs scope confirmation

Step 6: Output Selection

After writing the idea document, ask the user which output they want:

Option	Action
A: Markdown only (default)	Save the idea document to .docs/ideas/ — done
B: Markdown + GitHub Issue	Save the document and create a GitHub Issue with the content
C: Markdown + requirements	Save the document and invoke a requirements definition skill (e.g., usdm)

Key Principles

• One question at a time — do not bundle multiple questions in one message
• Multiple choice preferred — easier to answer than open-ended when feasible
• YAGNI ruthlessly — remove unnecessary features from all approaches
• Explore alternatives — always propose 2-3 approaches before settling
• Incremental validation — present sections, get approval, then move on
• Be flexible — go back and clarify when something does not make sense
• Feasibility over optimism — every approach needs honest risk assessment

Credits

This skill is based on the brainstorming skill from obra/superpowers (MIT License).