# Ql Brainstorm

> 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…

- **Type:** Skill
- **Install:** `agentstack add skill-andyzengmath-quantum-loop-ql-brainstorm`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [andyzengmath](https://agentstack.voostack.com/s/andyzengmath)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [andyzengmath](https://github.com/andyzengmath)
- **Source:** https://github.com/andyzengmath/quantum-loop/tree/master/skills/ql-brainstorm

## Install

```sh
agentstack add skill-andyzengmath-quantum-loop-ql-brainstorm
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

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

```bash
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`:

```bash
# 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
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.

```bash
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:

```markdown
# 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](https://github.com/andyzengmath)
- **Source:** [andyzengmath/quantum-loop](https://github.com/andyzengmath/quantum-loop)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-andyzengmath-quantum-loop-ql-brainstorm
- Seller: https://agentstack.voostack.com/s/andyzengmath
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.