From quantum-loop
Conducts deep Socratic exploration of feature ideas before implementation: asks questions one at a time, proposes 2-3 alternatives with trade-offs, presents design sections for approval, and saves approved design documents.
npx claudepluginhub andyzengmath/quantum-loop --plugin quantum-loopThis skill uses the workspace's default tool permissions.
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.
Refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation before writing code or plans.
Refines rough ideas into fully-formed designs through collaborative questioning, alternative exploration, and incremental validation before coding or planning.
Guides structured brainstorming to transform vague ideas into validated designs for features, architecture, and behavior before implementation.
Share bugs, ideas, or general feedback.
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.
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
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=<0-10> # "Can I state what this feature does in one sentence?"
CONSTRAINTS_CLARITY=<0-10> # "Can I list every constraint (time/tech/compliance)?"
CRITERIA_CLARITY=<0-10> # "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 <20 — gate passes, proceed to Phase 4 (design)."
else
echo "[AMBIGUITY] score=$SCORE challenge-mode=$MODE — more questions required."
# Apply the challenge mode before the next question:
# normal — continue clarifying questions as usual
# contrarian — challenge every assumption with an opposing view; force justification
# simplifier — push "what is the minimum that solves 80% of this?"
# ontologist — refuse to proceed until every named object has a precise definition
fi
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.
Record the final score in .handoffs/brainstorm.md as part of the Phase 4c handoff write, so downstream skills can verify the gate passed:
{
"decided": [...],
"ambiguity": { "final_score": 12, "rounds": 4, "final_mode": "normal" },
"notes": "..."
}
Read existing project files for context:
docs/plans/Then ask clarifying questions to understand the problem space:
Based on the answers, propose 2-3 alternative approaches:
For EACH approach, present:
End with your RECOMMENDATION and why.
Wait for the user to choose or provide feedback before proceeding.
Present the design in 200-300 word sections. After EACH section, explicitly ask:
"Does this section look right? Should I adjust anything before moving on?"
Sections to present (adapt based on complexity):
After all sections are approved, save the complete design to:
docs/plans/YYYY-MM-DD-<topic>-design.md
Use kebab-case for the topic. The document should include:
/quantum-loop:spec for formal PRD creationIf 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"):
{
"userIntent": {
"text": "<verbatim first-message text>",
"timestamp": "<ISO 8601 at write time>",
"source_message_id": null
},
"userClarifications": []
}
Write rules:
text MUST be the exact verbatim text the user wrote in their first brainstorm turn — no paraphrasing, no summary.userIntent.text is already populated, DO NOT overwrite. This field is immutable.lib/json-atomic.sh helpers (write_quantum_json) to avoid partial-write races.Inform the user:
"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."
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 <<'JSON'
{
"decided": ["<each approved-section decision, verbatim>"],
"rejected": ["<each alternative considered and NOT chosen, with reason>"],
"risks": ["<each risk surfaced during brainstorm>"],
"files": ["docs/plans/YYYY-MM-DD-<topic>-design.md"],
"remaining": ["<any open question left for /ql-spec to resolve>"],
"notes": "<free-form tail: unanswered questions, follow-ups>"
}
JSON
)"
Every downstream skill opens with bash lib/handoff.sh all | jq '.' — so any decision you record here is durable even across session boundaries.
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 < "$REVIEW_LOG")
summary=$(summarize_findings design "$findings")
persist_review_findings design "$DESIGN_PATH" "$summary" "$findings" >/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.
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. |
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.