ql-review

Name: ql-review
Author: andyzengmath

23stars0forks

How to install ql-review?

andyzengmath/quantum-loop/ql-review

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

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). Two-stage code review. Spec compliance first, then code quality. Use after implementation or before merge. Triggers on: review code, code revi

Files · 1

View on GitHub

SKILL.md

1	# Quantum-Loop: Review
2
3	You orchestrate a two-stage code review. Stage 1 (spec compliance) MUST pass before Stage 2 (code quality) begins. This order is absolute.
4
5	## Why Two Stages?
6
7	Code that doesn't match the spec is waste -- no matter how well-written. Checking spec compliance first prevents spending review effort on code that needs to be rewritten anyway.
8
9	## Usage Modes
10
11	### Mode 1: Within /quantum-loop:execute (automated)
12	Called automatically by the execution loop after a story's quality checks pass.
13	Receives story context from quantum.json.
14
15	### Mode 2: Standalone (user-invoked)
16	User invokes `/quantum-loop:review` directly to review recent changes.
17
18	## Standalone Workflow
19
20	### Step 1: Determine Review Scope
21
22	If the user specifies a story ID, use it. Otherwise:
23
24	1. Check for `quantum.json` -- if exists, identify the most recent `in_progress` story
25	2. If no quantum.json, use the current branch's diff from main/master:
26	```bash
27	git merge-base HEAD main
28	```
29
30	Determine BASE_SHA and HEAD_SHA for the review range.
31
32	### Step 2: Identify the Spec
33
34	1. If quantum.json exists: read the PRD path and story acceptance criteria
35	2. If no quantum.json: ask the user what requirements this code should meet
36	3. If no spec exists at all: skip Stage 1, proceed directly to Stage 2 with a warning
37
38	### Step 3: Stage 1 -- Spec Compliance Review
39
40	Dispatch the `spec-reviewer` agent with:
41	- STORY_ID
42	- PRD_PATH
43	- BASE_SHA
44	- HEAD_SHA
45
46	Wait for the review result.
47
48	If Stage 1 PASSES:
49	- Log result to quantum.json (if available)
50	- Proceed to Stage 2
51
52	If Stage 1 FAILS:
53	- Present the issues to the user (or to the execution loop)
54	- List every unsatisfied acceptance criterion with evidence
55	- Do NOT proceed to Stage 2
56	- If within /quantum-loop:execute: return failure with issues list
57
58	### Step 4: Stage 2 -- Code Quality Review
59
60	Only reached if Stage 1 passed.
61
62	Dispatch the `quality-reviewer` agent with:
63	- STORY_ID
64	- BASE_SHA
65	- HEAD_SHA
66	- DESCRIPTION (brief summary of what was implemented)
67
68	Wait for the review result.
69
70	If Stage 2 PASSES:
71	- Log result to quantum.json (if available)
72	- Report success
73
74	If Stage 2 FAILS:
75	- Present categorized issues (Critical / Important / Minor)
76	- Critical issues must be fixed
77	- 3+ Important issues must be fixed
78	- Minor issues are noted but don't block
79
80	## Handling Review Feedback
81
82	### Within /quantum-loop:execute (automated)
83	1. If review fails, the implementer gets ONE attempt to fix the issues
84	2. After fixing, both review stages run again from scratch
85	3. If second attempt also fails, story is marked as failed
86
87	### Standalone (user-invoked)
88	1. Present the full review report
89	2. User decides which issues to fix
90	3. User can re-invoke `/quantum-loop:review` after fixing
91
92	## Output Format
93
94	Present the combined review report:
95
96	```markdown
97	## Review Report: [Story ID or Branch Name]
98
99	### Stage 1: Spec Compliance
100	Status: PASSED / FAILED
101
102	[If failed: list unsatisfied criteria]
103	[If passed: "All N acceptance criteria satisfied."]
104
105	### Stage 2: Code Quality
106	Status: PASSED / FAILED / SKIPPED (if Stage 1 failed)
107
108	Strengths:
109	- [List from quality reviewer]
110
111	Issues:
112	- [Critical] [description] -- [file:line]
113	- [Important] [description] -- [file:line]
114	- [Minor] [description] -- [file:line]
115
116	### Recommendation
117	[Pass / Fix and re-review / specific guidance]
118	```
119
120	## Stage 3: Cross-Story Integration Review
121
122	This stage runs when:
123	- All stories in a dependency chain have passed Stages 1 and 2
124	- OR when all stories are complete (final gate before COMPLETE)
125	- OR when explicitly invoked: `/quantum-loop:ql-review --integration`
126
127	### Checks (use LSP tools when available, fall back to grep)
128
129	1. Call chain tracing: For every function created by an upstream story, verify it is called (not just imported) in downstream stories.
130	- PREFERRED: LSP "Find References" — returns only actual call sites
131	- FALLBACK: `grep -rn "function_name" --include="*.py" \| grep -v test`
132	- Must appear in at least one non-test call site outside its defining file
133
134	2. Type consistency: Check that return types from upstream stories match parameter types expected downstream.
135	- PREFERRED: LSP "Hover" on call sites to verify argument types
136	- FALLBACK: Read source of caller and callee, compare manually
137	- Flag: list-vs-string, Optional-vs-required, scalar-vs-collection mismatches
138
139	3. Dead code scan: Every new export must have a caller outside its own file and tests.
140	- PREFERRED: LSP "Find References" returns 0 results = dead code
141	- FALLBACK: grep for function name, exclude test files
142
143	4. Import resolution: Verify every import statement resolves

