speckit-harness-report

name	speckit-harness-report
description	Synthesize curated evidence and verification records into the feature's research.md with a coverage table
compatibility	Requires spec-kit project structure with .specify/ directory
metadata	{"author":"github-spec-kit","source":"harness:commands/speckit.harness.report.md"}

Research Report — Harness → Spec Kit Artifacts

Bridge the externalized harness state back into the standard spec-kit artifact flow: synthesize the curated set, evidence links, and verification records into the active feature's research.md, with an explicit coverage table showing which requirements rest on verified evidence — the curated-set quality measure of Harness-1 (arXiv:2606.02373), applied to specs.

Run this when exploration/verification is done (or budget is spent), before /speckit.plan consumes the research.

User Input

$ARGUMENTS

Optional. A scope filter (only synthesize matching topics) or an alternative output path. Default output: FEATURE_DIR/research.md.

Prerequisites

Resolve HARNESS_DIR as in /speckit.harness.init; require an initialized harness. This command reads the FULL state files (it is the one command that does) plus spec.md if present.

Steps

1. Load and cross-link

Read curated.md, evidence.md, verification.md, budget.md, and the feature's spec.md (if present). Build the requirement → evidence map: for each requirement / user story / open question in spec.md, collect curated entries whose evidence Supports: field references it, plus any obvious topical matches (mark the latter inferred).

2. Compute coverage

For each requirement, classify:

• covered-verified — ≥1 supporting curated entry whose claim is verified.
• covered-unverified — supporting evidence exists, none verified.
• contradicted — a supporting entry was refuted.
• uncovered — no evidence at all.

Coverage score = covered-verified / total requirements (report the raw fraction, e.g. "7/10 requirements verified").

3. Write research.md

If research.md exists, preserve any hand-written sections and replace only the block between <!-- harness:begin --> and <!-- harness:end --> (append the markers if absent). Inside the block:

<!-- harness:begin -->
## Research Summary (Research Harness)
Generated by /speckit.harness.report on <date>. State: specs/<feature>/harness/

### Verdict
<3–8 sentences: what the research established, citing evidence IDs>

### Requirement Coverage — <score>
| Requirement | Status | Evidence | Verification |
|-------------|--------|----------|--------------|
| FR-001 <short title> | covered-verified | E003, E007 | V002 (high) |
...

### Key Findings (curated set)
<curated entries grouped critical → low; each: finding, source pointer, verification status>

### Corrected Assumptions
<refuted claims: what was believed, what is actually true, record ID — or "none">

### Open Questions
<uncovered/unverifiable items + what would resolve each (access, budget, a decision)>

### Method & Budget
<1 line: actions spent per resource, stop reason, link to budget.md>
<!-- harness:end -->

4. Report

Output: the coverage score and table; refuted-claim corrections that should flow into spec.md/plan.md (as suggested edits — do not apply them); open questions; and the recommended next step:

• coverage strong + no contradictions → proceed to /speckit.plan (or /speckit.tasks if planning is done).
• contradictions present → fix the artifacts first (/speckit.clarify).
• significant uncovered requirements → /speckit.harness.explore if budget remains, otherwise flag the risk explicitly so the plan inherits it as a known unknown.

Guardrails

• Never invent evidence: every row in the coverage table must cite real evidence.md IDs; requirements with nothing supporting them are uncovered, not silently omitted.
• Preserve human edits in research.md outside the harness markers.
• Keep the report self-contained: a reader (or /speckit.plan) must not need the conversation transcript to use it.
• This command edits only research.md (or the path given in $ARGUMENTS) — never spec.md, plan.md, or the harness state files themselves.