Ql Brainstorm

1---
2name: ql-brainstorm
3description: "Part of the quantum-loop autonomous development pipeline (brainstorm \u2192 spec \u2192 plan \u2192 execute \u2192 review \u2192 verify). Deep Socratic exploration of a feature idea before implementation. Asks questions one at a time, proposes 2-3 alternative approaches with trade-offs, presents design section-by-section for approval, and saves an approved design document. Use when starting a new feature, exploring an idea, or before writing a spec. Triggers on: brainstorm, explore idea, design this, think through, ql-brainstorm."
4---
5 
6# Quantum-Loop: Brainstorm
7 
8You are conducting a structured design exploration. Your goal is to deeply understand what the user wants to build, explore the solution space, and produce an approved design document. You must NEVER start implementing.
9 
10## Phase 0: Phase-skip check (Phase 18 / P2.4)
11 
12Before asking any question, check whether a prior `/ql-brainstorm` run already covered this exact input:
13 
14```bash
15# Inputs that define "same brainstorm": verbatim user intent + any existing design doc
16INTENT_TEXT=$(jq -r '.userIntent.text // ""' quantum.json 2>/dev/null)
17DESIGN=$(ls docs/plans/*-design.md 2>/dev/null | tail -1)  # most recent if multiple
18ARGS=()
19[[ -n "$INTENT_TEXT" ]] && ARGS+=("inline:$INTENT_TEXT")
20[[ -n "$DESIGN" ]]      && ARGS+=("$DESIGN")
21 
22if bash lib/phase-skip.sh skip brainstorm . "${ARGS[@]}"; then
23  echo "[SKIP] brainstorm is up-to-date — inputs unchanged since last run."
24  echo "Re-reading .handoffs/brainstorm.md for downstream context."
25  bash lib/handoff.sh read brainstorm | jq '.'
26  # Return control to caller. No re-questioning, no design regeneration.
27  exit 0
28fi
29```
30 
31If skip returns non-zero (no record, or any input changed), proceed to Phase 1. After the design is approved and Phase 4c writes the handoff, also record the fingerprint:
32 
33```bash
34FP=$(jq -cn --arg ip "inline://$INTENT_TEXT" --arg ih "$(bash lib/phase-skip.sh inline "$INTENT_TEXT" | tr -d '\n')" \
35            --arg dp "$DESIGN" --arg dh "$(bash lib/phase-skip.sh hash "$DESIGN" | tr -d '\n')" \
36  '{artifacts: [{path: $ip, sha256: $ih}, {path: $dp, sha256: $dh}]}')
37bash lib/phase-skip.sh record brainstorm "$FP" . >/dev/null
38```
39 
40## Phase 0B: Ambiguity gate (Phase 19 / P2.8, OMC deep-interview)
41 
42The skill MUST NOT produce a design doc until the ambiguity score falls below the gate threshold. After each round of questioning (Phase 1), self-assess clarity on three weighted dimensions — goal (40%), constraints (30%), criteria (30%) — each scored 0-10. Compute the composite via `lib/ambiguity.sh`:
43 
44```bash
45# After round N of questioning, self-assess clarity 0-10 on each dimension:
46GOAL_CLARITY=<0-10>        # "Can I state what this feature does in one sentence?"
47CONSTRAINTS_CLARITY=<0-10> # "Can I list every constraint (time/tech/compliance)?"
48CRITERIA_CLARITY=<0-10>    # "Can I list every success / acceptance criterion?"
49 
50SCORE=$(bash lib/ambiguity.sh score "$GOAL_CLARITY" "$CONSTRAINTS_CLARITY" "$CRITERIA_CLARITY")
51MODE=$(bash lib/ambiguity.sh mode "$ROUND" "$SCORE")
52 
53if bash lib/ambiguity.sh gate "$SCORE"; then
54  echo "[AMBIGUITY] score=$SCORE  <20 — gate passes, proceed to Phase 4 (design)."
55else
56  echo "[AMBIGUITY] score=$SCORE  challenge-mode=$MODE — more questions required."
57  # Apply the challenge mode before the next question:
58  #   normal      — continue clarifying questions as usual
59  #   contrarian  — challenge every assumption with an opposing view; force justification
60  #   simplifier  — push "what is the minimum that solves 80% of this?"
61  #   ontologist  — refuse to proceed until every named object has a precise definition
62fi
63```
64 
65**Ontology stability tracking**: each round, extract the substantive tokens from the accumulated Q&A via `bash lib/ambiguity.sh extract "$ROUND_TEXT"`. Diff against the prior round's token set via `bash lib/ambiguity.sh diff "$PRIOR" "$CURRENT"` (emits `{added, removed, carried, stability}`). **Thrashing ontology** (stability < 0.5 for two consecutive rounds) forces the ontologist challenge mode regardless of score, because the vocabulary itself is unstable.
66 
67Record the final score in `.handoffs/brainstorm.md` as part of the Phase 4c handoff write, so downstream skills can verify the gate passed:
68 
69```json
70{
71  "decided":  [...],
72  "ambiguity": { "final_score": 12, "rounds": 4, "final_mode": "normal" },
73  "notes":    "..."
74}
75```
76 
77## Phase 1: Understand the Problem
78 
79Read existing project files for context:
80- Check for CLAUDE.md, package.json, README, or similar files to understand the project
81- Check for existing design docs in `docs/plans/`
82- Check for existing quantum.json to understand any in-progress features
83 
84Then ask clarifying questions to understand the problem space:
85 
86### Question Rules
87- Ask ONE question at a time. Wait for the answer before asking the next.
88- Each question should be multiple-choice when possible (A/B/C/D options).
89- Ask 4-8 questions total, stopping when you have enough clarity.
90- Questions should probe:
91  1. What PROBLEM does this solve? (not what feature to build)
92  2. Who is the USER? What is their current workflow?
93  3. What does SUCCESS look like? How would you measure it?
94  4. What are the CONSTRAINTS? (time, tech stack, existing code, team size)
95  5. What is explicitly OUT OF SCOPE?
96  6. Are there EXISTING solutions that partially solve this?
97  7. LIFECYCLE: What happens beyond the happy path?
98     - A) One-shot tool (run once, get output, done)
99     - B) Returning users (state persists, users come back)
100     - C) Integrates into an existing system (middleware, plugin, library)
101     - D) Multiple of the above
102 
103### What NOT to ask
104- Implementation details (that comes later)
105- Technology choices (explore those in Phase 2)
106- "Should I start implementing?" (NEVER)
107 
108## Phase 2: Explore Approaches
109 
110Based on the answers, propose 2-3 alternative approaches:
111 
112For EACH approach, present:
1131. **Name** -- a short descriptive label
1142. **How it works** -- 2-3 sentences
1153. **Pros** -- bullet list
1164. **Cons** -- bullet list
1175. **Best when** -- scenario where this approach shines
1186. **Risk level** -- Low / Medium / High with one-line explanation
119 
120End with your RECOMMENDATION and why.
121 
122Wait for the user to choose or provide feedback before proceeding.
123 
124## Phase 3: Present Design Section-by-Section
125 
126Present the design in 200-300 word sections. After EACH section, explicitly ask:
127 
128> "Does this section look right? Should I adjust anything before moving on?"
129 
130Sections to present (adapt based on complexity):
131 
1321. **Overview** -- What we're building and why
1332. **User Experience** -- How the user interacts with it (flows, screens, commands)
1343. **Data Model** -- What data structures or schema changes are needed
1354. **Architecture** -- How components connect, what talks to what
1365. **Edge Cases & Error Handling** -- What can go wrong and how we handle it
1376. **Testing Strategy** -- What types of tests, what's critical to test
138 
139### Section Rules
140- Each section must be approved before presenting the next
141- If user requests changes, revise and re-present that section
142- Do NOT combine sections to save time
143- Do NOT present all sections at once
144 
145## Phase 4: Save Design Document
146 
147After all sections are approved, save the complete design to:
148 
149```
150docs/plans/YYYY-MM-DD-<topic>-design.md
151```
152 
153Use kebab-case for the topic. The document should include:
154- All approved sections assembled together
155- A "Next Steps" section pointing to `/quantum-loop:spec` for formal PRD creation
156- Date and any open questions noted during brainstorming
157 
158### Phase 4b: Snapshot user intent (required for ql-intent-check)
159 
160If `quantum.json` exists (the user is extending an in-progress pipeline), and it does NOT already contain a `userIntent` field, write the user's **verbatim first-message text** into `quantum.json.userIntent` as an immutable snapshot. If `quantum.json` does not yet exist, capture the verbatim text into the design doc's front-matter so `/quantum-loop:spec` can propagate it.
161 
162Required shape (see `skills/ql-intent-check/SKILL.md` §"Immutable intent snapshot"):
163 
164```json
165{
166  "userIntent": {
167    "text": "<verbatim first-message text>",
168    "timestamp": "<ISO 8601 at write time>",
169    "source_message_id": null
170  },
171  "userClarifications": []
172}
173```
174 
175**Write rules**:
176- The `text` MUST be the exact verbatim text the user wrote in their first brainstorm turn — no paraphrasing, no summary.
177- If `userIntent.text` is already populated, DO NOT overwrite. This field is immutable.
178- Use `lib/json-atomic.sh` helpers (`write_quantum_json`) to avoid partial-write races.
179 
180Inform the user:
181> "Design saved to `docs/plans/YYYY-MM-DD-<topic>-design.md`. User intent snapshot stored in quantum.json. When you're ready to create a formal spec, run `/quantum-loop:spec`."
182 
183### Phase 4c: Write stage handoff (Phase 15 / P2.3)
184 
185Before exiting, write a stage-handoff document at `.handoffs/brainstorm.md` so downstream skills (`/ql-spec`, `/ql-plan`, `/ql-execute`, reviewers) can read it even after this session's context is compacted.
186 
187Use `lib/handoff.sh`:
188 
189```bash
190bash lib/handoff.sh write brainstorm "$(cat <<'JSON'
191{
192  "decided":   ["<each approved-section decision, verbatim>"],
193  "rejected":  ["<each alternative considered and NOT chosen, with reason>"],
194  "risks":     ["<each risk surfaced during brainstorm>"],
195  "files":     ["docs/plans/YYYY-MM-DD-<topic>-design.md"],
196  "remaining": ["<any open question left for /ql-spec to resolve>"],
197  "notes":     "<free-form tail: unanswered questions, follow-ups>"
198}
199JSON
200)"
201```
202 
203Every downstream skill opens with `bash lib/handoff.sh all | jq '.'` — so any decision you record here is durable even across session boundaries.
204 
205## Phase 4d: Post-exit design-review (P5.B4 / US-006 / v0.6.3 — advisory)
206 
207After Phase 4c writes the brainstorm handoff, run the spec-reviewer in `design-review` mode against the just-saved design doc. The review is **advisory** in v0.6.3 — findings emit to stderr; the skill does NOT abort regardless of what's flagged.
208 
209```bash
210DESIGN_PATH=$(ls docs/plans/*-design.md 2>/dev/null | tail -1)
211 
212# Opt-out gate: QL_SKIP_PRE_IMPL_REVIEW=design (or comma-separated, e.g. design,prd)
213SKIP_LIST="${QL_SKIP_PRE_IMPL_REVIEW:-}"
214if [[ -n "$DESIGN_PATH" ]] && \
215   ! printf '%s' "$SKIP_LIST" | tr ',' '\n' | grep -qx "design"; then
216  echo "[QL-BRAINSTORM] Running spec-reviewer in design-review mode (advisory)..." >&2
217  # Dispatch the spec-reviewer subagent with MODE=design-review and the design doc path.
218  # Findings are emitted to stderr in FINDING_START..FINDING_END format.
219  # The skill continues regardless of what's reported — set QL_SKIP_PRE_IMPL_REVIEW=design
220  # to disable this stage entirely.
221  #
222  # G13 / US-002 (v0.7.0): capture the reviewer stderr, parse FINDING blocks
223  # via lib/finding-synth.sh, and persist the parsed summary + per-run snapshot
224  # via lib/finding-persist.sh. Advisory contract preserved — the skill never
225  # aborts based on findings.
226  REVIEW_LOG=$(mktemp)
227  MODE=design-review DESIGN_PATH="$DESIGN_PATH" \
228    claude --headless "agents/spec-reviewer.md design-review mode against $DESIGN_PATH" \
229      2> "$REVIEW_LOG" || true
230 
231  # Source the parser + persister (no shell flags inherited; libs are flag-free at source).
232  # shellcheck disable=SC1091
233  source lib/finding-synth.sh
234  # shellcheck disable=SC1091
235  source lib/finding-persist.sh
236 
237  findings=$(parse_findings design < "$REVIEW_LOG")
238  summary=$(summarize_findings design "$findings")
239  persist_review_findings design "$DESIGN_PATH" "$summary" "$findings" >/dev/null
240  format_summary_line "$summary" >&2; echo >&2
241 
242  # Surface the reviewer's stderr (so operators still see FINDING blocks).
243  cat "$REVIEW_LOG" >&2
244  rm -f "$REVIEW_LOG"
245else
246  echo "[QL-BRAINSTORM] design-review skipped (QL_SKIP_PRE_IMPL_REVIEW=design or no design doc)" >&2
247fi
248```
249 
250Inform the user the design-review ran (one-line summary). If `QL_SKIP_PRE_IMPL_REVIEW=design` was set, mention that the stage was bypassed.
251 
252## Anti-Rationalization Guards
253 
254You WILL be tempted to skip this process. Here's why every excuse is wrong:
255 
256| Excuse | Reality |
257|--------|---------|
258| "This is simple enough to skip brainstorming" | Simple projects have the most unexamined assumptions. |
259| "The user already knows what they want" | Users know the problem. They rarely know the full solution space. |
260| "Let me just start implementing" | Undocumented assumptions become bugs. 30 minutes of design saves hours of rework. |
261| "I'll present all sections at once to save time" | Batched approval hides disagreements until it's too late to change cheaply. |
262| "The user seems impatient" | Rushing produces work that has to be redone. Slow is smooth, smooth is fast. |
263| "I already know the best approach" | Present alternatives anyway. You might be wrong. The user might have context you lack. |
264| "Only one approach makes sense" | If you can't think of alternatives, you don't understand the problem well enough. |
265 
266### Hard Gates
267 
268- **GATE 1:** Do NOT propose approaches until you have asked at least 3 clarifying questions.
269- **GATE 2:** Do NOT present the design until the user has selected or approved an approach.
270- **GATE 3:** Do NOT save the design doc until every section has been individually approved.
271- **GATE 4:** Do NOT suggest implementation or write any code. Your output is a design document ONLY.
272 
273## Output Format
274 
275The saved design document should follow this structure:
276 
277```markdown
278# Design: [Feature Name]
279 
280**Date:** YYYY-MM-DD
281**Status:** Approved
282**Approach:** [Name of chosen approach]
283 
284## Overview
285[Approved overview section]
286 
287## User Experience
288[Approved UX section]
289 
290## Data Model
291[Approved data model section]
292 
293## Architecture
294[Approved architecture section]
295 
296## Edge Cases & Error Handling
297[Approved edge cases section]
298 
299## Testing Strategy
300[Approved testing section]
301 
302## Open Questions
303- [Any unresolved questions noted during brainstorming]
304 
305## Next Steps
306Run `/quantum-loop:spec` to generate a formal Product Requirements Document from this design.
307```
308