People who liked this also viewed

6 picks

Type

ql-review

23stars0forks

View on GitHub

How to install ql-review?

andyzengmath/quantum-loop/ql-review

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

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Quantum-Loop: Review
2
3	You orchestrate a two-stage code review. Stage 1 (spec compliance) MUST pass before Stage 2 (code quality) begins. This order is absolute.
4
5	## Why Two Stages?
6
7	Code that doesn't match the spec is waste -- no matter how well-written. Checking spec compliance first prevents spending review effort on code that needs to be rewritten anyway.
8
9	## Usage Modes
10
11	### Mode 1: Within /quantum-loop:execute (automated)
12	Called automatically by the execution loop after a story's quality checks pass.
13	Receives story context from quantum.json.
14
15	### Mode 2: Standalone (user-invoked)
16	User invokes `/quantum-loop:review` directly to review recent changes.
17
18	## Standalone Workflow
19
20	### Step 1: Determine Review Scope
21
22	If the user specifies a story ID, use it. Otherwise:
23
24	1. Check for `quantum.json` -- if exists, identify the most recent `in_progress` story
25	2. If no quantum.json, use the current branch's diff from main/master:
26	```bash
27	git merge-base HEAD main
28	```
29
30	Determine BASE_SHA and HEAD_SHA for the review range.
31
32	### Step 2: Identify the Spec
33
34	1. If quantum.json exists: read the PRD path and story acceptance criteria
35	2. If no quantum.json: ask the user what requirements this code should meet
36	3. If no spec exists at all: skip Stage 1, proceed directly to Stage 2 with a warning
37
38	### Step 3: Stage 1 -- Spec Compliance Review
39
40	Dispatch the `spec-reviewer` agent with:
41	- STORY_ID
42	- PRD_PATH
43	- BASE_SHA
44	- HEAD_SHA
45
46	Wait for the review result.
47
48	If Stage 1 PASSES:
49	- Log result to quantum.json (if available)
50	- Proceed to Stage 2
51
52	If Stage 1 FAILS:
53	- Present the issues to the user (or to the execution loop)
54	- List every unsatisfied acceptance criterion with evidence
55	- Do NOT proceed to Stage 2
56	- If within /quantum-loop:execute: return failure with issues list
57
58	### Step 4: Stage 2 -- Code Quality Review
59
60	Only reached if Stage 1 passed.
61
62	Dispatch the `quality-reviewer` agent with:
63	- STORY_ID
64	- BASE_SHA
65	- HEAD_SHA
66	- DESCRIPTION (brief summary of what was implemented)
67
68	Wait for the review result.
69
70	If Stage 2 PASSES:
71	- Log result to quantum.json (if available)
72	- Report success
73
74	If Stage 2 FAILS:
75	- Present categorized issues (Critical / Important / Minor)
76	- Critical issues must be fixed
77	- 3+ Important issues must be fixed
78	- Minor issues are noted but don't block
79
80	## Handling Review Feedback
81
82	### Within /quantum-loop:execute (automated)
83	1. If review fails, the implementer gets ONE attempt to fix the issues
84	2. After fixing, both review stages run again from scratch
85	3. If second attempt also fails, story is marked as failed
86
87	### Standalone (user-invoked)
88	1. Present the full review report
89	2. User decides which issues to fix
90	3. User can re-invoke `/quantum-loop:review` after fixing
91
92	## Output Format
93
94	Present the combined review report:
95
96	```markdown
97	## Review Report: [Story ID or Branch Name]
98
99	### Stage 1: Spec Compliance
100	Status: PASSED / FAILED
101
102	[If failed: list unsatisfied criteria]
103	[If passed: "All N acceptance criteria satisfied."]
104
105	### Stage 2: Code Quality
106	Status: PASSED / FAILED / SKIPPED (if Stage 1 failed)
107
108	Strengths:
109	- [List from quality reviewer]
110
111	Issues:
112	- [Critical] [description] -- [file:line]
113	- [Important] [description] -- [file:line]
114	- [Minor] [description] -- [file:line]
115
116	### Recommendation
117	[Pass / Fix and re-review / specific guidance]
118	```
119
120	## Stage 3: Cross-Story Integration Review
121
122	This stage runs when:
123	- All stories in a dependency chain have passed Stages 1 and 2
124	- OR when all stories are complete (final gate before COMPLETE)
125	- OR when explicitly invoked: `/quantum-loop:ql-review --integration`
126
127	### Checks (use LSP tools when available, fall back to grep)
128
129	1. Call chain tracing: For every function created by an upstream story, verify it is called (not just imported) in downstream stories.
130	- PREFERRED: LSP "Find References" — returns only actual call sites
131	- FALLBACK: `grep -rn "function_name" --include="*.py" \| grep -v test`
132	- Must appear in at least one non-test call site outside its defining file
133
134	2. Type consistency: Check that return types from upstream stories match parameter types expected downstream.
135	- PREFERRED: LSP "Hover" on call sites to verify argument types
136	- FALLBACK: Read source of caller and callee, compare manually
137	- Flag: list-vs-string, Optional-vs-required, scalar-vs-collection mismatches
138
139	3. Dead code scan: Every new export must have a caller outside its own file and tests.
140	- PREFERRED: LSP "Find References" returns 0 results = dead code
141	- FALLBACK: grep for function name, exclude test files
142
143	4. Import resolution: Verify every import statement resolves

People who liked this also viewed

6 picks

Type