review-spec
Skill6 starsChanged 50 days agoApache-2.0View on GitHub
Architectural review of a specification or design document, performed before implementation begins. Use whenever a spec or design proposal is in scope and the user asks any quality question — even when not phrased explicitly: 'review this spec', 'evaluate this design', 'is this spec implementable', 'is this ready to build', 'check this architecture proposal', 'review the design for feature X', 'is this design sound', 'what's missing from this spec'. Also triggers when a file under `.specs/` is being evaluated without an existing implementation. Do NOT use for verifying an existing implementation against a spec, reviewing a PR or implementation changes, reviewing an existing system's architecture, or security review. Identify the spec and any review focus in the arguments; the skill does not infer them from the conversation.
- Reads credentials
18 other projects use a version of this.
Adopted by
Most recently taken up by
- fclabs/skillstheir own version, first seen Nov 12, 2026
- 0xdeafcafe/skillstheir own version, first seen Nov 6, 2026
- alo-exp/silver-bullettheir own version, first seen Nov 1, 2026
- holgerleichsenring/specification-first-agentic-developmenttheir own version, first seen Oct 28, 2026
- Tngc93/product-management-skillstheir own version, first seen Oct 20, 2026
- swm8023/skillstheir own version, first seen Oct 14, 2026
Used with
Projects with it also use create-spec.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
srobinsonSkillcreate-spec
Create a task specification (SPEC.md) through interactive requirements elicitation. Use when helping users define what they want to build before autonomous execution begins.
Also in 3 projects that use this
Other versions18 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 18
- warpdotdev/oz-for-oss★ 316same name
- sd0xdev/sd0x-dev-flow★ 192same name
- sd0xdev/sd0x-harness★ 192same name
- tranhieutt/software_development_department★ 71same name
- holgerleichsenring/specification-first-agentic-development★ 41same name
- Codagent-AI/agent-skills★ 31same name
- alo-exp/silver-bullet★ 7same name
- dekoza/oh-my-slop★ 4same name
- NitinJ/specforge★ 4same name
- sponge-b0b/Polaris★ 4same name
8 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository35 other files it gives its agents.
- .agents/AGENTS.mdAGENTS.md
- AGENTS.mdAGENTS.md
- audit-agentSkill
- babysit-prSkill
- check-dependabotSkill
- compare-itSkill
- context-filesSkill
- create-prSkill
- delegate-workSkill
- explain-itSkill
- git-commitSkill
- improve-selfSkill
- isolate-cliSkill
- jira-syntaxSkill
- log-changesSkill
- make-docsSkill
- make-skillSkill
- manage-adrSkill
- manage-issuesSkill
- manage-ticketsSkill
- manage-todoSkill
- monitor-ciSkill
- prove-checksSkill
- research-itSkill
- review-archSkill
- review-implSkill
- scan-securitySkill
- search-webSkill
- split-docsSkill
- test-goSkill
- test-tsSkill
- verify-implSkill
- vet-dependencySkill
- writing-plansSkill
- writing-specsSkill
The file
We split this skill into the rules it gives an agent
9 rules. 0 are common, 6 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 17 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 43
Before evaluating the spec, study the project the spec lives in.
- Distinctive: line 45
Project documentation: Search and read:
- Distinctive: line 55
Existing patterns: Search the codebase for patterns the spec may have to align with: how similar features were implemented previously, …
- Distinctive: line 82
Be grounded: Every finding cites evidence: a section of the spec, a file in the codebase, a named pattern, an ADR.
- Distinctive: line 85
Honor existing decisions: If the project has decided not to use library X (visible in ADRs or context files), do not recommend X.
- Very specific: line 91
Write the full review to a markdown file under .reviews/, creating the directory if it does not exist.
- Very specific: line 95
All durable spec reviews use the Review-spec-{slug}.md pattern.
- Very specific: line 111
Collision handling: If the resolved filename already exists, append a numeric index: .reviews/<name>-2.md, .reviews/<name>-3.md, etc.
- Distinctive: line 118
After writing, print the path to the created file.
“Common” is measured: kept by at least 6 in 10 of the 17 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Specification Architectural Review
You are conducting a deep architectural review of a specification or design document — before implementation begins. You answer one question: is this spec ready to be implemented, and if not, what must change?
A spec is the contract between an architect and an implementer. Every ambiguity, every unstated assumption, every quality-attribute trade-off the spec leaves implicit will surface as a defect during implementation or in production. Your review is the last gate before implementation begins; the cost of catching issues at this stage is orders of magnitude lower than catching them after code is written.
Input
The user provides two arguments:
- Task name — a brief description of the feature ("Implement worker attempt function") OR a GitHub issue reference (
https://github.com/owner/repo/issues/123,owner/repo#123,#123). - Spec path — a markdown file defining the architecture or design.
If the invoker has already quoted the issue title and body in this prompt (typical when an orchestrator fetched the tracker in an earlier phase and passed the context forward), use those values directly — do not re-fetch. Otherwise, if the task name is a GitHub issue reference, fetch context with gh issue view <ref> --json title,body, and use the fetched title as the task name and the body as additional context. If the argument is plain text and no issue context was provided, treat it as the task name verbatim.
Workflow
The review proceeds in five phases. Each phase has a documented gate that prevents a specific failure mode (ungrounded reviews, missed conventions, ambiguity blindness, severity inflation). Do not skip, merge, or abbreviate any phase.
Copy this checklist into your response and mark items as you complete them:
- Phase 1 — Resolve task reference
- Phase 2 — Build project context
- Phase 3 — Read the specification thoroughly
- Phase 4 — Evaluate against six dimensions
- Phase 5 — Compose the review
Phase 1 — Resolve task reference
If the invoker already provided the issue title and body in the prompt (e.g. quoted under an Issue context (already fetched) section by an orchestrator), use those values directly and do not run gh issue view. Otherwise, if the task argument is a GitHub issue URL or shorthand, run gh issue view <ref> --json title,body and use the title as the task name and the body as additional context. If neither applies, treat the argument as the task name verbatim.
Phase 2 — Build project context
Before evaluating the spec, study the project the spec lives in. A review without project grounding produces generic advice that ignores what the project already does, has decided not to do, or cannot do given its constraints.
Project documentation. Search and read:
- Context file:
AGENTS.md - Project docs:
README.md,CONTRIBUTING.md, plusdocs/ordoc/directories - Decision records:
ADR/,adr/,docs/adr/,docs/decisions/ - Build manifests:
package.json,go.mod,Cargo.toml,pyproject.toml, etc. - Runtime model:
.env.example,compose.yml,docker-compose.yml,Makefile
Codebase structure. List the project root and key subdirectories. Identify entry points and public interfaces, domain boundaries and module organization, shared infrastructure and cross-cutting concerns, test structure and coverage patterns.
Existing patterns. Search the codebase for patterns the spec may have to align with: how similar features were implemented previously, abstractions the spec should reuse, integration points it touches, data models and storage patterns already in use.
Phase 3 — Read the specification thoroughly
Read the spec from the first line to the last. Do not skim. Note what the spec covers, what it leaves implicit, what assumptions it makes about the project, and what cross-references it makes to other documents. The spec is the primary subject of this review.
Phase 4 — Evaluate against six dimensions
For each dimension, ground every finding in evidence from the spec and the project context (Phases 2–3). Findings without evidence are speculation, and speculation disguised as review is worse than silence.
The six dimensions, with focusing questions, evidence-gathering checklists, and severity mapping per dimension, are documented in references/review-dimensions.md:
- Alignment — does the spec align with existing architecture, patterns, conventions?
- Feasibility — is the spec implementable given the current codebase?
- Risks — what architectural risks does the spec introduce?
- Completeness — what does the spec leave unspecified?
- Tradeoffs — which quality attributes does it prioritize, which does it sacrifice?
- Recommendations — what concrete improvements should the spec author make?
For the catalogue of spec failure modes to recognize during evaluation (vague language, untestable requirements, over-specification, missing error paths, implicit ordering, unspecified defaults, unstated assumptions, hidden coupling, traceability gaps, implementation in spec, architectural-decision contradiction, oversized steps) and the severity rubric that maps each to Critical / Significant / Observation, read references/spec-anti-patterns.md. The catalogue is grounded in IEEE 830 / ISO/IEC 29148 requirement-quality attributes.
Phase 5 — Compose the review
Populate the template at assets/review-template.md. The structure separates findings by severity (Critical Issues that block implementation, Significant Concerns that degrade quality, Observations worth noting) and explicitly captures Strengths (calibration), Open Questions (clarifications needed before implementation), and the overall Recommendation (READY / NEEDS REVISION / NOT READY).
Critical reminders
- Be grounded. Every finding cites evidence: a section of the spec, a file in the codebase, a named pattern, an ADR. Findings without anchors are opinions.
- Be direct. State findings without social padding. Findings wrapped in qualifiers are easy to ignore — and easy to disregard.
- Match severity to impact. A spec that overlooks an edge case is
Significant. A spec that mandates a layer-boundary breach isCritical. Naming preferences areObservation. See references/spec-anti-patterns.md for the rubric. - Honor existing decisions. If the project has decided not to use library X (visible in ADRs or context files), do not recommend X. The spec must align with the project, not the reviewer's preferences.
- Spec-first, code-second. This skill reviews the spec, not an implementation. If the spec is wrong, that is a finding here. If the implementation diverges from a correct spec, that is a different review (use
verify-impl). - Calibrate with strengths. A review that lists only what is wrong reads as adversarial and is hard to act on. Naming what the spec gets right preserves those decisions in revisions and helps the author trust the rest of the review.
Output
Write the full review to a markdown file under .reviews/, creating the directory if it does not exist. Populate the body using the structure defined in assets/review-template.md.
Filename derivation
All durable spec reviews use the Review-spec-{slug}.md pattern. The spec infix disambiguates a pre-implementation spec review from an architecture review or a spec-conformance verification when more than one runs on the same artefact.
Decide the filename in this priority order. Stop at the first matching rule.
- Invoker-provided path. If the invocation specifies an explicit output path (typical when an orchestrator or pipeline delegates to this skill — e.g.
.reviews/Review-spec-ISSUE-42-r2.md), use that path verbatim. Invokers carry task-specific identifiers, iteration suffixes (-r2,-r3), and ticketing conventions this skill has no visibility into. Do not second-guess. - Mirror the spec filename (the default when the spec filename starts with
Spec-). Strip theSpec-prefix and emitReview-spec-{rest}.md. This preserves 1:1 traceability between spec and review:.specs/Spec-6.4-Worker-Attempt-Function.md→.reviews/Review-spec-6.4-Worker-Attempt-Function.md.specs/Spec-ABC-42.md→.reviews/Review-spec-ABC-42.md.specs/Spec-238-codex-agent-adapter.md→.reviews/Review-spec-238-codex-agent-adapter.md
- Spec filename does not start with
Spec-— derive a slug, in this sub-priority:- Jira ID present in the task argument (e.g.
SORT-42,BP-138):.reviews/Review-spec-{ID}.md(e.g.Review-spec-SORT-42.md). - GitHub issue present in the task argument (e.g.
#238,owner/repo#238, full issue URL):.reviews/Review-spec-{N}-{kebab-case-slug}.md, where{slug}is derived from the issue title (e.g.Review-spec-238-codex-agent-adapter.md). - Neither ID present: derive
{kebab-case-slug}from the task name and emit.reviews/Review-spec-{slug}.md(e.g.Review-spec-agent-max-turns-passthrough-leak.md).
- Jira ID present in the task argument (e.g.
- Collision handling. If the resolved filename already exists, append a numeric index:
.reviews/<name>-2.md,.reviews/<name>-3.md, etc. Use the next available number.
Title and slug style
- Slugs are kebab-case ASCII, under ~60 characters.
- The H1 in the body (
## Spec Review: {Title}) matches the filename slug in human-readable form (capitalization restored, hyphens replaced with spaces where natural).
After writing, print the path to the created file.
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.

