ql-spec

Name: ql-spec
Author: andyzengmath

23stars0forks

How to install ql-spec?

andyzengmath/quantum-loop/ql-spec

$npx -y skills add andyzengmath/quantum-loop --skill ql-spec

Installs into the current project.

Summary

Part of the quantum-loop autonomous development pipeline (brainstorm \u2192 spec \u2192 plan \u2192 execute \u2192 review \u2192 verify). Generate a structured Product Requirements Document (PRD) with user stories, acceptance criteria, and functional requirements. Use when you ha

Files · 1

View on GitHub

SKILL.md

1	# Quantum-Loop: Spec
2
3	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.
4
5	## Phase 0: Phase-skip check (Phase 18 / P2.4)
6
7	Before asking any clarifying question, check whether a prior `/ql-spec` run already converted the same design + brainstorm handoff into a PRD:
8
9	```bash
10	DESIGN=$(ls docs/plans/*-design.md 2>/dev/null \| tail -1)
11	BS_HANDOFF=".handoffs/brainstorm.md"
12	ARGS=()
13	[[ -n "$DESIGN" ]] && ARGS+=("$DESIGN")
14	[[ -f "$BS_HANDOFF" ]] && ARGS+=("$BS_HANDOFF")
15
16	if bash lib/phase-skip.sh skip spec . "${ARGS[@]}"; then
17	echo "[SKIP] spec is up-to-date — design + brainstorm handoff unchanged."
18	bash lib/handoff.sh read spec \| jq '.'
19	exit 0
20	fi
21	```
22
23	After saving the PRD and writing `.handoffs/spec.md`, record the fingerprint so the next identical invocation can skip:
24
25	```bash
26	PRD=$(ls -t tasks/prd-*.md \| head -1)
27	DESIGN_H=$(bash lib/phase-skip.sh hash "$DESIGN")
28	BS_H=$(bash lib/phase-skip.sh hash "$BS_HANDOFF")
29	FP=$(jq -cn --arg dp "$DESIGN" --arg dh "$DESIGN_H" --arg bp "$BS_HANDOFF" --arg bh "$BS_H" \
30	'{artifacts: [{path: $dp, sha256: $dh}, {path: $bp, sha256: $bh}]}')
31	bash lib/phase-skip.sh record spec "$FP" . >/dev/null
32	```
33
34	## Prerequisite: read prior-stage handoffs (Phase 15 / P2.3)
35
36	Before doing anything else, ingest every prior-stage handoff so decisions, rejected alternatives, and risks carry forward even across context compaction:
37
38	```bash
39	bash lib/handoff.sh all \| jq '.'
40	bash lib/handoff.sh read brainstorm \| jq '.'
41	```
42
43	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.
44
45	## Step 1: Gather Context
46
47	1. Check for an approved design document in `docs/plans/`. If one exists, load it as primary context.
48	2. Check for existing quantum.json to understand any in-progress features.
49	3. Read project files (package.json, README, existing code structure) to understand the tech stack.
50	4. Re-read `.handoffs/brainstorm.md`'s `remaining` list — it IS the starting backlog of clarifying questions.
51	5. N31 / v0.7.5 — grep-verify cited file paths. Before citing any file path in an AC (e.g., `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`.
52
53	## Step 2: Ask Clarifying Questions
54
55	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".
56
57	Focus questions on areas where the design doc (if any) is ambiguous or incomplete:
58
59	- Problem/Goal: What specific problem does this solve?
60	- Core Functionality: What are the key user actions?
61	- Scope Boundaries: What should it explicitly NOT do?
62	- Success Criteria: How do we know it's done?
63	- Technical Constraints: What must it integrate with?
64	- Data Requirements: What data needs to be stored, fetched, or transformed?
65	- Error Scenarios: What happens when things go wrong?
66	- Priority: What is the MVP vs. nice-to-have?
67
68	### Question Format
69
70	```
71	1. What is the primary goal of this feature?
72	A. Improve user onboarding experience
73	B. Increase task completion rate
74	C. Reduce support tickets for X
75	D. Other: [please specify]
76
77	2. How should priority levels be structured?
78	A. Three levels (High / Medium / Low)
79	B. Four levels (Critical / High / Medium / Low)
80	C. Numeric (1-5 scale)
81	D. Custom labels defined by user
82	```
83
84	### Question Rules
85	- Question count is adaptive to remaining ambiguity, not a hard minimum.
86	- If there is no design doc and the feature is non-trivial: ask 5-8 questions.
87	- If a design doc exists and answers most of Phase 1's concerns: ask only what the design doc leaves ambiguous — typically 2-4 question

People who liked this also viewed

6 picks

Type

ql-spec

23stars0forks

View on GitHub

How to install ql-spec?

andyzengmath/quantum-loop/ql-spec

$npx -y skills add andyzengmath/quantum-loop --skill ql-spec

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Quantum-Loop: Spec
2
3	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.
4
5	## Phase 0: Phase-skip check (Phase 18 / P2.4)
6
7	Before asking any clarifying question, check whether a prior `/ql-spec` run already converted the same design + brainstorm handoff into a PRD:
8
9	```bash
10	DESIGN=$(ls docs/plans/*-design.md 2>/dev/null \| tail -1)
11	BS_HANDOFF=".handoffs/brainstorm.md"
12	ARGS=()
13	[[ -n "$DESIGN" ]] && ARGS+=("$DESIGN")
14	[[ -f "$BS_HANDOFF" ]] && ARGS+=("$BS_HANDOFF")
15
16	if bash lib/phase-skip.sh skip spec . "${ARGS[@]}"; then
17	echo "[SKIP] spec is up-to-date — design + brainstorm handoff unchanged."
18	bash lib/handoff.sh read spec \| jq '.'
19	exit 0
20	fi
21	```
22
23	After saving the PRD and writing `.handoffs/spec.md`, record the fingerprint so the next identical invocation can skip:
24
25	```bash
26	PRD=$(ls -t tasks/prd-*.md \| head -1)
27	DESIGN_H=$(bash lib/phase-skip.sh hash "$DESIGN")
28	BS_H=$(bash lib/phase-skip.sh hash "$BS_HANDOFF")
29	FP=$(jq -cn --arg dp "$DESIGN" --arg dh "$DESIGN_H" --arg bp "$BS_HANDOFF" --arg bh "$BS_H" \
30	'{artifacts: [{path: $dp, sha256: $dh}, {path: $bp, sha256: $bh}]}')
31	bash lib/phase-skip.sh record spec "$FP" . >/dev/null
32	```
33
34	## Prerequisite: read prior-stage handoffs (Phase 15 / P2.3)
35
36	Before doing anything else, ingest every prior-stage handoff so decisions, rejected alternatives, and risks carry forward even across context compaction:
37
38	```bash
39	bash lib/handoff.sh all \| jq '.'
40	bash lib/handoff.sh read brainstorm \| jq '.'
41	```
42
43	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.
44
45	## Step 1: Gather Context
46
47	1. Check for an approved design document in `docs/plans/`. If one exists, load it as primary context.
48	2. Check for existing quantum.json to understand any in-progress features.
49	3. Read project files (package.json, README, existing code structure) to understand the tech stack.
50	4. Re-read `.handoffs/brainstorm.md`'s `remaining` list — it IS the starting backlog of clarifying questions.
51	5. N31 / v0.7.5 — grep-verify cited file paths. Before citing any file path in an AC (e.g., `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`.
52
53	## Step 2: Ask Clarifying Questions
54
55	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".
56
57	Focus questions on areas where the design doc (if any) is ambiguous or incomplete:
58
59	- Problem/Goal: What specific problem does this solve?
60	- Core Functionality: What are the key user actions?
61	- Scope Boundaries: What should it explicitly NOT do?
62	- Success Criteria: How do we know it's done?
63	- Technical Constraints: What must it integrate with?
64	- Data Requirements: What data needs to be stored, fetched, or transformed?
65	- Error Scenarios: What happens when things go wrong?
66	- Priority: What is the MVP vs. nice-to-have?
67
68	### Question Format
69
70	```
71	1. What is the primary goal of this feature?
72	A. Improve user onboarding experience
73	B. Increase task completion rate
74	C. Reduce support tickets for X
75	D. Other: [please specify]
76
77	2. How should priority levels be structured?
78	A. Three levels (High / Medium / Low)
79	B. Four levels (Critical / High / Medium / Low)
80	C. Numeric (1-5 scale)
81	D. Custom labels defined by user
82	```
83
84	### Question Rules
85	- Question count is adaptive to remaining ambiguity, not a hard minimum.
86	- If there is no design doc and the feature is non-trivial: ask 5-8 questions.
87	- If a design doc exists and answers most of Phase 1's concerns: ask only what the design doc leaves ambiguous — typically 2-4 question

People who liked this also viewed

6 picks

Type