bauer/dotfiles
1
0
Fork 0
mirror of https://github.com/dnlbauer/dotfiles.git synced 2026-09-10 13:35:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat: update spec review skill to run without fanout

Browse Source
This commit is contained in:
Daniel Bauer
2026-08-16 11:36:55 +02:00
parent 2ab082cca5
commit 1ee089b51e
1 changed files with 50 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

153
dot_claude/skills/sdd-spec-review/SKILL.md
View File

@@ -8,7 +8,6 @@ context: fork
model: opus model: opus
effort: high effort: high
allowed-tools: allowed-tools:
- Agent
- AskUserQuestion - AskUserQuestion
- Glob - Glob
- Grep - Grep
@@ -18,30 +17,24 @@ allowed-tools:
# Spec Review # Spec Review
You are a spec-review orchestrator and a **pure critic**. You fan out specialist reviewer You are a **pure critic**. You review a spec-for-change from specialist perspectives, then aggregate the findings into a single verdict and return them.
subagents in parallel, aggregate their findings into a single verdict, and return them.
You **never edit the spec** and you **never run a human approval gate** — those belong to You **never edit the spec** and you **never run a human approval gate** — those belong to
`sdd-plan`, which owns the spec and the loop. Your only output is findings + a verdict. `sdd-plan`, which owns the spec and the loop. Your only output is findings + a verdict.
**Subagent stop guard:** If you were dispatched to perform a single review role, produce your
findings and return. Do NOT invoke further subagents. Do NOT edit the spec.
## Step 1: Read the spec ## Step 1: Read the spec
1. Locate the spec file. If a path was passed in, use it. If invoked standalone with no path, 1. Locate the spec file. If a path was passed in, use it. If invoked standalone with no path,
look for `spec-*.md` in the repo root; if there are several, ask the user which one. look for `spec-*.md` in the repo root; if there are several, ask the user which one.
2. Read the spec completely (no limit/offset). 2. Read the spec completely (no limit/offset).
## Step 2: Fan out reviewer subagents in parallel ## Step 2: Review from five perspectives
Dispatch all five reviewers **at once** (a single message, multiple Agent calls). Do not wait Work through the spec and review it from the five perspectives below. You may check the spec against the actual codebase by reading files as needed.
for one before dispatching the next. Wait for all to return before aggregating. Pass the full
spec content to each.
Each reviewer uses the output contract below. **Every finding must be self-contained and Each perspective produces findings using the output contract below. **Every finding must be
actionable** — enough detail that someone could fix it without re-reading the reviewer's mind. self-contained and actionable** — enough detail that someone could fix it without re-reading
Use this exact per-finding structure: your reasoning. Use this exact per-finding structure:
``` ```
- **<short title>** — <what is wrong, missing, or ambiguous, with enough context to locate it - **<short title>** — <what is wrong, missing, or ambiguous, with enough context to locate it
@@ -69,115 +62,62 @@ examples, or details the implementer can reasonably decide within the guardrails
Critical/Important; put them in Minor or omit them. If you cannot state a concrete suggested Critical/Important; put them in Minor or omit them. If you cannot state a concrete suggested
fix for a finding, it is almost certainly not Critical or Important. fix for a finding, it is almost certainly not Critical or Important.
**When you dispatch each reviewer, append this entire contract verbatim to its prompt** — a Apply the severity calibration below to every perspective — it governs what counts as
subagent only sees what you send it, so the per-finding structure and severity calibration must Critical/Important/Minor across all five passes, not just one.
be included in every reviewer prompt.
### Reviewer 1 — Completeness & Clarity ### Perspective 1 — Completeness & Clarity
``` Do not praise the spec — find problems. Evaluate:
Task (general-purpose): - Are all sections present and non-empty (Summary, Problem Statement, Current State, Goals,
You are reviewing a spec-for-change for completeness and clarity. Do NOT edit it. Do NOT
invoke subagents. Do not praise it — find problems.
Spec content:
<full spec>
Evaluate:
- Are all sections present and non-empty (Summary, Problem Statement, Current State, Goals,
Non-Goals, Functional Requirements, Non-Functional Requirements, Design & Architectural Non-Goals, Functional Requirements, Non-Functional Requirements, Design & Architectural
Decisions, Scope of Change, Edge Cases, Risks & Constraints)? Decisions, Scope of Change, Edge Cases, Risks & Constraints)?
- Does every Functional Requirement carry a concrete **Verify** block? - Does every Functional Requirement carry a concrete **Verify** block?
- Is each requirement unambiguous and individually verifiable? - Is each requirement unambiguous and individually verifiable?
- Is anything important missing or left implicit? - Is anything important missing or left implicit?
- Is the Documentation subsection under Scope of Change concrete (names the docs to update), not hand-waved? - Is the Documentation subsection under Scope of Change concrete (names the docs to update), not hand-waved?
Output the Critical / Important / Minor / Verdict contract. ### Perspective 2 — Internal Consistency
```
### Reviewer 2 — Internal Consistency Evaluate:
- Do Goals, Requirements (FR/NFR), and Design & Architectural Decisions agree with each other?
- Do any Non-Goals contradict a stated Goal or Requirement?
- Do the Edge Cases and Risks & Constraints align with the Design & Architectural Decisions?
- Are there requirements with no corresponding design, or design with no driving requirement?
``` ### Perspective 3 — Architectural Soundness
Task (general-purpose):
You are reviewing a spec-for-change for internal consistency. Do NOT edit it. Do NOT invoke subagents.
Spec content: Read existing code with Read/Glob/Grep as needed to check the design against reality. Evaluate:
<full spec> - Are the data-ownership, interface, and pattern decisions coherent and complete?
- Do they conflict with the Current State or established conventions in the codebase?
- Are the chosen interfaces/contracts at the right boundary? Any leaky or missing abstractions?
- Will the Design & Architectural Decisions actually satisfy the non-functional requirements?
Evaluate: ### Perspective 4 — Irreversibility & Risk
- Do Goals, Requirements (FR/NFR), and Design & Architectural Decisions agree with each other?
- Do any Non-Goals contradict a stated Goal or Requirement?
- Do the Edge Cases and Risks & Constraints align with the Design & Architectural Decisions?
- Are there requirements with no corresponding design, or design with no driving requirement?
Output the Critical / Important / Minor / Verdict contract. Evaluate:
``` - Are hard-to-reverse decisions (schema changes, persisted data formats, public API/contract
### Reviewer 3 — Architectural Soundness
```
Task (general-purpose):
You are a software architect reviewing a spec-for-change. Do NOT edit it. Do NOT invoke subagents.
You may read existing code with Read/Glob/Grep to check the design against reality.
Spec content:
<full spec>
Evaluate:
- Are the data-ownership, interface, and pattern decisions coherent and complete?
- Do they conflict with the Current State or established conventions in the codebase?
- Are the chosen interfaces/contracts at the right boundary? Any leaky or missing abstractions?
- Will the Design & Architectural Decisions actually satisfy the non-functional requirements?
Output the Critical / Important / Minor / Verdict contract.
```
### Reviewer 4 — Irreversibility & Risk
```
Task (general-purpose):
You are reviewing a spec-for-change for risk and irreversibility. Do NOT edit it. Do NOT invoke subagents.
Spec content:
<full spec>
Evaluate:
- Are hard-to-reverse decisions (schema changes, persisted data formats, public API/contract
changes, migrations) explicitly called out with their consequences? changes, migrations) explicitly called out with their consequences?
- What could break existing behaviour? Are the Constraints sufficient to prevent it? - What could break existing behaviour? Are the Constraints sufficient to prevent it?
- Are there security, data-loss, or compatibility risks the spec fails to address? - Are there security, data-loss, or compatibility risks the spec fails to address?
- Which open questions, if any, would block implementation from starting safely? - Which open questions, if any, would block implementation from starting safely?
Output the Critical / Important / Minor / Verdict contract. ### Perspective 5 — Testability
```
### Reviewer 5 — Testability Evaluate as a QA engineer would:
- Does every Functional Requirement have a **Verify** block, and is that block concrete and
```
Task (general-purpose):
You are a QA engineer reviewing a spec-for-change for testability. Do NOT edit it. Do NOT invoke subagents.
Spec content:
<full spec>
Evaluate:
- Does every Functional Requirement have a **Verify** block, and is that block concrete and
actionable (a real test, command + expected output, or observable behaviour) rather than vague? actionable (a real test, command + expected output, or observable behaviour) rather than vague?
- Are the Goals measurable? - Are the Goals measurable?
- Are the Non-Functional Requirements expressed with verifiable bars (thresholds, limits)? - Are the Non-Functional Requirements expressed with verifiable bars (thresholds, limits)?
- Are the Edge Cases concrete enough to write tests from? - Are the Edge Cases concrete enough to write tests from?
- Could an implementer turn the Verify blocks straight into acceptance tests, or would they have to guess? - Could an implementer turn the Verify blocks straight into acceptance tests, or would they have to guess?
Output the Critical / Important / Minor / Verdict contract.
```
## Step 3: Aggregate ## Step 3: Aggregate
Once all reviewers return: Once all five passes are done:
1. **Overall verdict** = the worst individual verdict (`NEEDS_REVISION` > `APPROVED`). 1. **Overall verdict** = the worst individual verdict across passes (`NEEDS_REVISION` > `APPROVED`).
2. **Deduplicate** overlapping findings across reviewers — when two reviewers raise the same 2. **Deduplicate** overlapping findings across passes — when two passes raise the same issue,
issue, merge them but keep the fullest description, impact, and suggested fix. merge them but keep the fullest description, impact, and suggested fix.
3. **Group by severity**: Critical → Important → Minor. 3. **Group by severity**: Critical → Important → Minor.
4. **Preserve each finding's full structure** (title, description, Impact, Suggested fix) — do 4. **Preserve each finding's full structure** (title, description, Impact, Suggested fix) — do
NOT shorten findings to bare titles. The caller needs the detail to act on or present them. NOT shorten findings to bare titles. The caller needs the detail to act on or present them.
@@ -199,7 +139,6 @@ finding forces `NEEDS_REVISION`.
## Principles ## Principles
- You are a critic, not an author: never edit the spec, never approve it on the human's behalf. - You are a critic, not an author: never edit the spec, never approve it on the human's behalf.
- All reviewer subagents run in parallel — never sequentially. - Give each perspective a genuine independent pass; don't let earlier passes suppress findings a later perspective would raise on its own terms.
- Reviewer subagents do not invoke further subagents; they return findings and stop. - Aggregate the worst verdict — never average or soften across perspectives.
- Aggregate the worst verdict — never average or soften across reviewers.
- A spec with any Critical or Important finding is NEEDS_REVISION; Critical issues are never buried. - A spec with any Critical or Important finding is NEEDS_REVISION; Critical issues are never buried.