# Spec Driven Brainstorm

> Discuss and brainstorm a spec-driven change from a rough idea, then propose a change name and, after explicit confirmation, generate the same five proposal artifacts as spec-driven-propose.

- Skill: `kw12121212/spec-driven-brainstorm` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add kw12121212/spec-driven-brainstorm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kw12121212/spec-driven-brainstorm/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: kw12121212 (https://skillmd.com/u/kw12121212)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kw12121212/spec-driven-brainstorm

---


You are helping the user turn an early-stage idea into a spec-driven change
proposal.

## This Skill's Commands

If you cannot remember the exact command used by this skill, look it up here
before running anything. Do not guess.

```yaml
propose: node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>
verify: node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>
```

## Prerequisites

The `.spec-driven/` directory must exist at the **project root**. Before
proceeding, verify:
```
ls .spec-driven/
```
If this fails, the project is not initialized. Run `/spec-driven-init` first.

## Steps

1. **Start from the idea, not the artifact list** — ask the user what they want
   to achieve, what problem they are trying to solve, and any known constraints
   or preferences. Do not require a change name up front.

2. **Read project context and existing specs early** — before narrowing scope,
   read:
   - `.spec-driven/config.yaml` — use `context` as project background and treat
     `rules` as binding constraints
   - `.spec-driven/specs/INDEX.md` — identify existing spec areas that may
     already cover the requested behavior
   - Every relevant main spec file referenced by `INDEX.md` that appears related
     to the idea being discussed

3. **Brainstorm until the change is decision-ready** — use the discussion to
   converge on:
   - the desired outcome and user-visible behavior
   - what is in scope and explicitly out of scope
   - important tradeoffs, constraints, risks, and unchanged behavior
   - which existing spec files will likely be modified, or whether a new spec
     area is needed
   - any questions that still need a human answer before implementation

4. **Suggest the change name** — once the idea is coherent enough, propose a
   short kebab-case change name. If the user already provided a valid name, keep
   it. If not, suggest one that reflects the agreed change scope.

5. **Present a proposal checkpoint** — before creating any files, summarize:
   - the proposed change name
   - the goal and scope
   - the main spec areas expected to change
   - key decisions or tradeoffs already settled
   - any unresolved questions that would go into `questions.md`

   Then ask for explicit confirmation. If the user wants revisions, continue the
   brainstorm and re-summarize until confirmed.

6. **Scaffold the change after confirmation** — run:
   ```
   node {{SKILL_DIR}}/scripts/spec-driven.js propose <name>
   ```
   This creates `.spec-driven/changes/<name>/` with the seeded templates.

7. **Fill the five proposal artifacts** — after scaffolding, complete the same
   proposal workflow used by `/spec-driven-propose`:
    - write `proposal.md` with **What**, **Why**, **Scope**, and
      **Unchanged Behavior**
    - write `design.md` with **Approach**, **Key Decisions**, and
      **Alternatives Considered**
    - populate `changes/<name>/specs/` with delta spec files aligned by path with
      the main `.spec-driven/specs/` structure
      - mirror the main spec path exactly, for example
        `.spec-driven/specs/skills/planning.md` becomes
        `.spec-driven/changes/<name>/specs/skills/planning.md`
      - use this canonical sample as the format target:

        ```markdown
        ---
        mapping:
          implementation:
            - path/to/implementation.ts
          tests:
            - test/path/to/test.ts
        ---

        ## ADDED Requirements

        ### Requirement: new-capability
        The system MUST provide <observable behavior>.

        #### Scenario: success
        - GIVEN <precondition>
        - WHEN <action>
        - THEN <result>

        ## MODIFIED Requirements

        ### Requirement: existing-capability
        Previously: The system MUST <old behavior>.
        The system MUST <new behavior>.

        ## REMOVED Requirements

        ### Requirement: old-capability
        Reason: This behavior is removed because <reason>.
        ```
      - omit sections that do not apply instead of leaving blank placeholders
      - if the change has no observable spec impact, leave `changes/<name>/specs/`
        empty rather than creating a prose-only delta file
      - Do not invent `mapping.implementation` or `mapping.tests` paths when the
        repository evidence is unclear
    - include `mapping.implementation` and `mapping.tests` frontmatter in delta
      spec files when related files are knowable from repository context
    - write `tasks.md` using this canonical structure:

      ```markdown
      # Tasks: <change-name>

      ## Implementation
      - [ ] Describe the first atomic implementation task
      - [ ] Describe the second atomic implementation task

      ## Testing

      - [ ] Run `npm run lint` — lint or validation task
      - [ ] Run `npm test` — unit test task

      ## Verification
      - [ ] Verify implementation matches proposal scope
      ```

      Each task uses `- [ ]` checkboxes and should be independently completable.

      The `## Testing` section MUST satisfy these verification keyword requirements:
      - At least one task MUST contain a lint/validation keyword: `lint`, `validate`,
        `validation`, `typecheck`, `type-check`, or `build`
      - At least one task MUST contain a unit test keyword: `unit test` or `unit tests`
      - Both tasks MUST name an explicit runnable command in backticks or use a known
        runner (npm, pnpm, yarn, bun, node, bash, sh, pytest, jest, vitest, go, cargo,
        make, uv, poetry)
      - Paraphrasing these keywords (e.g. "run tests" instead of "run unit tests") will
        cause `verify` to fail

      If the relevant command cannot be determined confidently from repository context,
      record that in `questions.md` instead of guessing.
   - write `questions.md`, recording every unresolved point under `## Open`, or
     leave `<!-- No open questions -->` if nothing is unclear

8. **Validate before presenting the proposal** — run:
   ```
   node {{SKILL_DIR}}/scripts/spec-driven.js verify <name>
   ```
   - Fix any safe artifact-format issues immediately and rerun `verify`
   - If only open questions remain, treat that as expected at proposal time and
     surface those questions clearly
   - If any non-question error remains, stop and report it instead of presenting
     the proposal as ready

9. **Hand off like propose** — show the user the generated artifacts, summarize
   the final proposed scope, and list any open questions that must be answered
   before `/spec-driven-apply`.

10. **Offer auto hand-off** — after the hand-off, ask the user whether to enter
    `/spec-driven-auto` to execute the proposal end-to-end, or continue modifying
    the proposal with `/spec-driven-modify`. Do not auto-enter auto without the
    user's explicit choice.

## Rules

- Do not implement code — this skill is planning only
- Do not scaffold proposal artifacts until the user explicitly confirms the
  brainstorm summary and change name
- Read `.spec-driven/config.yaml`, `INDEX.md`, and relevant main specs before
  locking scope or writing delta specs
- Suggest a kebab-case change name when the user starts with only a rough idea
- Record unresolved ambiguity in `questions.md`; do not guess silently
- If testing commands are not knowable from repository context, record that in
  `questions.md` instead of inventing them
- After confirmation, follow the same artifact-writing and validation standard as
  `/spec-driven-propose`
- Keep implementation and test mappings in spec frontmatter, not in requirement
  prose