From quantum-loop
Generates structured Product Requirements Document (PRD) with user stories, acceptance criteria, and functional requirements from approved designs or brainstorms in quantum-loop pipeline.
npx claudepluginhub andyzengmath/quantum-loop --plugin quantum-loopThis skill uses the workspace's default tool permissions.
You are generating a formal Product Requirements Document (PRD). This document will be consumed by `/quantum-loop:plan` to produce machine-readable tasks for autonomous execution. Write for junior developers or AI agents -- be explicit, unambiguous, and verifiable.
Generates structured Product Requirements Documents (PRDs) by gathering project context from files and commits, asking 3-5 clarifying questions with lettered options, and producing sections like user stories, functional requirements, non-goals, and success metrics.
Clarifies vague requirements into actionable PRDs via dialogue, 100-point clarity scoring, and systematic questioning on functionality, tech, scope, and business context.
Share bugs, ideas, or general feedback.
You are generating a formal Product Requirements Document (PRD). This document will be consumed by /quantum-loop:plan to produce machine-readable tasks for autonomous execution. Write for junior developers or AI agents -- be explicit, unambiguous, and verifiable.
Before asking any clarifying question, check whether a prior /ql-spec run already converted the same design + brainstorm handoff into a PRD:
DESIGN=$(ls docs/plans/*-design.md 2>/dev/null | tail -1)
BS_HANDOFF=".handoffs/brainstorm.md"
ARGS=()
[[ -n "$DESIGN" ]] && ARGS+=("$DESIGN")
[[ -f "$BS_HANDOFF" ]] && ARGS+=("$BS_HANDOFF")
if bash lib/phase-skip.sh skip spec . "${ARGS[@]}"; then
echo "[SKIP] spec is up-to-date — design + brainstorm handoff unchanged."
bash lib/handoff.sh read spec | jq '.'
exit 0
fi
After saving the PRD and writing .handoffs/spec.md, record the fingerprint so the next identical invocation can skip:
PRD=$(ls -t tasks/prd-*.md | head -1)
DESIGN_H=$(bash lib/phase-skip.sh hash "$DESIGN")
BS_H=$(bash lib/phase-skip.sh hash "$BS_HANDOFF")
FP=$(jq -cn --arg dp "$DESIGN" --arg dh "$DESIGN_H" --arg bp "$BS_HANDOFF" --arg bh "$BS_H" \
'{artifacts: [{path: $dp, sha256: $dh}, {path: $bp, sha256: $bh}]}')
bash lib/phase-skip.sh record spec "$FP" . >/dev/null
Before doing anything else, ingest every prior-stage handoff so decisions, rejected alternatives, and risks carry forward even across context compaction:
bash lib/handoff.sh all | jq '.'
bash lib/handoff.sh read brainstorm | jq '.'
Treat brainstorm.decided as binding (already agreed — do not re-litigate), brainstorm.rejected as closed alternatives (do not re-propose them), brainstorm.remaining as the exact backlog your PRD MUST resolve, and brainstorm.risks as mandatory §Risks entries in the PRD.
docs/plans/. If one exists, load it as primary context..handoffs/brainstorm.md's remaining list — it IS the starting backlog of clarifying questions.tests/test_X.sh, lib/Y.sh), run a grep/ls verification that the path actually exists in the codebase. If the path is being created by this PRD, annotate with [NEW] in parentheses to disambiguate. This prevents the AC-drift class of error where the spec phase hallucinates plausible-looking file paths that don't exist. Worked example: v0.7.4 US-004 cited tests/test_worktree_isolation.sh and lib/type-auditor.sh — neither existed; real names were tests/test_type_audit.sh + lib/type-audit.sh.Ask 2-8 clarifying questions — count adaptive to remaining ambiguity (see Question Rules below). Format each with LETTERED OPTIONS so the user can respond with shorthand like "1A, 2C, 3B, 4D, 5A".
Focus questions on areas where the design doc (if any) is ambiguous or incomplete:
1. What is the primary goal of this feature?
A. Improve user onboarding experience
B. Increase task completion rate
C. Reduce support tickets for X
D. Other: [please specify]
2. How should priority levels be structured?
A. Three levels (High / Medium / Low)
B. Four levels (Critical / High / Medium / Low)
C. Numeric (1-5 scale)
D. Custom labels defined by user
Based on the user's answers, generate a PRD with ALL 9 sections below. No section may be omitted.
Brief description (2-3 sentences) of the feature and the problem it solves.
Specific, measurable objectives as a bullet list. Each goal should be verifiable.
Format:
### US-001: [Title]
**Description:** As a [user], I want [feature] so that [benefit].
**Acceptance Criteria:**
- [ ] Specific verifiable criterion 1
- [ ] Specific verifiable criterion 2
- [ ] Typecheck/lint passes
- [ ] [UI stories only] Verify in browser
Each story must be completable in ONE context window (one AI agent session). Rules of thumb:
Numbered list with unambiguous requirements:
FR-1: The system shall store task priority as an enum ('high' | 'medium' | 'low').
FR-2: The system shall default new tasks to 'medium' priority.
FR-3: The API shall accept an optional 'priority' query parameter on GET /tasks.
Explicit list of what this feature will NOT include. This section is mandatory and must have at least 3 items.
UI/UX requirements, mockup references, existing component reuse.
Constraints, dependencies, integration points, performance requirements.
Measurable outcomes (e.g., "Reduce time to find high-priority tasks by 50%").
Remaining areas needing clarification. If none, state "None at this time."
Save to: tasks/prd-<feature-name>.md (kebab-case filename).
Inform the user:
"PRD saved to
tasks/prd-<feature-name>.md. When you're ready to create the execution plan, run/quantum-loop:plan."
Do NOT start implementing. Do NOT create quantum.json. That is /quantum-loop:plan's job.
status column to tasks table with default 'pending'"Every criterion must answer: "How would a machine verify this?"
| Excuse | Reality |
|---|---|
| "I'll pad questions to hit 5" | Padding past real ambiguity produces release-ops / non-goal-confirmation questions that don't belong in a PRD. If the design doc answers most of Phase 1, ask only what remains genuinely open — 2-4 is fine. The floor is 2, not 5. |
| "This story is slightly too big but it's fine" | Too-big stories fail during autonomous execution. Split ruthlessly. |
| "The acceptance criteria are obvious" | Obvious to you is ambiguous to an AI agent. Be explicit. |
| "Non-goals aren't needed for this feature" | Unbounded scope is the root of scope creep. Always define boundaries. |
| "I'll skip the design considerations section" | All 9 sections are mandatory. Mark optional sections as "N/A" if truly not applicable. |
| "These criteria are verifiable enough" | If a machine can't test it, it's not verifiable. Rewrite. |
Before saving the PRD, verify:
tasks/prd-<feature-name>.mdFor each item below, either address it in the PRD or mark it "N/A" with a justification. Silent skipping is forbidden — every item must have an explicit resolution.
Before returning control, persist a stage handoff at .handoffs/spec.md so /ql-plan, /ql-execute, and downstream reviewers can read your decisions even across session compaction:
bash lib/handoff.sh write spec "$(cat <<'JSON'
{
"decided": ["<each AC that converges a prior brainstorm.remaining item>", "<scope-boundary picks>"],
"rejected": ["<any alternative framing of an AC you considered and dropped, with reason>"],
"risks": ["<each §Risks entry of the PRD>"],
"files": ["tasks/prd-<feature>.md"],
"remaining": ["<any question you could not resolve — flag for /ql-plan>"],
"notes": "<free-form: how this PRD re-grounds against userIntent, any re-negotiation logged>"
}
JSON
)"
The decided array MUST NOT contradict brainstorm.decided; any re-negotiation MUST also land as a new quantum.json.userClarifications[] entry so /ql-intent-check sees it as explicit.
After the handoff is written, run the spec-reviewer in prd-review mode against the just-saved PRD. The review is advisory in v0.6.3 — findings emit to stderr; the skill does NOT abort regardless of what's flagged.
PRD_PATH=$(bash lib/handoff.sh read spec 2>/dev/null | jq -r '.files[0] // empty' 2>/dev/null)
[[ -z "$PRD_PATH" || "$PRD_PATH" == "null" ]] && PRD_PATH=$(ls tasks/prd-*.md 2>/dev/null | tail -1)
# Opt-out gate: QL_SKIP_PRE_IMPL_REVIEW=prd (or comma-separated, e.g. design,prd).
SKIP_LIST="${QL_SKIP_PRE_IMPL_REVIEW:-}"
if [[ -n "$PRD_PATH" ]] && \
! printf '%s' "$SKIP_LIST" | tr ',' '\n' | grep -qx "prd"; then
echo "[QL-SPEC] Running spec-reviewer in prd-review mode (advisory)..." >&2
# 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=prd-review PRD_PATH="$PRD_PATH" \
claude --headless "agents/spec-reviewer.md prd-review mode against $PRD_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 prd < "$REVIEW_LOG")
summary=$(summarize_findings prd "$findings")
persist_review_findings prd "$PRD_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-SPEC] prd-review skipped (QL_SKIP_PRE_IMPL_REVIEW=prd or no PRD)" >&2
fi
The reviewer emits findings via FINDING_START..FINDING_END blocks to stderr. The skill exits 0 regardless. Operators can chain skips (QL_SKIP_PRE_IMPL_REVIEW=design,prd to bypass both stages).