canon-spec-review
Skill3 starsChanged 9 days agoMITView on GitHub
Use when a canon task spec is written and the human wants to surface BLOCKING issues before invoking `canon run <id>`. Triggers on "/canon-spec-review", "review the spec", "pre-flight the spec", "what would Codex catch", or before kicking off the pipeline. Useful for any spec with logic — for full-tier (S/M/L/XL/delicate) it pre-empts `spec_review` iterations, for fast-tier (XS non-delicate) it's the only automated review layer since the fast tier auto-approves `spec_review`.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- canon-changelogSkill
- canon-initSkill
- canon-inline-reviewSkill
- canon-pipelineSkill
- canon-specSkill
- canon-statusSkill
- canon-sweepSkill
- docs-auditSkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 1 is distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
After a reroute amendment, before re-invoking the pipeline
- Very specific: line 20
Don't use for code-diff review (use /canon-inline-review), or for XS changes with no logic to vet (typo fixes, version bumps).
- Very specific: line 32
Verify tasks/<id>/spec.md exists and is filled out (no <placeholder> text or "TBD" stubs).
- Very specific: line 54
Read whole functions and call sites, not excerpts, when verifying return shapes.
- Very specific: line 122
If a lens returned [NO FINDINGS], say so under its section.
- Very specific: line 126
Inline report only: No file writes. No status.json updates.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
canon-spec-review
Previews what the pipeline's spec_review phase would surface — BEFORE canon run <id> — by dispatching three parallel sub-agents at the spec from different angles. Returns one inline report; the human revises the spec or proceeds.
When to use
- Spec is written,
human_spec_gatenot yet cleared - Task is full-tier (S/M/L/XL/delicate) — pre-empts
spec_reviewiterations; saves time and cost - Task is fast-tier (XS non-delicate) — this is the only automated review layer (fast-tier auto-approves
spec_review, so without this skill the human's read is the only gate before the implementer hits the spec at implement-time) - After a reroute amendment, before re-invoking the pipeline
Don't use for code-diff review (use /canon-inline-review), or for XS changes with no logic to vet (typo fixes, version bumps).
Workflow
1. Verify inputs
Resolve the task ID:
$ARGUMENTSnames a task → use it. This is how to review a task other than the one under discussion, or to run from a fresh session.$ARGUMENTSis empty → take the task from the conversation: the one just authored with/canon-spec, or the one the human has been discussing. Don't re-confirm an unambiguous pick.- Still unclear (fresh session, or several tasks in play) → run
canon task list, narrow to tasks atspecorspec_review, plus tasks atplanwhosestatus.jsonshowsphases.plan.status: "pending"(full tier waits at the human spec gate in that state). UseAskUserQuestionto pick one. If none match, say so rather than offering tasks already past the gate. Don't guess.
Verify tasks/<id>/spec.md exists and is filled out (no <placeholder> text or "TBD" stubs). If it's still a template, stop and say so.
Read into context:
tasks/<id>/spec.md(the artifact under review)tasks/<id>/status.json(size, delicate flag — informs whether the review is worth running)
State briefly: task ID, size, delicate flag, "dispatching 3 parallel sub-agents."
2. Dispatch 3 sub-agents in one message
Send a SINGLE message with three Agent tool calls so they run concurrently. Every call uses subagent_type: spec-review-lens and carries the full spec text inline, its angle, scope and rubric. Agent B's call also passes model: haiku; its lookups are mechanical, while A and C need judgment and inherit the session model. Each lens returns cited findings in its own format. If the Agent tool rejects spec-review-lens, stop and tell the human to run canon upgrade, then start a new Claude Code session; do not fall back to another agent type.
Agent A — Structural / shape
Scope: review whether the spec solves the right problem in the right shape. Answer four questions: is the problem real, is the framing right, is there a materially simpler solution, and is the AC decomposition right (compound ACs, missing ACs, ACs solving symptoms rather than causes)?
Constraints: don't audit factual claims (Agent B's job); don't audit completeness against canon's spec-writing rules (Agent C's job). Stay in shape territory.
Agent B — Factual / ground-truth
Scope: verify every factual claim in the spec against the actual codebase. For each named symbol, file path, function, or behavior: does it exist, is the description correct, and are Affected Files entries real paths? For symbols in ACs, verify signatures, return shapes, and call sites. Then search for other implementations of the behavior the spec changes (a parallel listener, entry path, or component, or a test or doc that asserts the current behavior) that Affected Files doesn't name; one the change must also reach is BLOCKING.
Read whole functions and call sites, not excerpts, when verifying return shapes. Cite file:line for every claim. Don't audit shape (Agent A) or stylistic completeness (Agent C).
This angle catches the highest-value class: a spec that assumes something exists in one place when it is elsewhere, or describes its contract incorrectly.
Agent C — Spec-quality completeness
Scope: audit against canon's spec-writing rules of thumb. Check these eleven items:
(1) Name effects to DELETE — when a change supersedes prior code, is it framed as a single replacement, not separate add/remove bullets?
(2) Prefer positive or structural assertions — are load-bearing "must not" constraints backed by a grep AC or positive reframe, not just prose negation?
(3) Affected Files — completeness only: it lists every file the change writes, including generated mirrors and rebuilt outputs, under ### Affected Files in ## Design or an amendment section; files only read for context stay out. A missing generated or rebuilt output is BLOCKING. Heading and row format is enforced when the spec is marked done, with a pre-flight backstop before planning and implementation.
(4) Validation Required — section present AND has at least one - [x] checked entry (or an explicit checked "None — <reason>"). A section with zero [x] entries is a failing check.
(5) Non-goals — rule out the most tempting scope expansions.
(6) Human Test Plan — product language only; no code, no file paths.
(7) Known Risks — names actual failure modes for the trickiest ACs.
(8) Symbols in ACs exist — for any named function or symbol, has the author verified the return shape matches the spec's assumed data contract?
(9) Bug/flake-fix evidence (N/A for features/refactors) — Problem states the confirmed mechanism and how it was confirmed, with evidence matching the mechanism class: a deterministic mechanism may cite a trace with verified trigger values; a runtime-dependent mechanism needs executed confirmation (a throwaway prototype-fix spike or a deterministic forced repro). Acceptance Criteria includes a red-first regression-test AC or the explicit environment-bound-and-impractical escape with a named deterministic alternative. Missing or under-rung evidence, or a missing red-first AC without the escape, is BLOCKING.
(10) Refactor correctness audit evidence (N/A for features/bug fixes) — does the spec record, for each behavior it declares preserved, whether it is correct today and one outcome: correct as-is, fixed deliberately (with its own AC), split into a separate task, or kept as a named quirk? A behavior confirmed correct needs only a one-line record. Missing audit evidence is STRONG, never BLOCKING.
(11) Unlisted judgment calls — A judgment call is a choice between two or more defensible options where the choice changes behavior or scope. A choice a project doc already settles is not a judgment call: follow the doc and cite it. Does the spec make a judgment call that its Judgment Calls section does not list? Name the call, a defensible alternative the spec does not record, and the AC or behavior that would differ under it; if you cannot name all three, do not raise it. A missing or empty section is not, by itself, a finding. An unlisted call that meets this bar is BLOCKING (the pipeline's spec_review treats it as changes_requested).
Constraints: stay structural/completeness. Don't second-guess shape (Agent A) or independently re-verify symbols against the codebase (Agent B's job). Check (8) audits whether the author verified before writing the AC.
Severity definitions and scope boundary
- BLOCKING: would cause wrong behavior or a silent bug, or makes an AC unimplementable as written.
- NIT: an implementation detail the implementer resolves by reading the codebase, a minor ambiguity with an obvious default, or a question the plan phase should answer.
- STRONG: nit-grade under those rules, but likely to cost a review round, so cheaper to fix now.
An unlisted judgment call (check 11) is BLOCKING regardless of the rules above.
Behavior the spec's Non-Goals explicitly exclude and verify as unaffected is a NIT at most. An omitted required change (such as a caller, parser, migration or test surface), a transitive effect of the change, or an internal contradiction between spec sections stays BLOCKING.
3. Synthesize and report
Silence is the default for what reaches the report. Apply these filters:
- Drop any finding with no citation (uncited).
- Downgrade any finding inside the scope boundary to NIT (scope-boundary downgrade).
- de-dupe overlapping findings, keeping the more specific rationale.
- Re-classify on the strongest evidence, then order BLOCKING, STRONG, NIT.
Print this inline (do NOT write to a file):
# /canon-spec-review for `<task-id>`
**Task**: <title> · **Size**: <XS/S/M/L/XL> · **Delicate**: <yes/no>
## 🔴 BLOCKING (N)
1. <finding> — <citation>
<rationale> · _flagged by: A/B/C_
## 🟡 STRONG (N)
...
## 🟢 NIT (N)
...
## Recommendation
<one of:>
- Proceed — `canon run <id>` is ready, only NITs (pipeline will absorb them)
- Revise spec first — N BLOCKING items must be addressed
- Worth a quick pass — STRONG items will probably surface in spec_review; cheaper to fix nowIf a lens returned [NO FINDINGS], say so under its section. Don't pad. If all three returned no findings, the report is two lines: header + "Proceed — three sub-agents found no issues."
Output principles
- Inline report only. No file writes. No status.json updates. No spec-review.md mutations.
- Operator owns the decision. This skill surfaces findings; it doesn't revise specs or invoke the pipeline.
Anti-patterns
| Anti-pattern | Why it's wrong | Do instead |
| Run on XS typo fixes or version bumps | Overhead exceeds value when there is no logic to vet | Skip when there's no logic to vet; use freely on any spec that has decisions in it, XS included |
| Use to revise the spec | The skill doesn't edit files | Read the report, edit the spec manually |
| Manufacture findings to look thorough | Dilutes signal | [NO FINDINGS] is a real verdict; report only cited findings |
| Use for code-diff review | Spec mode only | Use /canon-inline-review for diff review |
Related
/canon-spec— where the spec under review came from./canon-pipeline— invokecanon run <id>after BLOCKING findings are addressed.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

