evidence-gap-review

Review the output of specgraph verify (or specgraph verify --json) and produce an actionable gap report.

Procedure

1. Run specgraph verify (or read the provided output).
2. For each spec with status WARN, FAIL, or INSUFFICIENT:
   • Identify the required evidence dimension(s) that are unmet.
   • State the current evidence level and what level is needed.
   • Suggest the lowest-effort action that would provide the required evidence.
3. Group findings by effort: low (annotation), medium (test), high (architecture decision).

Evidence-gap action map

Required level	Unmet because	Recommended action
E0	No @spec annotation	Add /** @spec ID @implements Feature */ to the implementation file
E1	No closed Beads issue or structural artifact	Create a Beads issue with --spec-id ID and close it when done
E2	Not indexed in specgraph DB / no linked artifact	Run specgraph verify to store claims, add cross-refs via depends_on
E3	No test annotation	Add /** @spec ID @verifies Feature */ to a test file
E4	No CI artifact	Configure freshness.artifacts in .specgraph/config.json

Status meanings

Status	Meaning
PASS	All required evidence thresholds met
WARN	Evidence exists but below required strength for this state
FAIL	No evidence found for a required dimension
INSUFFICIENT	Evidence found but strength is below required level (e.g. E0 found, E2 required)
SKIP	Spec has no evidence requirements (draft/deprecated)
WAIVED	Requirement waived — check expiry

Output format

For each gap, output:

SPEC-ID  [WARN|FAIL|INSUFFICIENT]  dimension=<name>  need=<Ex>  have=<Ey|none>
  → Action: <one-line description>

Then a prioritised action list (most impactful first).

Useful drill-down commands

specgraph verify                     # summary table for all specs
specgraph verify --json              # machine-readable output
specgraph verify --spec SPEC-ID      # single spec only
specgraph explain SPEC-ID            # full claim breakdown for one spec
specgraph find --spec SPEC-ID        # locate files that reference a spec
specgraph find --relation IMPLEMENTS # all IMPLEMENTS claims
specgraph find --strength 1          # E1 and above
specgraph waivers                    # list active waivers

Rules

1. Do not suggest adding waivers unless the requirement is genuinely unreachable.
2. Prefer adding annotations over creating new files.
3. If multiple specs share the same gap pattern, batch the fix into a single suggestion.
4. Check specgraph explain <SPEC-ID> for detailed claim breakdown when unsure what evidence exists.
5. Config file is .specgraph/config.json (falls back to .agent-docs/config.json).