verify

Files (1)

• SKILL.md

SKILL.md (first lines)

# Verify

Turn an approved SpecScore Feature plus its `Verifies:` commit trailers into a per-AC verdict report. Close the SpecStudio pipeline's verify slot so `recap` has an honest gate to consume.

## Hard Gate

<HARD-GATE>
Do NOT invoke `specstudio:ideate`, `specstudio:specify`, `specstudio:plan`, `specstudio:implement`, `specstudio:review`, `specstudio:ship`, `writing-plans`, `frontend-design`, `mcp-builder`, or ANY other skill until ALL of the following are true:
  1. Pre-flight passed: the input slug resolves to `spec/features/<feature-slug>/README.md`, the Feature's `**Status:**` is in `{Approved, Implementing, Stable}`, and the Feature exists at git HEAD (`git cat-file -e HEAD:spec/features/<feature-slug>/README.md` exits zero).
  2. The Feature parsed cleanly via the `specscore` CLI's Feature parser; the ordered AC ID list is available.
  3. The report has been written to `spec/features/<feature-slug>/_verify/<sha>.md` with a fenced ` ```yaml ` summary block followed by one `## AC: <ac-slug>` body section per AC.
  4. The `_verify/README.md` index has been created (if absent) or updated with the current run's row (if present), per `## Report Format → Index README`.
  5. Both the report and the `_verify/README.md` index are in the publication manifest and the `verify.completed` publication checkpoint has been resolved, disclosed, and applied.
  6. The `verify.completed` event has been emitted exactly once.

The only skill invoked after `specstudio:verify` is `specstudio:recap` (or — while `recap` is unshipped — a hand-back to the user with the report path and a recommendation to review verdicts manually).
</HARD-GATE>

## When to Use

- An approved Feature at `spec/features/<feature-slug>/README.md` exists in git HEAD and the user wants a per-AC verdict on the work already committed.
- `specstudio:implement` has just transitioned via its `transition-to-verify` REQ and the consolidated batch has been committed.
- The user wants to re-verify a Feature after additional `Verifies:`-trailed commits have landed.

**Refuse and redirect when:**

- The Feature's `**Status:**` is `Draft` or `In Review` → print the current Status and recommend `specstudio:specify` to re-approve. Write no report. Exit non-zero. (AC: `refuses-draft-feature`)
- The Feature exists only in the working tree (uncommitted) → instruct the user to commit the Feature first. Write no report. Exit non-zero. (AC: `refuses-uncommitted-feature`)
- The user asks the skill to bypass publication policy, commit unrelated paths, or push without branch-policy approval → refuse.
- The user asks the skill to invoke `ship`, `review`, or any non-`recap` skill → refuse; the only permitted downstream transition is `specstudio:recap`.

## Pre-Flight

1. **Resolve input.** The skill MUST accept exactly one positional argument — the Feature slug — and resolve it to `spec/features/<feature-slug>/README.md`.
2. **Status guard.** Read the Feature's body-metadata `**Status:**` line. Refuse if it is outside `{Approved, Implementing, Stable}`. On refusal, print the current Status, recommend `specstudio:specify` to re-approve, write no report, and exit non-zero.
3. **HEAD-existence guard.** Run `git cat-file -e HEAD:spec/features/<feature-slug>/README.md`. On non-zero exit, refuse with an instruction to commit the Feature first, write no report, and exit non-zero. This mirrors `implement`'s pre-flight discipline — the `Verifies:` trailer convention requires the Feature to exist in git history.
4. **Resolve HEAD SHA.** Capture `git rev-parse --short HEAD` once. This SHA is the `<sha>` in the report path and the `revision` in the YAML summary and the event payload.

## Checklist

Create a task for each and complete in order:

1. **Pre-flight** (steps above). Refusals exit immediately; do not proceed.
2. **Parse the Feature.** Delegate to the `specscore` CLI's Feature parser. Surface the ordered list of AC IDs in the form `<feature-slug>#ac:<ac-slug>` paired with each AC's full `Given / When / Then` text. Parse failures stop the skill with the CLI's lint-rule citation surfaced verbatim to the user.
3. **Collect commits per AC.** For each AC ID in Feature order, run:

   ```
   git log --extended-regexp --grep='^Verifies:.*<feature-slug>#ac:<ac-slug>' --format='%H%n%s%n%b%x00'
   ```

   Collect the matching commit SHAs in chronological (oldest-first) order paired with their commit messages (subject + body). Do NOT pre-fetch commit diffs — the subagent fetches diffs on demand. An AC with zero matching commits is recorded as `unmapped` and skipped for subagent dispatch.
