tercel/spec-forge/idea

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:

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.

# 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:

# 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:

# {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: