Ql Brainstorm

Quantum-Loop: Brainstorm

You 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.

Phase 0: Phase-skip check (Phase 18 / P2.4)

Before asking any question, check whether a prior /ql-brainstorm run already covered this exact input:

# Inputs that define "same brainstorm": verbatim user intent + any existing design doc
INTENT_TEXT=$(jq -r '.userIntent.text // ""' quantum.json 2>/dev/null)
DESIGN=$(ls docs/plans/*-design.md 2>/dev/null | tail -1)  # most recent if multiple
ARGS=()
[[ -n "$INTENT_TEXT" ]] && ARGS+=("inline:$INTENT_TEXT")
[[ -n "$DESIGN" ]]      && ARGS+=("$DESIGN")

if bash lib/phase-skip.sh skip brainstorm . "${ARGS[@]}"; then
  echo "[SKIP] brainstorm is up-to-date — inputs unchanged since last run."
  echo "Re-reading .handoffs/brainstorm.md for downstream context."
  bash lib/handoff.sh read brainstorm | jq '.'
  # Return control to caller. No re-questioning, no design regeneration.
  exit 0
fi

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

FP=$(jq -cn --arg ip "inline://$INTENT_TEXT" --arg ih "$(bash lib/phase-skip.sh inline "$INTENT_TEXT" | tr -d '\n')" \
            --arg dp "$DESIGN" --arg dh "$(bash lib/phase-skip.sh hash "$DESIGN" | tr -d '\n')" \
  '{artifacts: [{path: $ip, sha256: $ih}, {path: $dp, sha256: $dh}]}')
bash lib/phase-skip.sh record brainstorm "$FP" . >/dev/null

Phase 0B: Ambiguity gate (Phase 19 / P2.8, OMC deep-interview)

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

# After round N of questioning, self-assess clarity 0-10 on each dimension:
GOAL_CLARITY=        # "Can I state what this feature does in one sentence?"
CONSTRAINTS_CLARITY= # "Can I list every constraint (time/tech/compliance)?"
CRITERIA_CLARITY=    # "Can I list every success / acceptance criterion?"

SCORE=$(bash lib/ambiguity.sh score "$GOAL_CLARITY" "$CONSTRAINTS_CLARITY" "$CRITERIA_CLARITY")
MODE=$(bash lib/ambiguity.sh mode "$ROUND" "$SCORE")

if bash lib/ambiguity.sh gate "$SCORE"; then
  echo "[AMBIGUITY] score=$SCORE   "Does this section look right? Should I adjust anything before moving on?"

Sections to present (adapt based on complexity):

1. **Overview** -- What we're building and why
2. **User Experience** -- How the user interacts with it (flows, screens, commands)
3. **Data Model** -- What data structures or schema changes are needed
4. **Architecture** -- How components connect, what talks to what
5. **Edge Cases & Error Handling** -- What can go wrong and how we handle it
6. **Testing Strategy** -- What types of tests, what's critical to test

### Section Rules
- Each section must be approved before presenting the next
- If user requests changes, revise and re-present that section
- Do NOT combine sections to save time
- Do NOT present all sections at once

## Phase 4: Save Design Document

After all sections are approved, save the complete design to:

docs/plans/YYYY-MM-DD--design.md

Use kebab-case for the topic. The document should include:
- All approved sections assembled together
- A "Next Steps" section pointing to `/quantum-loop:spec` for formal PRD creation
- Date and any open questions noted during brainstorming

### Phase 4b: Snapshot user intent (required for ql-intent-check)

If `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.

Required shape (see `skills/ql-intent-check/SKILL.md` §"Immutable intent snapshot"):

```json
{
  "userIntent": {
    "text": "",
    "timestamp": "",
    "source_message_id": null
  },
  "userClarifications": []
}

Write rules:

• The text MUST be the exact verbatim text the user wrote in their first brainstorm turn — no paraphrasing, no summary.
• If userIntent.text is already populated, DO NOT overwrite. This field is immutable.
• Use lib/json-atomic.sh helpers (write_quantum_json) to avoid partial-write races.

Inform the user: > "Design saved to docs/plans/YYYY-MM-DD--design.md. User intent snapshot stored in quantum.json. When you're ready to create a formal spec, run /quantum-loop:spec."

Phase 4c: Write stage handoff (Phase 15 / P2.3)

Before 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.

Use lib/handoff.sh:

bash lib/handoff.sh write brainstorm "$(cat "],
  "rejected":  [""],
  "risks":     [""],
  "files":     ["docs/plans/YYYY-MM-DD--design.md"],
  "remaining": [""],
  "notes":     ""
}
JSON
)"

Every downstream skill opens with bash lib/handoff.sh all | jq '.' — so any decision you record here is durable even across session boundaries.

Phase 4d: Post-exit design-review (P5.B4 / US-006 / v0.6.3 — advisory)

After 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.

DESIGN_PATH=$(ls docs/plans/*-design.md 2>/dev/null | tail -1)

# Opt-out gate: QL_SKIP_PRE_IMPL_REVIEW=design (or comma-separated, e.g. design,prd)
SKIP_LIST="${QL_SKIP_PRE_IMPL_REVIEW:-}"
if [[ -n "$DESIGN_PATH" ]] && \
   ! printf '%s' "$SKIP_LIST" | tr ',' '\n' | grep -qx "design"; then
  echo "[QL-BRAINSTORM] Running spec-reviewer in design-review mode (advisory)..." >&2
  # Dispatch the spec-reviewer subagent with MODE=design-review and the design doc path.
  # Findings are emitted to stderr in FINDING_START..FINDING_END format.
  # The skill continues regardless of what's reported — set QL_SKIP_PRE_IMPL_REVIEW=design
  # to disable this stage entirely.
  #
  # G13 / US-002 (v0.7.0): capture the reviewer stderr, parse FINDING blocks
  # via lib/finding-synth.sh, and persist the parsed summary + per-run snapshot
  # via lib/finding-persist.sh. Advisory contract preserved — the skill never
  # aborts based on findings.
  REVIEW_LOG=$(mktemp)
  MODE=design-review DESIGN_PATH="$DESIGN_PATH" \
    claude --headless "agents/spec-reviewer.md design-review mode against $DESIGN_PATH" \
      2> "$REVIEW_LOG" || true

  # Source the parser + persister (no shell flags inherited; libs are flag-free at source).
  # shellcheck disable=SC1091
  source lib/finding-synth.sh
  # shellcheck disable=SC1091
  source lib/finding-persist.sh

  findings=$(parse_findings design /dev/null
  format_summary_line "$summary" >&2; echo >&2

  # Surface the reviewer's stderr (so operators still see FINDING blocks).
  cat "$REVIEW_LOG" >&2
  rm -f "$REVIEW_LOG"
else
  echo "[QL-BRAINSTORM] design-review skipped (QL_SKIP_PRE_IMPL_REVIEW=design or no design doc)" >&2
fi

Inform the user the design-review ran (one-line summary). If QL_SKIP_PRE_IMPL_REVIEW=design was set, mention that the stage was bypassed.

Anti-Rationalization Guards

You WILL be tempted to skip this process. Here's why every excuse is wrong:

| Excuse | Reality | |--------|---------| | "This is simple enough to skip brainstorming" | Simple projects have the most unexamined assumptions. | | "The user already knows what they want" | Users know the problem. They rarely know the full solution space. | | "Let me just start implementing" | Undocumented assumptions become bugs. 30 minutes of design saves hours of rework. | | "I'll present all sections at once to save time" | Batched approval hides disagreements until it's too late to change cheaply. | | "The user seems impatient" | Rushing produces work that has to be redone. Slow is smooth, smooth is fast. | | "I already know the best approach" | Present alternatives anyway. You might be wrong. The user might have context you lack. | | "Only one approach makes sense" | If you can't think of alternatives, you don't understand the problem well enough. |

Hard Gates

• GATE 1: Do NOT propose approaches until you have asked at least 3 clarifying questions.
• GATE 2: Do NOT present the design until the user has selected or approved an approach.
• GATE 3: Do NOT save the design doc until every section has been individually approved.
• GATE 4: Do NOT suggest implementation or write any code. Your output is a design document ONLY.

Output Format

The saved design document should follow this structure:

# Design: [Feature Name]

**Date:** YYYY-MM-DD
**Status:** Approved
**Approach:** [Name of chosen approach]

## Overview
[Approved overview section]

## User Experience
[Approved UX section]

## Data Model
[Approved data model section]

## Architecture
[Approved architecture section]

## Edge Cases & Error Handling
[Approved edge cases section]

## Testing Strategy
[Approved testing section]

## Open Questions
- [Any unresolved questions noted during brainstorming]

## Next Steps
Run `/quantum-loop:spec` to generate a formal Product Requirements Document from this design.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: andyzengmath
• Source: andyzengmath/quantum-loop
• License: MIT

Install and usage instructions live in the source repository linked above.