45ck Read and explain the output of specgraph verify in plain language, then recommend next steps.
Status meanings
| Status | Meaning | Action |
|---|---|---|
PASS |
All required evidence thresholds met | Nothing required |
WARN |
Evidence exists but below required strength for this state | Strengthen evidence or lower requirement |
FAIL |
No evidence found for a required dimension | Add evidence or add waiver |
INSUFFICIENT |
Evidence found but strength is below required level | Raise evidence strength (e.g. E0 → E2) |
SKIP |
Spec has no evidence requirements (draft/deprecated) | Review if state is correct |
WAIVED |
Requirement waived — check expiry | Verify waiver is still valid |
Example output
PASS FEAT-001 [accepted]
WARN FEAT-002 [in_progress]
warn: No verification claims found (advisory)
FAIL FEAT-003 [accepted]
fail: No implementation claims found. Required: E2 (indexed)
INSUFFICIENT FEAT-004 [accepted]
insufficient-evidence: implementation: found E0 but required E2
Verify commands reference
specgraph verify # summary table for all specs
specgraph verify --spec FEAT-001 # single spec only
specgraph verify --json # machine-readable output
specgraph verify --changed src/foo.ts # incremental scan (changed files only)
specgraph verify --no-db # dry run — skip writing to DB
specgraph explain <SPEC-ID> # full claim breakdown for one spec
specgraph explain # all specs
specgraph find --spec FEAT-001 # locate files that reference a spec
specgraph find --relation IMPLEMENTS # all IMPLEMENTS claims
specgraph find --provider annotation # claims from a specific provider
specgraph find --strength 1 # E1 and above
specgraph waivers # list active waivers
specgraph waivers FEAT-001 # waivers for one spec
specgraph subject issue:beads:bd-a1b2 # show a specific Beads issue's claims
specgraph subject symbol:annotation:MyClass # show a symbol's claims
Subject IDs follow the format kind:provider:identity (e.g. issue:beads:bd-a1b2, symbol:annotation:TodoStore).
Interpretation checklist
- Count PASS / WARN / FAIL / INSUFFICIENT counts — overall health indicator.
- For each FAIL: run
specgraph explain <ID>to see what claims exist. - For each INSUFFICIENT: check the
required_evidencethreshold in the spec frontmatter — lower it or add stronger evidence. - For each WARN: check if the evidence level matches the spec's
staterequirements. - Check waiver expiry dates — expired waivers flip to WARN/FAIL.
- Confirm provider scans are recent — stale scan data can hide real gaps.
Common causes
| Symptom | Likely cause | Fix |
|---|---|---|
| All specs FAIL | Annotations not scanned | Run specgraph verify again; check @spec syntax |
INSUFFICIENT on accepted specs |
Evidence is E0/E1, need E2+ | Add cross-refs or tests to raise strength |
WARN on accepted specs |
Evidence is E0/E1, need E2+ | Add cross-refs or tests |
| Unexpected PASS | Waiver is covering a gap | Check specgraph waivers for active waivers |
| Missing specs in output | Spec file not in docs/ |
Check path and .specgraph/config.json |
| Beads claims missing | Beads not enabled | Set beads.enabled: true in .specgraph/config.json |
Rules
- Never dismiss a FAIL without understanding the root cause.
- Use
specgraph explainbefore deciding whether to add evidence or a waiver. - Report the exact spec IDs and dimensions in any gap summary you produce.
- Config file is
.specgraph/config.json(falls back to.agent-docs/config.json).