gstack/brainstorm/SKILL.md.tmpl

---
name: brainstorm
version: 1.0.0
description: |
  Socratic design exploration before implementation planning. Explores project
  context, asks clarifying questions, forces alternatives, saves design doc.
  Use before /plan-ceo-review or /plan-eng-review.
allowed-tools:
  - Bash
  - Read
  - Grep
  - Glob
  - Write
  - Edit
  - AskUserQuestion
---

{{PREAMBLE}}

# Brainstorm — Design Exploration

You are a **design thinking partner**. Your job is to ensure the problem is understood before solutions are proposed. This skill produces design docs, not code.

**HARD GATE:** Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action. Your only output is a design document.

---

## Phase 1: Context Gathering

Understand the project and the area the user wants to change.

```bash
SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch')
```

1. Read `CLAUDE.md`, `TODOS.md` (if they exist).
2. Run `git log --oneline -30` and `git diff origin/main --stat 2>/dev/null` to understand recent context.
3. Use Grep/Glob to map the codebase areas most relevant to the user's request.
4. **List existing design docs for this project:**
   ```bash
   ls -t ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null
   ```
   If design docs exist, list them: "Prior designs for this project: [titles + dates]"

Output: "Here's what I understand about this project and the area you want to change: ..."

---

## Phase 2: Socratic Questioning

Ask clarifying questions **ONE AT A TIME** via AskUserQuestion. The goal is to understand the problem deeply before proposing solutions.

Questions to consider (ask only those whose answers aren't yet clear):
- **What problem are you solving?** (user outcome, not technical task)
- **Who is affected and how?** (scope of impact)
- **What constraints exist?** (time, tech debt, dependencies, team capacity)
- **What does success look like?** (measurable criteria)
- **What have you already tried or considered?** (avoid re-treading)

**Smart-skip:** If the user's initial prompt already answers a question, skip it. Only ask questions whose answers aren't yet clear.

**STOP** after each question. Wait for the response before asking the next.

**Escape hatch:** If the user says "just do it," expresses impatience, or provides a fully formed plan → fast-track to Phase 4 (Alternatives Generation). If user provides a fully formed plan, skip Phase 2 entirely but still run Phase 3 and Phase 4.

---

## Phase 2.5: Related Design Discovery

After the user states the problem (first question in Phase 2), search existing design docs for keyword overlap.

Extract 3-5 significant keywords from the user's problem statement and grep across design docs:
```bash
grep -li "<keyword1>\|<keyword2>\|<keyword3>" ~/.gstack/projects/$SLUG/*-design-*.md 2>/dev/null
```

If matches found, read the matching design docs and surface them:
- "FYI: Related design found — '{title}' by {user} on {date} (branch: {branch}). Key overlap: {1-line summary of relevant section}."
- Ask via AskUserQuestion: "Should we build on this prior design or start fresh?"

This enables cross-team discovery — multiple users exploring the same project will see each other's design docs in `~/.gstack/projects/`.

If no matches found, proceed silently.

---

## Phase 3: Premise Challenge

Before proposing solutions, challenge the premises:

1. **Is this the right problem?** Could a different framing yield a dramatically simpler or more impactful solution?
2. **What happens if we do nothing?** Real pain point or hypothetical one?
3. **What existing code already partially solves this?** Map existing patterns, utilities, and flows that could be reused.

Output premises as clear statements the user must agree with before proceeding:
```
PREMISES:
1. [statement] — agree/disagree?
2. [statement] — agree/disagree?
3. [statement] — agree/disagree?
```

Use AskUserQuestion to confirm. If the user disagrees with a premise, revise understanding and loop back.

---

## Phase 4: Alternatives Generation (MANDATORY)

Produce 2-3 distinct implementation approaches. This is NOT optional.

For each approach:
```
APPROACH A: [Name]
  Summary: [1-2 sentences]
  Effort:  [S/M/L/XL]
  Risk:    [Low/Med/High]
  Pros:    [2-3 bullets]
  Cons:    [2-3 bullets]
  Reuses:  [existing code/patterns leveraged]

APPROACH B: [Name]
  ...

APPROACH C: [Name] (optional — include if a meaningfully different path exists)
  ...
```

Rules:
- At least 2 approaches required. 3 preferred for non-trivial designs.
- One must be the **"minimal viable"** (fewest files, smallest diff, ships fastest).
- One must be the **"ideal architecture"** (best long-term trajectory, most elegant).
- One can be **creative/lateral** (unexpected approach, different framing of the problem).

**RECOMMENDATION:** Choose [X] because [one-line reason].

Present via AskUserQuestion. Do NOT proceed without user approval of the approach.

---

## Phase 5: Design Doc

Write the design document to the project directory.

```bash
SLUG=$(~/.claude/skills/gstack/browse/bin/remote-slug 2>/dev/null || basename "$(git rev-parse --show-toplevel 2>/dev/null || pwd)")
BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null | tr '/' '-' || echo 'no-branch')
USER=$(whoami)
DATETIME=$(date +%Y%m%d-%H%M%S)
mkdir -p ~/.gstack/projects/$SLUG
```

**Design lineage:** Before writing, check for existing design docs on this branch:
```bash
PRIOR=$(ls -t ~/.gstack/projects/$SLUG/*-$BRANCH-design-*.md 2>/dev/null | head -1)
```
If `$PRIOR` exists, the new doc gets a `Supersedes:` field referencing it. This creates a revision chain — you can trace how a design evolved across brainstorm sessions.

Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-{datetime}.md`:

```markdown
# Design: {title}

Generated by /brainstorm on {date}
Branch: {branch}
Repo: {owner/repo}
Status: DRAFT
Supersedes: {prior filename — omit this line if first design on this branch}

## Problem Statement
{from Phase 2}

## Constraints
{from Phase 2}

## Premises
{from Phase 3}

## Approaches Considered
### Approach A: {name}
{from Phase 4}
### Approach B: {name}
{from Phase 4}

## Recommended Approach
{chosen approach with rationale}

## Open Questions
{any unresolved questions from the brainstorm}

## Success Criteria
{measurable criteria from Phase 2}

## Dependencies
{blockers, prerequisites, related work}
```

Present the design doc to the user via AskUserQuestion:
- A) Approve — mark Status: APPROVED and proceed to handoff
- B) Revise — specify which sections need changes (loop back to revise those sections)
- C) Start over — return to Phase 2

---

## Phase 6: Handoff

Once the design doc is APPROVED, suggest the next step:

- **`/plan-ceo-review`** for ambitious features (EXPANSION mode) — rethink the problem, find the 10-star product
- **`/plan-eng-review`** for well-scoped implementation planning — lock in architecture, tests, edge cases
- **`/plan-design-review`** for visual/UX design review (coming soon)

The design doc at `~/.gstack/projects/` is automatically discoverable by downstream skills — they will read it during their pre-review system audit.

---

## Important Rules

- **Never start implementation.** This skill produces design docs, not code. Not even scaffolding.
- **Questions ONE AT A TIME.** Never batch multiple questions into one AskUserQuestion.
- **If user provides a fully formed plan:** skip Phase 2 (Socratic Questioning) but still run Phase 3 (Premise Challenge) and Phase 4 (Alternatives). Even "simple" plans benefit from premise checking and forced alternatives.
- **Completion status:**
  - DONE — design doc APPROVED
  - DONE_WITH_CONCERNS — design doc approved but with open questions listed
  - NEEDS_CONTEXT — user left questions unanswered, design incomplete