ql-deep-review
starsforks
How to install ql-deep-review?
andyzengmath/quantum-loop/ql-deep-review
$npx -y skills add andyzengmath/quantum-loop --skill ql-deep-reviewMulti-perspective post-implementation review aggregator for quantum-loop. Invokes 2-7 reviewer agents in parallel based on risk score, applies actionability filter, dedups, aggregates with evidence requirements. Use AFTER the per-story two-stage review gates pass and before mergi
SKILL.md
| 1 | # ql-deep-review — whole-feature post-implementation review |
| 2 | |
| 3 | ## Purpose |
| 4 | |
| 5 | quantum-loop's built-in two-stage review gate (`ql-review`: spec-compliance → code-quality) operates on ONE story at a time inside ONE worktree. It does not detect: |
| 6 | |
| 7 | 1. **Cross-story divergence** (e.g., story A uses `'google'` as a secret key while story B uses `'google-api-key'` for the same constant). |
| 8 | 2. **Post-merge regressions** (test that was green in isolation breaks after integration). |
| 9 | 3. **Drift from original user intent** (paraphrase chain from intent → design → PRD → plan → code). |
| 10 | 4. **Low-signal comments** that look like findings but lack evidence (CRA actionability is 0.9-19.2% per Chowdhury 2604.03196; human baseline is ~60%). |
| 11 | |
| 12 | `ql-deep-review` closes these gaps with a whole-feature review that runs AFTER all stories in a wave / feature pass the per-story gate. |
| 13 | |
| 14 | ## When to use |
| 15 | |
| 16 | - After `ql-execute` emits `COMPLETE` for a wave and before merging the feature branch to master. |
| 17 | - After cherry-picking or merging a foreign branch whose conflict-resolution changed semantics. |
| 18 | - Manually, when suspicion of cross-story drift is high (e.g., follow-on work after a long autonomous run). |
| 19 | |
| 20 | ## What it does NOT do |
| 21 | |
| 22 | - **Does not** replace the per-story two-stage gate. Run `ql-review` per story, then this. |
| 23 | - **Does not** auto-fix findings. Produces a structured report; user or orchestrator drives action. |
| 24 | - **Does not** block merge autonomously. Emits a verdict + confidence; user decides. |
| 25 | |
| 26 | ## Risk scoring (0-100) |
| 27 | |
| 28 | Risk factors and weights (inspired by soliton's risk-adaptive dispatch): |
| 29 | |
| 30 | | Factor | Weight | Measurement | |
| 31 | |--------|:------:|-------------| |
| 32 | | Blast radius | 25 | count of files touched in wave × (max transitive callers of any touched symbol ÷ 100) | |
| 33 | | Change complexity | 15 | `difftastic` or `cloc` diff line count; tree-sitter function edit count | |
| 34 | | Sensitive paths | 20 | glob match: `auth/`, `payment/`, `*.env*`, `*secret*`, `*password*`, `*token*` | |
| 35 | | File size / scope | 10 | total LOC touched / number of files | |
| 36 | | AI-authored signal | 10 | git commit trailer `Co-Authored-By: Claude`, uniform-style heuristic | |
| 37 | | Test coverage gap | 10 | production files touched without corresponding test edits | |
| 38 | | Intent-drift signal | 10 | `ql-intent-check` CRITICAL findings count (optional input) | |
| 39 | |
| 40 | Score → dispatch tier: |
| 41 | - **0-30 LOW**: 2 reviewers (code-reviewer, synthesizer). Target turnaround 2-3 min. |
| 42 | - **31-60 MEDIUM**: 4 reviewers (+security-reviewer, test-engineer). 4-6 min. |
| 43 | - **61-80 HIGH**: 6 reviewers (+critic, architect). 6-10 min. |
| 44 | - **81-100 CRITICAL**: 7 reviewers (+cross-provider critic using codex or gemini via `/ask`). 10-15 min plus manual inspection. |
| 45 | |
| 46 | ## Reviewer agents (dispatched per tier) |
| 47 | |
| 48 | All agents are invoked via the `Agent` tool in parallel. Each receives: |
| 49 | - `BASE_SHA..HEAD_SHA` — whole-feature diff scope |
| 50 | - `PRD_PATH` — path to the feature PRD |
| 51 | - `STORY_LIST` — JSON list of stories executed with their IDs and status |
| 52 | - `INTENT_SNAPSHOT` — verbatim user intent (from `quantum.json.userIntent` if present) |
| 53 | - `CHANGED_FILES` — file-list manifest |
| 54 | |
| 55 | ### Tier-core reviewers (always dispatched) |
| 56 | |
| 57 | - **`oh-my-claudecode:code-reviewer`** — severity-rated findings (CRITICAL / HIGH / MEDIUM / LOW) with line-level evidence. |
| 58 | - **`soliton:synthesizer`** — risk-adaptive PR-style review; contributes a reviewer-side risk score and a READY_TO_MERGE / NEEDS_REWORK / BLOCKED verdict. |
| 59 | |
| 60 | ### Tier-MEDIUM additions |
| 61 | |
| 62 | - **`oh-my-claudecode:security-reviewer`** — OWASP Top 10 + secret exposure + input validation; hard-dispatched when sensitive-paths factor > 0. |
| 63 | - **`oh-my-claudecode:test-engineer`** — test-quality audit: AC-to-test mapping, over-mock detection (Hora & Robbes 2026), missing edge cases. |
| 64 | |
| 65 | ### Tier-HIGH additions |
| 66 | |
| 67 | - **`oh-my-claudecode:critic`** — multi-perspective adversarial critique; self-audit + Realist Check. |
| 68 | - **`oh-my-claudecode:architect`** — architectural review: SOLID, layering, cross-cutting concerns. |
| 69 | |
| 70 | ### Tier-CRITICAL additions |
| 71 | |
| 72 | - **Cross-provider critic** — via `omc ask codex --agent-prompt critic` (Codex reviews Claude's output) OR `omc ask gemini`. Different failure modes → higher catch rate. |
| 73 | |
| 74 | ## Actionability filter (the Chowdhury 2604.03196 fix) |
| 75 | |
| 76 | Every finding returned by a reviewer MUST include: |
| 77 | 1. `file` (string, path) |
| 78 | 2. `line` or `line_start` + `line_end` (integer) |
| 79 | 3. `evidence_type`: one of `code-reference` / `command-output` / `spec-citation` / `test-failure` / `diff-hunk` |
| 80 | 4. `severity`: `critical` / `high` / `medium` / `low` / `info` |
| 81 | 5. `confidence` |
People who liked this also viewed
6 picksType
- requesting-code-reviewUse when completing tasks, implementing major features, or before merging to verify work meets requirementsSkillsJul 2026
- code-reviewSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026
- receiving-code-reviewUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performativeSkillsJul 2026
- baoyu-format-markdownFormats plain text or markdown files with frontmatter, titles, summaries, headings, bold, lists, and code blocks. Use when user asks to "format markdown", "beautify article", "add formatting", or imprSkillsJul 2026
- code-review-excellenceMaster effective code review practices to provide constructive feedback, catch bugs early, and foster knowledge sharing while maintaining team morale. Use when reviewing pull requests, establishing reSkillsJul 2026
- code-review-and-qualityConducts multi-axis code review. Use before merging any change. Use when reviewing code written by yourself, another agent, or a human. Use when you need to assess code quality across multiple dimensiSkillsJul 2026
