| name | verify-interpreter |
| description | Interpret the output of `specgraph verify` and explain what each status means and what to do next. |
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 |
SKIP | Spec has no evidence requirements (draft/deprecated) | Review if state is correct |
WAIVED | Requirement waived — check expiry | Verify waiver is still valid |
Verify commands reference
specgraph verify
specgraph verify --json
specgraph explain <SPEC-ID>
specgraph find <SPEC-ID>
specgraph waivers
specgraph subject issue:beads:BD-xx
Interpretation checklist
- Count PASS / WARN / FAIL counts — overall health indicator.
- For each FAIL: run
specgraph explain <ID> to see what claims exist.
- For each WARN: check if the evidence level matches the spec's
state requirements.
- Check waiver expiry dates — expired waivers flip to WARN/FAIL.
- Confirm
provider_runs 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 |
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 |
Rules
- Never dismiss a FAIL without understanding the root cause.
- Use
specgraph explain before deciding whether to add evidence or a waiver.
- Report the exact spec IDs and dimensions in any gap summary you produce.
