idea git:20260719.c80ca98A

Immutable. This exact content is served forever at /api/v1/blob/46515b9f2e4505bb.

---
name: idea
description: >
  Use when exploring a new idea before writing formal specifications. Guides users through iterative
  discovery, research, and critical analysis to crystallize vague ideas into validated requirement
  drafts. Includes anti-pseudo-requirement checks, competitive research, demand evidence gathering,
  and "What if we don't build this?" analysis. Supports pause/resume across sessions, stores ideas
  in the project's ideas/ directory, and graduates validated ideas into the spec-forge auto
  chain (idea → decompose → tech-design + feature specs).
instructions: >
  Follow the workflow below exactly. This is an interactive, multi-session skill.
  Ideas are stored in the project's ideas/ directory. By default, suggest adding ideas/
  to .gitignore, but the user can choose to commit them for team collaboration.
  CRITICAL: Do not let ideas graduate without demand validation. A "ready" idea must
  have evidence that it solves a real problem, not just a "sounds cool" feeling.
---

# Idea — Brainstorming & Demand Validation

Explore, research, validate, and crystallize ideas through iterative sessions before committing to formal specification. **Every idea must prove it's a real need before graduating.**

## Core Principles

1. **Brainstorm freely, validate ruthlessly**: Early sessions are open and creative; later sessions demand evidence
2. **Non-linear**: Ideas evolve through multiple sessions, not in one sitting
3. **Research-driven**: Use web search, competitive analysis, and user evidence to ground ideas in reality
4. **Anti-pseudo-requirement**: Before graduating, every idea must answer "What happens if we don't build this?" — if the answer is "nothing significant", the idea is not ready
5. **Persistent**: Every session is recorded, nothing is lost
6. **Project-local**: Ideas live in the project's `ideas/` directory, close to the codebase and docs they relate to

## Storage Structure

> **`ideas/` is a top-level directory at the project root, separate from `docs/`. Never nest it inside `docs/`.**

```
{project-root}/
├── ideas/                          # Brainstorming workspace (TOP-LEVEL, not under docs/)
│   ├── {idea-name}/
│   │   ├── state.json              # Status, metadata, and validation checklist
│   │   ├── sessions/
│   │   │   ├── overview.md         # Session index: chronological order, summaries
│   │   │   ├── explore-initial-spark.md    # First session
│   │   │   ├── research-competitors.md     # Second session
│   │   │   ├── validate-demand.md          # Third session
│   │   │   └── ...
│   │   ├── research/
│   │   │   ├── competitors.md      # Competitive landscape analysis
│   │   │   └── market-notes.md     # Market research, user evidence, data points
│   │   └── draft.md                # Evolving summary (auto-updated after each session)
│   └── ...
├── docs/                           # Formal spec documents (PRD, SRS, etc.)
└── .gitignore                      # Add "ideas/" if you want to keep them private
```

### .gitignore Guidance

On first run, if `ideas/` does not exist, ask the user:
- **Add to .gitignore (Recommended)** — ideas are personal working notes, keep them local
- **Commit to Git** — share brainstorming with the team for collaboration
- **Decide later** — create the directory now, handle .gitignore manually

## Session Types

Each return session, the user chooses a focus. The idea matures through these phases:

| Phase | Focus | Key Activities |
|-------|-------|---------------|
| **Explore** | Diverge, discover | Brainstorm, free association, "what if" thinking |
| **Research** | Investigate, evidence | Competitive analysis, market research, user pain points |
| **Validate** | Challenge, prove | Anti-pseudo-requirement checks, demand evidence, feasibility |
| **Refine** | Converge, sharpen | MVP scope, success criteria, draft polishing |

Phases are not strictly sequential — users can revisit any phase at any time. But an idea cannot reach `ready` status without completing the Validate phase.

## Session Overview File

Each idea maintains a `sessions/overview.md` that tracks all sessions in chronological order. This file is the single source of truth for session ordering — filenames do NOT encode sequence.

**Create this file when the first session is recorded. Update it after every subsequent session.**

```markdown
# Session Overview — {idea-name}

> Chronological index of brainstorming sessions.
> Updated: {date}

## Sessions

| # | Session | Type | Date | Summary |
|---|---------|------|------|---------|
| 1 | [explore-initial-spark](./explore-initial-spark.md) | Explore | {date} | {one-line summary} |
| 2 | [research-competitors](./research-competitors.md) | Research | {date} | {one-line summary} |
| 3 | [validate-demand](./validate-demand.md) | Validate | {date} | {one-line summary} |
| ... | ... | ... | ... | ... |
```