4. **Dispatch verifier subagents serially.** For each mapped AC (commit count ≥ 1) in Feature AC order, dispatch one verifier subagent via the Agent tool with `subagent_type: general-purpose`. Construct the prompt per `## Verifier Subagent Contract` below. Wait for the subagent to return a parseable verdict before dispatching the next AC's subagent. At no point during the run MUST more than one verifier subagent be concurrently in flight.
5. **Parse the verdict.** Validate per `## Verifier Subagent Contract`. On a malformed first response, re-dispatch the same subagent exactly once with a corrective prompt that quotes the failure (verdict outside `{pass, fail, error}`, missing justification, or justification exceeding 400 characters) and reiterates the verdict contract. On a malformed second response, record the AC's verdict as `error` and MUST NOT call the subagent a third time.
6. **Tally counts.** Compute `passed_count`, `failed_count`, `unmapped_count`, `errored_count` over the full AC list. Each is a non-negative integer; their sum equals the Feature's total AC count.
7. **Write the report.** Create `spec/features/<feature-slug>/_verify/` if absent. Write the report file to `spec/features/<feature-slug>/_verify/<sha>.md` per `## Report Format` below.
8. **Write or update the `_verify/README.md` index.** Per `## Report Format → Index README` below. If absent, create it with one row in `## Contents`. If present, append one row for the current run, preserving prior rows. Without this step the project's `readme-exists` lint rule will fail on the newly created `_verify/` directory.
9. **Publication checkpoint.** Add `spec/features/<feature-slug>/_verify/<sha>.md` and `spec/features/<feature-slug>/_verify/README.md` to the manifest. Apply [publication-policy.md](../shared/publication-policy.md) for `verify.completed`, staging only manifest paths and committing/pushing only when policy and safety allow.
10. **Emit `verify.completed`.** Per `## Event Emission` below, including `publication_result`. Exactly once per successful run.
11. **Transition.** Per `## Promotion Boundary` below. Only `specstudio:recap` (or hand-back when `recap` is unshipped).
12. **Determine exit code.** Per `## Exit Semantics` below. Non-zero iff `failed_count + errored_count > 0`. Otherwise zero.
13. **Throughout** — watch for sidekick ideas (e.g., a flaky subagent shape, a deferred AC-coverage gap surfacing during verification). When an out-of-scope improvement surfaces, invoke `specstudio:sidekick` with a one-liner, acknowledge in one line, and return to the current checklist step immediately. Do not derail.

## Verifier Subagent Contract

Each verifier subagent is dispatched with an **isolated prompt** — it MUST NOT inherit the parent session's context. Construct the prompt freshly per AC.

### Prompt shape (four required parts, in this order)

1. **AC identification and full text.** The AC ID (`<feature-slug>#ac:<ac-slug>`) followed by its complete `Given / When / Then` text quoted verbatim from the source Feature.
2. **Matching commits.** The ordered list of commit SHAs (chronological, oldest-first) paired with each commit's full message (subject + body). Format:

   ```
   ## Matching commits

   - <sha-1>
     <commit message subject + body>
   - <sha-2>
     <commit message subject + body>
   ```

   The orchestrator MUST NOT include pre-fetched commit diffs in the prompt. The subagent fetches diffs and reads source files on demand via its own Bash tool.
3. **Verdict contract (verbatim).** Quote the following block into the prompt verbatim, so the subagent knows the required output shape:

   ```
   Return exactly one verdict from the set: {pass, fail, error}.

   Required output shape:

     verdict: <pass | fail | error>
     justification: <one-line snippet, MAXIMUM 400 characters>
     evidence:
       - <file path, commit SHA, or reference>
       - ...

   - `pass`   = the matching commits satisfy the AC's `Then` clause.
   - `fail`   = the matching commits do NOT satisfy the AC's `Then` clause.
   - `error`  = you cannot reach a verdict (e.g., a commit is unreachable, a referenced
                file is missing, the AC text is ambiguous in a way that no diff can resolve).

   The value `unmapped` is produced only by the orchestrator for ACs with zero matching
   commits and MUST NOT appear in your response.

   Malformed responses (verdict outside the allowed set, missing justification, or
   justification exceeding 400 characters) will be re-dispatched exactly once with a
   corrective prompt; a second malformed response is recorded as `error`.
   ```

4. **Fetch-on-demand instruction.** An explicit instruction that the subagent fetches commit diffs and reads source files on its own via Bash. Suggested commands to mention:

   ```
   git show <sha>
   git show <sha> -- <path>
   git show <sha> --stat
   cat <path>
   ```

   Include the guidance: "Read at the depth required to reach a verdict; do not enumerate every file in every commit if the verdict is obvious from one diff."

### Out of scope for the prompt

From specscore/specstudio-skills, MIT.

More from specscore/specstudio-skills