spec-review
/spec-review
Review a natural-language hardware specification for ambiguity, internal inconsistency, untestable statements, and missing corner cases BEFORE it enters spec-to-rtl. Use when the user says "review this spec", "check my spec", "is this spec complete", "spec sanity check", or provides a datasheet draft / PRD for a hardware block.
Assessment and security
- Files in this package
- 3
- Scripts
- 1
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
- 1 scripts in this package. Review them before installing, as Claude may execute them.
Scripts: tests/test_compliance.py
What it does and when to use it
Review a natural-language hardware specification for ambiguity, internal inconsistency, untestable statements, and missing corner cases BEFORE it enters spec-to-rtl. Use when the user says "review this spec", "check my spec", "is this spec complete", "spec sanity check", or provides a datasheet draft / PRD for a hardware block.
Triggers from the description
Original author description
Review a natural-language hardware specification for ambiguity, internal inconsistency, untestable statements, and missing corner cases BEFORE it enters spec-to-rtl. Use when the user says "review this spec", "check my spec", "is this spec complete", "spec sanity check", or provides a datasheet draft / PRD for a hardware block.
How it works
- When to use
- Review dimensions
- Workflow
- Output format
- Technical basis
- Handoff
- Compliance gate (mandatory)
SKILL.md preview
---
name: spec-review
description: Review a natural-language hardware specification for ambiguity, internal inconsistency, untestable statements, and missing corner cases BEFORE it enters spec-to-rtl. Use when the user says "review this spec", "check my spec", "is this spec complete", "spec sanity check", or provides a datasheet draft / PRD for a hardware block.
---
# Spec Review
A bad spec is the cheapest bug to fix and the most expensive to ship. This skill screens a natural-language spec for defects before `/spec-to-rtl` turns the defects into RTL.
## When to use
- Draft PRD / architecture doc for a new block
- Legacy spec being resurrected for a new tape-out
- Spec delta for an ECO
- Before running any generative skill that consumes the spec
## Review dimensions
1. **Unambiguous**
- Every signal has direction, width, polarity, clock domain, reset domain
- Every timing statement has a reference edge
2. **Internally consistent**
- No contradicting statements ("always X" vs "X when Y")
- Priority order of control signals is explicit
- Numerical examples match the general rule
3. **Testable**
- Every behavior can be observed from I/O or debug
- Every mode has an entry and exit condition
4. **Complete corner cases**
- Reset during operation
- Back-to-back transactions
- Full / empty / overflow / underflow
- Illegal inputs — defined vs undefined behavior
5. **Interface discipline**
- Protocol compliance (AXI, APB, AHB, I2C, SPI)
- Handshake sequencing
6. **Non-functional**
- Power / clock / area / latency targets stated
- Safety / security level
## Workflow
**Step 0 — run the deterministic structural lint FIRST (do not eyeball it).**
The presence/structure half of the checklist above — *is each declared signal's
`{direction, width, polarity, clock, reset}` present? does each timing statement
name a reference edge? does each declared mode have entry + exit? are the four
corner-case checklist items covered?* — is mechanical and must run identically
every time. Run it before any human reading so the rest of your review is spent
only on judgment:
```bash
python3 programs/spec_review_lint.py <spec_file> --json spec/spec_review_lint.json
# add --strict to make any WARN finding fail the gate (exit 1)
```
The lint is chip-AGNOSTIC and no-false-alert: it flags ONLY genuinely-missing
declared structure (a signal that IS declared but lacks an attribute, a real
timing statement with no edge, an uncovered corner-case item). A pure-prose spec
with no interface list yields no signal findings; an empty/short spec SKIPs; a
missing file exits 2. Treat every `WARN` as a concrete must-fix gap and fold the
JSON findings into your dimension table below. It does NOT judge ambiguity wording
or propose rewrites — that is your job in steps 3-5.
1. Read the spec end-to-end
2. For each dimension above, mark each section as GREEN / YELLOW / RED — seed the
Unambiguous / Testable / Complete-corner-cases rows from `spec_review_lint.json`,
then apply judgment to the consistency / interface / non-functional rows
3. List specific sentences that are ambiguous with suggested rewrites **(judgment —
the lint does not do this)**
4. Flag missing subsections **(judgment, beyond the lint's structural items)**
5. Propose cover properties that should exist once the spec is hardened (handoff to `/assertion-gen`)
## Output format
- `spec/spec_review.md`:
- Dimension score table
- Line-by-line findings
- Suggested rewrites (diff-style)
- Open questions for the designer
## Technical basis
Requirements-engineering principles (IEEE 29148). For hardware specifically: ARM AMBA spec methodology, automotive ISO 26262 requirements tracing.
## Handoff
- Hardened spec → `/spec-to-rtl`
- Testable claims → `/assertion-gen`
- Architecture trade-offs → `/architecture-explore`
## Compliance gate (mandatory)
After producing your output, save it to a file and run:
```bash
python3 plugins/vibe-ic/_shared/skill_compliance_check.py \
--requirements plugins/vibe-ic/skills/spec-review/compliance.yaml \
<your_output_file>
```
Exit 0 = PASS, exit 1 = FAIL with specific missing elements listed.
`compliance.yaml` in the corresponding skill directory enumerates
every required element of your output: section headers, metadata fields,
handoff lines, tool invocations.
**Your task is not complete until the audit returns PASS.** Missing
elements are the single largest source of skill-execution non-determinism
across different agents.
### Skill: Reconcile conflicting statements using admitted authority
Read the entire current input before treating a short, repeated sentence as a
replacement for a complete behavioral contract. Compare declared interfaces,
required state capacity, timing, explicit comparisons and any stated priority.
An extreme-zone override governs that zone; it does not reverse an explicit
previous/current comparison elsewhere. A defined functional requirement must
not be replaced by a convention merely because the latter is familiar.
If the current request permits engineering assumptions and the admitted
evidence supports a unique intended interpretation, record the precise
conflicting excerpts, the assumption and every literal requirement displaced.
Do not claim literal conformance to an inconsistent input. Otherwise retain a
source-bound clarification question; multiple plausible interpretations are
not resolved by guessing. A later authorized clarification uses the existing
review-correction/fresh-review path, preserving consumed questions and tests.
A prior PASS bit does not prove an implementation or supply a missing fact.
Fresh blind authoring/review must not read prior solutions, scores, sibling
problems, hidden tests or references. An expressly authorized history-informed
continuation is a different evidence scope and must be disclosed as such.
Neither a lesson nor a golden result can override a current explicit input.
**Why not Bucket A:** detecting inconsistent meaning, authority and a unique
intended interpretation is not a closed syntax transformation. Existing
`spec_review_lint.py` and review-correction validation enforce the structural
and provenance portions; no automatic contradiction waiver is introduced.
Files in this package (3)
- SKILL.md 6 KB
- compliance.yaml 1 KB
- tests/test_compliance.py 8 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · vibeic/vibe-ic | 100 | Apache-2.0 |
| dxos/dxos | 100 | Apache-2.0 |
| xoai/sage | 100 | MIT |
| komluk/scaffolding | 100 | MIT |
| Mosin112/pm-harness | 100 | MIT |
| lukedj78/dev-flow | 100 | MIT |
| microsoft/winappcli | 100 | MIT |
| robruiz/rob-ruiz-skills | 100 | MIT |
| r-hatim/hrih-skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version 18e6f443f8cc (SHA-256 digest of the entire package)
Downloads in the last 30 days: 2 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 95Spec
Generate feature specifications from natural language descriptions with foundation-aware template selection and clarification cycles. USE WHEN spec, specification, feature spec, requirements, document feature, create spec, write spec, PRD, product requirements. - 100rtl-specification-consistency-checker
Check behavioral consistency between high-level hardware specifications and RTL implementations. Use when asked to check RTL consistency, verify RTL against spec, check hardware specification compliance, validate RTL implementation, find spec violations in RTL, check behavioral… - 92arch-review
Read-only architecture review of RTL vs uArch spec with area/timing/power tradeoffs. Use for post-RTL architecture sign-off or suspected spec mismatch. - 100analyze-spec
Analyze an existing spec for inconsistencies, missing information, ambiguities, and structure issues. Use when user says "analyze spec", "review spec", "spec quality check", "validate requirements", "audit spec", or "check spec quality". - 100logic-gatekeeper
Validates requirements for ambiguity and physical hardware constraints. Use this after requirements are generated but before code/hardware synthesis begins. - 100spec-driven-development
Creates specs before coding, with hard rules against silently filled assumptions and untestable success criteria. Use when starting a new project, feature, or significant change and no specification exists yet. Triggers on "build me", "create a", "add a feature", or any…