**Rules:**
- The `#` column is the chronological order (for human readability only — NOT part of the filename)
- Append new sessions at the bottom
- Never reorder or renumber existing entries

## Workflow

### Step 1: Initialize or Resume

#### 1.1 Ensure Base Directory

**IMPORTANT: `ideas/` MUST be at the project root — the same level as `docs/`, NOT inside it.**
- Correct: `{project-root}/ideas/`
- Wrong: `{project-root}/docs/ideas/`

Check if `ideas/` exists in the project root. If not:
1. Create the `ideas/` directory at the project root
2. Ask the user about .gitignore preference (see .gitignore Guidance above)
3. If user chooses to gitignore, add `ideas/` to `.gitignore`

#### 1.2 Parse Idea Name

Extract idea name from arguments. Convert to kebab-case.

If no name provided, list existing ideas. To gather them, prefer `python3 "<sf_scripts>/sf-scan.py" --root "<project_root>" --docs-only` (resolve `<sf_scripts>` per `@../shared/scripts.md`) — its `documents` include each idea draft with its type and status; fall back to reading each `ideas/*/state.json` by hand if `python3` is unavailable or the script is not found.

```
Your Ideas:

  # | Idea            | Status     | Validated | Sessions | Last Updated
  1 | cool-feature    | refining   | Yes       | 5        | 2026-02-10
  2 | payment-system  | exploring  | No        | 1        | 2026-02-14
  3 | ai-assistant    | ready      | Yes       | 7        | 2026-02-12

Actions:
  Enter a number to resume that idea
  Enter a new name to start brainstorming
```

Use `AskUserQuestion` to let the user choose.

#### 1.3 Check Existing State

Check if `ideas/{idea-name}/` exists:

**New idea** (directory doesn't exist):
- Create directory structure: `state.json`, `sessions/`, `research/`, `draft.md`
- Initialize `state.json`:
  ```json
  {
    "idea": "{idea-name}",
    "status": "exploring",
    "created": "{ISO timestamp}",
    "updated": "{ISO timestamp}",
    "session_count": 0,
    "draft_version": 0,
    "validation": {
      "problem_evidence": null,
      "demand_evidence": null,
      "competitive_analysis": false,
      "not_build_analysis": null,
      "validated": false
    }
  }
  ```
- Proceed to Step 2 (New Idea)

**Existing idea**:
- Read `state.json`
- If `status` is `graduated`: inform user this idea has already moved to formal specs, ask if they want to start a new variant
- If `status` is `ready`: ask if they want to continue refining, or graduate now
- If `status` is `exploring`, `researching`, or `refining`: read `draft.md` to restore context, proceed to Step 3 (Continue Session)

### Step 2: New Idea — Opening Exploration

This is the first session for a brand new idea. The goal is to understand the user's raw thinking AND begin planting seeds of critical analysis.

#### 2.1 Open-Ended Discovery

Use `AskUserQuestion` with open questions. **Ask only what you cannot already infer** from the idea draft (if one exists) or the context the user has given — a single rich answer may satisfy several Draft Validation Checklist dimensions at once. Do NOT march through a fixed sequence; pull from the optional prompt bank below in whatever order fits the conversation, asking a few at a time and adapting follow-ups, and stop once you can fill in the draft.

The prompts below are grouped by theme for convenience — they are **optional prompts, not a locked sequence of rounds.** Skip any whose answer you already have.

**The Spark:**
- What's the idea? Describe it however you like (one sentence or a paragraph)
- What triggered this idea? (a pain point you experienced, something you saw, a user complaint, data you noticed?)

**The Problem:**
- What specific problem does this solve? Can you describe a concrete scenario where someone suffers without this?
- Who suffers from this problem? How often? How severely?
- What happens if this is NOT built? (Plant this question early — it's the core anti-pseudo-requirement check)

**The Landscape:**
- What existing solutions have you seen? (competitors, workarounds, manual processes)
- What do they get wrong? Why are they insufficient?
- If good solutions exist, why build another one?

**The Shape:**
- What would the simplest version look like? (MVP)
- What are you most uncertain about?

Do NOT force answers. If the user says "I don't know yet" — record it as an open question that needs research.

#### 2.2 Initial Demand Signal Assessment

Based on the user's answers, provide an honest initial assessment:

```
Initial Demand Signal:

  Problem clarity:     [Clear / Vague / Unknown]
  Evidence of demand:  [Strong / Weak / None yet]
  Existing solutions:  [None / Inadequate / Good (risk!)]
  Differentiation:     [Clear / Unclear / Not yet defined]

  Suggested next session focus: [Research / Explore more / Validate]
```

Be honest. If the idea sounds like a solution looking for a problem, say so gently:
> "The idea is interesting, but I notice we haven't identified who specifically suffers from this problem. In a future session, it would help to research concrete user pain points."

#### 2.3 Record Session

Write the session to `ideas/{idea-name}/sessions/{type}-{slug}.md` (e.g., `explore-initial-spark.md`):

**Session filename rules:**
- Format: `{session-type}-{brief-slug}.md` where type is one of: `explore`, `research`, `validate`, `refine`
- The slug is a 2-4 word kebab-case description of the session focus (e.g., `initial-spark`, `competitors`, `demand-check`, `mvp-scope`)
- Do NOT use sequential numbers (`001.md`, `002.md`, etc.) — chronological order is tracked in `sessions/overview.md`
- If a type repeats (e.g., two explore sessions), differentiate by slug: `explore-initial-spark.md`, `explore-new-angles.md`

**Session filename:**

```markdown
# Session 1 — {date}
## Type: Exploration

## Context
{Where this idea came from, what triggered it}

## Key Points
- {Bullet points of main ideas discussed}

## Problem Definition
- **Who suffers**: {who}
- **How they suffer**: {pain description}
- **Current workaround**: {what they do today}

## Demand Signal
- Problem clarity: {Clear/Vague/Unknown}
- Evidence: {what evidence exists or is needed}

## Decisions
- {Any decisions made, even tentative ones}

## Open Questions
- {Things still uncertain or needing research}

## Research Needed
- {Specific research tasks identified for next session}

## Raw Notes
{Full Q&A exchange, preserving the user's original words}
```

#### 2.4 Generate Initial Draft

Create `draft.md`:

```markdown
# {Idea Name}

> Status: Exploring | Draft v1 | {date}

## One-Liner
{One sentence description}

## Problem
{What problem this solves — be specific about who suffers and how}

## Target Users
{Who would use this — be specific, not "everyone"}

## Core Concept
{How it would work at a high level}

## Existing Solutions & Gaps
{What exists today, why it's insufficient}

## MVP Scope
{Simplest useful version — or "not yet defined"}

## Demand Validation Status
- [ ] Problem backed by evidence (not just assumption)
- [ ] Target users identified and reachable
- [ ] Existing solutions analyzed (competitors, workarounds)
- [ ] "What if we don't build this?" answered convincingly
- [ ] At least one form of demand evidence (user complaints, data, research)

## Open Questions
- {List of unresolved questions}

## Research Backlog
- {Things to investigate in future sessions}

## Session History
- [{date}] explore-initial-spark — {one-line summary}
```

#### 2.5 Update State and Wrap Up

Update `state.json`: `session_count: 1`, `updated: now`, `draft_version: 1`

Display:

```
Idea saved: {idea-name}
  Location: ideas/{idea-name}/
  Status: exploring
  Sessions: 1
  Validated: No

Suggested next session: {Research / Continue exploring}
  /spec-forge:idea {idea-name}

When validated and ready:
  /spec-forge {idea-name}         Start full spec chain
```

### Step 3: Continue Session — Iterative Development

The user is returning to an existing idea.

#### 3.1 Restore Context

Read `draft.md` and display a concise summary:

```
Resuming idea: {idea-name}
  Status: {status} | {session_count} sessions | Last: {last_date}
  Validated: {Yes/No}

Current summary:
  {One-liner from draft.md}

Validation status:
  [x] Problem backed by evidence
  [ ] Competitive analysis done
  [ ] "What if we don't build this?" answered
  ...

Open questions:
  - {question 1}
  - {question 2}

Research backlog:
  - {research item 1}
```

#### 3.2 Choose Session Focus

Use `AskUserQuestion`:
- **Explore** — I have new thoughts or want to brainstorm further
- **Research** — Let's investigate the market, competitors, or user needs
- **Validate** — Challenge assumptions, check if this is a real need
- **Refine** — The direction is clear, let's sharpen the draft
- **Graduate** — This idea is validated and ready for formal specification
- **Park** — Set aside for now

#### 3.3a: Explore Session

Open-ended brainstorming, similar to Step 2 but adaptive:
- Address open questions from previous sessions
- Explore new angles the user hasn't considered
- Challenge assumptions: "You mentioned X — have you considered Y?"
- Explore alternatives: "What if instead of A, you did B?"
- "What's the worst version of this that would still be useful?"
- "What would make you NOT use this product?"

Record as new session. Update `draft.md` with new insights.

#### 3.3b: Research Session

**This is where the idea gets grounded in reality.** Use `WebSearch` and critical analysis.

##### Competitive Analysis

Use `WebSearch` to research:
1. Direct competitors (same problem, same solution approach)
2. Indirect competitors (same problem, different approach)
3. Adjacent solutions (different problem, similar technology)

For each competitor found, analyze:
- What they do well
- What they do poorly
- Their pricing model
- Their target users
- Why our idea is different (or is it?)

Write findings to `research/competitors.md`:

```markdown
# Competitive Analysis — {idea-name}
> Last updated: {date}

## Direct Competitors
### {Competitor 1}
- **What they do**: ...
- **Strengths**: ...
- **Weaknesses**: ...
- **Why we're different**: ...

## Indirect Competitors / Workarounds
### {Alternative approach}
- ...

## Key Takeaway
{Is there a real gap in the market? Or is this already well-served?}
```

##### Market & Demand Research

Use `WebSearch` to find:
- How many people search for solutions to this problem?
- Forum posts, Reddit threads, Stack Overflow questions about this pain point
- Industry reports or blog posts discussing this need
- Any data on market size or growth

Write findings to `research/market-notes.md`.

##### User Evidence Gathering

Ask the user:
- Have you or anyone you know experienced this problem firsthand?
- Do you have access to user feedback, support tickets, or analytics that show this need?
- Can you point to specific user quotes, complaints, or feature requests?

**Be rigorous**: "I think users want this" is not evidence. Evidence is:
- User interviews or surveys
- Support ticket patterns
- Usage analytics showing friction points
- Community discussions (forums, social media)
- Competitor reviews mentioning gaps

Record all findings in the session file. Update `draft.md` with research results. Update `state.json` validation fields. Change status to `researching` if not already.

#### 3.3c: Validate Session

**The critical session that separates real needs from pseudo-requirements.**

Run through the Demand Validation Checklist with the user:

##### Check 1: Problem Evidence
> "What concrete evidence do we have that this problem exists and is painful enough to justify a solution?"

Rate: **Strong** (data, user quotes, patterns) / **Moderate** (anecdotes, logical reasoning) / **Weak** (assumption only)

If Weak: flag it. "This is still an assumption. Before going further, we need to find evidence. What's the cheapest way to validate this?"

##### Check 2: "What Happens If We Don't Build This?"

> "Imagine we decide not to build this. What happens?"

Possible answers and their implications:
- "Users keep suffering with workarounds" → **Real need** — but how painful are the workarounds? Are they acceptable?
- "A competitor will beat us to it" → **Competitive pressure** — but is this a race worth running? What if the competitor also fails?
- "Nothing really changes" → **RED FLAG: Pseudo-requirement.** This idea may not be worth building.
- "We miss a business opportunity" → **Opportunity cost** — quantify it. How big is the opportunity?

##### Check 3: Target User Reality
> "Who concretely would use this in the first week — can you name 3-5 specific people or types, or point to a stronger demand signal in their place?"

The goal is evidence quality, not hitting a headcount. Naming 3-5 concrete early adopters is one way to pass; a single strong demand signal (a paying-customer waitlist, a pile of support tickets, a signed LOI) can pass on its own even when naming individuals is awkward. If neither concrete adopters nor a strong signal exists, the target user definition is too vague.

##### Check 4: Differentiation Test
> "If a user is already using {competitor/workaround}, why would they switch to this?"

Switching cost is real. The new solution must be significantly better, not just slightly different.

##### Check 5: Simplicity Test
> "Can you explain what this does in one sentence to someone outside the industry?"

If not, the concept may be too complex or poorly defined.

##### Validation Verdict

After all checks, provide an honest assessment:

```
Validation Summary:

  Problem evidence:    [Strong / Moderate / Weak]
  "Not build" impact:  [Significant / Moderate / Low]
  Target users:        [Concrete / Vague]
  Differentiation:     [Clear / Unclear]
  Simplicity:          [Pass / Needs work]

  Overall: [VALIDATED / NEEDS WORK / NOT VALIDATED]
```

**VALIDATED**: Weighing the five checks as dimensions to reason about — not a rigid all-must-hit-Moderate tally — the evidence quality is strong enough to proceed. A single dimension backed by a strong demand signal can carry a softer answer elsewhere, but no amount of enthusiasm substitutes for problem evidence → idea can proceed to `ready`

**NEEDS WORK**: Some checks are Weak → specific guidance on what to research or rethink next

**NOT VALIDATED**: Core checks fail (no problem evidence, no impact if not built) → honest conversation:
> "Based on our analysis, this idea doesn't yet have strong evidence of real demand. That doesn't mean it's a bad idea — it means it needs more validation before committing resources to formal specification. Here's what I suggest..."

Update `state.json` validation fields and draft.md.

#### 3.3d: Refine Session

Available only after validation passes. Shift to convergent thinking:
- Review each section of `draft.md` with the user
- Finalize MVP scope — ruthlessly cut anything non-essential
- Define preliminary success criteria (measurable)
- Identify technical constraints or risks
- Prepare the draft for handoff to `/spec-forge:tech-design` (or the full chain via `/spec-forge`)

Update `draft.md` to a polished version. Change status to `refining`.

When the draft has:
- Clear, evidence-backed problem statement
- Defined, reachable target users
- Concrete MVP scope
- No critical open questions
- Validation checklist complete

→ Suggest changing status to `ready`.

#### 3.3e: Graduate

**Pre-graduation check**: Verify `validation.validated` is `true` in `state.json`. If not:

> "This idea hasn't completed demand validation yet. Graduating without validation risks building something nobody needs. Would you like to run a validation session first, or graduate anyway (not recommended)?"

If user insists on graduating without validation, record it in state:
```json
{ "validation": { "validated": false, "graduated_without_validation": true } }
```

If validated, update `state.json`:
```json
{ "status": "ready" }
```

Display:

```
Idea '{idea-name}' is ready for formal specification!

  Validation: Passed
  Draft: ideas/{idea-name}/draft.md

To start the spec chain:
  /spec-forge {idea-name}         Full chain (Idea → Decompose → Tech Design + Feature Specs)

Optional (on-demand):
  /spec-forge:prd {idea-name}     PRD (for stakeholders)
  /spec-forge:srs {idea-name}     SRS (for compliance/audit)
  /spec-forge:test-cases {idea-name} Test cases with coverage matrix
```

Note: The actual `graduated` status is set by the `/spec-forge` chain command after it successfully generates the tech-design.

#### 3.3f: Park

Update `state.json`: set `status: 'parked'`, update `updated` timestamp. Display:

```
Idea '{idea-name}' parked.
  Everything is saved. Come back anytime:
  /spec-forge:idea {idea-name}
```

#### 3.4 Record Session and Update

- Write session to `sessions/{type}-{slug}.md` (use session type + descriptive slug, NOT sequential numbers)
- Create or update `sessions/overview.md` to append the new session entry (see Session Overview below)
- Update `draft.md` with any new content
- Update `research/` files if research was conducted
- Update `state.json`: `session_count`, `updated`, `draft_version`, `status`, `validation`

## Status Definitions

| Status | Meaning |
|--------|---------|
| `exploring` | Early stage, divergent thinking, brainstorming |
| `researching` | Investigating market, competitors, user needs |
| `refining` | Direction clear and validated, converging on specifics |
| `ready` | Validated and ready for formal specification |
| `graduated` | Tech Design has been generated from this idea |
| `parked` | Intentionally set aside, can resume anytime |

## Draft Validation Checklist

An idea cannot reach `ready` status without these being addressed:

- [ ] **Problem backed by evidence** — not just "I think this is needed"
- [ ] **Target users identified** — specific, reachable people, not "everyone"
- [ ] **Competitive analysis done** — know what exists, why it's insufficient
- [ ] **"What if we don't build this?" answered** — impact must be significant
- [ ] **Demand evidence exists** — at least one concrete data point (user quotes, analytics, market data, community signals)
- [ ] **Differentiation clear** — why switch from existing solutions
- [ ] **MVP scope defined** — simplest useful version, not the dream version

## Notes

1. **Project-local**: Ideas are stored in the project's `ideas/` directory. Users can add `ideas/` to `.gitignore` for privacy, or commit for team collaboration.
2. **Honest Assessment**: Unlike pure brainstorming, this skill is designed to kill bad ideas early. A "NOT VALIDATED" result saves weeks of wasted development. Be honest, not encouraging.
3. **Session Preservation**: Every session is a separate file named `{type}-{slug}.md`. Never overwrite or merge sessions — they are the historical record of how the idea evolved. Chronological order is tracked in `sessions/overview.md`, not in filenames.
4. **Research Artifacts**: The `research/` directory preserves competitive analysis and market research. This data feeds directly into the PRD's market analysis and competitive sections.
5. **Draft Evolution**: `draft.md` is the living document that evolves. Old versions are implicitly preserved in the session history.
6. **Anti-Pseudo-Requirement**: This principle carries through the entire spec-forge chain. It starts here at the idea stage, is reinforced in the PRD (demand evidence, feasibility verdict), and is traced through SRS and Tech Design.