What SpecScore
validates.
SpecScore is an open Markdown format for features, requirements, and acceptance criteria — checked by two validators: a deterministiclinter and an AI reviewer. Here's what each one catches, and where automated checking stops.
New to SpecScore? Start here ·The CLI ·AI Skills
$ specscore lint checkout/ ✓ 24 requirements — structure, references, IDs valid ✓ no index drift · no broken links · no slug collisions 0 problems exit 0
Three layers, not one.
SpecScore validates in layers, cheapest and most certain first.Lint is deterministic — fast, free, runs on every commit. AI review is probabilistic — deeper, costs tokens, catches things lint can't reach. Human judgmentis the third layer: the seams the first two can't close still need a person — no tool can close them reliably today. The two automated layers are complementary, not redundant: lint catches what AI can't defend; AI catches what lint can't reach.
What each validator checks.
CLI linter
deterministicSame result every run, no LLM, no cost. If it passes here, it's a fact — not an opinion.
$ specscore lint apply-discount.md ✓ R1 has acceptance criteria ✓ R2 has acceptance criteria ✗ R3 no acceptance criteria ✗ link "Related Feature: discount-tiers" not found ✗ section "Open Questions" missing 3 problems exit 1
- Referential integrity — links resolve, IDs are unique
- Structural conventions — required sections, frontmatter shape
- Status hygiene and index drift
- Slug collisions
- Prefix validity on metadata fields (e.g.
Related Ideas:)
AI review & score
non-deterministicReads for meaning, the way a human reviewer would — and like a human, it isn't perfectly repeatable.
> /score apply-discount.md Grade: B — ready with edits AC-2 vague trigger — name the actor and event AC-3 no error path for an expired code prose reads clean; criteria need tightening
- ACs phrased as verifiable Given/When/Then
- Internal consistency within an artifact
- Vague or placeholder content
- Readability for a human reviewer
- Author-actionable, severity-marked feedback
- An A–F readiness grade
What they don't catch.
No validator is magic. Here's where each one stops — so you know exactly where your own judgment still has to do the work.
CLI linter
- Implicit contradictions across deep hierarchies
- Drift between spec and code (improving as
specstudio:recaplands) - Semantic correctness of acceptance criteria
- Whether a name actually makes sense
- Whether the requirements solve the stated problem
AI review & score
catches inconsistently- Full run-to-run reproducibility — verdicts may shift within tolerance
- Cross-artifact contradictions across a large tree without explicit cross-checks
- Whether requirements truly solve the problem — flags obvious gaps, misses domain-specific ones
- Biases inherited from the underlying LLM
- Semantic correctness with absolute certainty
- Anything the rubric doesn't weight
- 1
Lint reaches here
Structure, references, hygiene. Cheap and certain — but blind to meaning.
- 2
AI reaches here
Meaning, clarity, consistency within an artifact. Deeper — but probabilistic, and weak across a large tree.
- 3
Still on you
Cross-cutting judgment over the whole system — work no tool can do reliably today, so it still takes a human reviewer.
The case neither tool will save you from
Picture a real, deep spec tree. Feature A requires X. Feature B requires Y. Feature C requiresZ. Then feature D quietly requires something that contradicts B — but only when A is also active. Lint sees four valid, well-linked documents and passes. The AI reviewer, reading artifacts one at a time, has no reason to load all four and notice the three-way interaction.
Neither layer reliably catches this — and we're not going to pretend otherwise. This exact class of contradiction is why the third layer exists. SpecScore's job is to make the tree navigable enough that a human reviewing the seams can findthe conflict — open questions propagate up the hierarchy, related requirements are one query away — not to claim a tool already found it.