recap

Files (1)

• SKILL.md

SKILL.md (first lines)

# Recap

Turn an approved SpecScore Feature plus its latest verify report into a per-AC drift report. Close the SpecStudio pipeline's recap slot so `review` and `ship` have an honest drift gate to consume.

## Hard Gate

<HARD-GATE>
Do NOT invoke `specstudio:ideate`, `specstudio:specify`, `specstudio:plan`, `specstudio:implement`, `specstudio:verify`, `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}`, the Feature exists at git HEAD (`git cat-file -e HEAD:spec/features/<feature-slug>/README.md` exits zero), AND `spec/features/<feature-slug>/_verify/` exists and contains at least one `<sha>.md` report file reachable at HEAD.
  2. The Feature parsed cleanly via the `specscore` CLI's Feature parser; the ordered AC ID list is available.
  3. The verify report has been resolved (preferring the report whose `<sha>` matches `git rev-parse --short HEAD`; otherwise the report whose embedded `revision:` YAML field is most recent in branch history) and its top-of-file YAML summary block has been parsed into a per-AC `{verify_verdict, verify_justification}` map.
  4. The report has been written to `spec/features/<feature-slug>/_recap/<sha>.md` with a fenced ` ```yaml ` summary block (top-level `feature:`, `revision:`, `verify_revision:`, and `drift:` list with one entry per AC) followed by one `## AC: <ac-slug>` body section per AC.
  5. The `_recap/README.md` index has been created (if absent) or updated with the current run's row (if present), per `## Report Format → Index README`.
  6. Both the report and the `_recap/README.md` index are in the publication manifest and the `recap.completed` publication checkpoint has been resolved, disclosed, and applied.
  7. The `recap.completed` event has been emitted exactly once.

The only skill invoked after `specstudio:recap` is `specstudio:review` (or — while `review` is unshipped — a hand-back to the user with the report path and a recommendation to inspect drift items manually). The skill MUST NOT invoke `ideate`, `specify`, `plan`, `implement`, `verify`, `ship`, `writing-plans`, `frontend-design`, or `mcp-builder` on transition.
</HARD-GATE>

## When to Use

- An approved Feature at `spec/features/<feature-slug>/README.md` exists in git HEAD, `specstudio:verify` has already produced at least one report at `spec/features/<feature-slug>/_verify/<sha>.md`, and the user wants a per-AC drift verdict comparing what the spec asks for against what the commits actually delivered.
- `specstudio:verify` has just transitioned via its `transition-to-recap` REQ and the user wants to continue the pipeline.
- The user wants to re-recap a Feature after additional `Verifies:`-trailed commits and a fresh verify run 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 Feature's `_verify/` directory does not exist or contains zero `<sha>.md` report files reachable at HEAD → recommend running `specstudio:verify <feature-slug>` first. Write no report. Exit non-zero. Recap-without-verify is a category error: there is nothing to recap against. (AC: `refuses-when-no-verify-report`)
- 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` (when unshipped), or any non-`review` skill → refuse; the only permitted downstream transition is `specstudio:review`.

## 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. The `Verifies:` trailer convention requires the Feature to exist in git history.
4. **Verify-report-presence guard.** Check that `spec/features/<feature-slug>/_verify/` exists AND contains at least one `<sha>.md` file reachable at HEAD. If the directory is absent, or it exists but contains zero `<sha>.md` reports reachable at HEAD, refuse with a recommendation to run `specstudio:verify <feature-slug>` first, write no report, and exit non-zero.
5. **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. **Resolve and parse the verify report.** Auto-resolve the latest `_verify/<sha>.md` report at HEAD:
   - **First preference:** the report file whose `<sha>` matches `git rev-parse --short HEAD` exactly.
   - **Fallback:** the report whose embedded top-of-file YAML `revision:` field is most recent in the branch's git history (use `git log` over `_verify/` paths to determine recency).

   Parse the resolved report's top-of-file fenced YAML summary block and build a per-AC map keyed by `<feature-slug>#ac:<ac-slug>` whose value is `{verify_verdict, verify_justification}`. Record the resolved report's path (e.g., `spec/features/<feature-slug>/_verify/<verify-sha>.md`) and its `revision:` value — both flow into the recap report's YAML (`verify_revision:`) and the event payload (`verify_report_path`). Parse failures on the verify report's YAML block MUST stop the skill with a clear error identifying the unparseable file. The skill MUST NOT accept a `--report <path>` override in MVP.
4. **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 drift-narrator subagent fetches diffs on demand. An AC with zero matching commits is recorded as `unmapped` (orchestrator-produced) and skipped for subagent dispatch.
5. **Dispatch drift-narrator subagents serially.** For each mapped AC (commit count ≥ 1) in Feature AC order, dispatch one drift-narrator subagent via the Agent tool with `subagent_type: general-purpose`. Construct the prompt per `## Drift-Narrator 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 narrator subagent be concurrently in flight.
6. **Parse the verdict.** Validate per `## Drift-Narrator Subagent Contract`. On a malformed first response, re-dispatch the same subagent exactly once with a corrective prompt that quotes the failure (verdict outside `{no-drift, spec-tighter-than-code, code-tighter-than-spec, contradiction}`, missing narrative, or narrative exceeding 500 characters) and reiterates the verdict contract. On a malformed second response, record the AC's drift verdict as `error` (orchestrator-produced) and MUST NOT call the subagent a third time.
7. **Tally counts.** Compute six non-negative integer counts over the full AC list: `no_drift_count`, `spec_tighter_count`, `code_tighter_count`, `contradiction_count`, `unmapped_count`, `errored_count`. Their sum equals the Feature's total AC count.
8. **Write the report.** Create `spec/features/<feature-slug>/_recap/` if absent. Write the report file to `spec/features/<feature-slug>/_recap/<sha>.md` per `## Report Format` below.
9. **Write or update the `_recap/README.md` index.** Per `## Report Format → Index README` below. If absent, create it with one row in `## Contents`. If present, append one row (newest-last) for the current run, preserving prior rows. Without this step the project's `readme-exists` lint rule will fail on the newly created `_recap/` directory.
10. **Publication checkpoint.** Add `spec/features/<feature-slug>/_recap/<sha>.md` and `spec/features/<feature-slug>/_recap/README.md` to the manifest. Apply [publication-policy.md](../shared/publication-policy.md) for `recap.completed`, staging only manifest paths and committing/pushing only when policy and safety allow.
11. **Emit `recap.completed`.** Per `## Event Emission` below, including `publication_result`. Exactly once per successful run.
12. **Transition.** Per `## Promotion Boundary` below. Only `specstudio:review` (or hand-back when `review` is unshipped).
13. **Determine exit code.** Per `## Exit Semantics` below. Non-zero iff `contradiction_count + errored_count > 0`. Otherwise zero.
14. **Throughout** — watch for sidekick ideas (e.g., a flaky drift-narrator shape, a recurrent verify-vs-recap disagreement pattern, a deferred plan-completeness check). 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.

## Drift-Narrator Subagent Contract

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

### Prompt shape (five 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. **Verify verdict carry-over (verbatim).** The AC's verify verdict and verify justification snippet copied verbatim from the resolved `_verify/<sha>.md` report's YAML summary block for the same AC ID. Format:

   ```
   ## Verify result for this AC

   - verdict: <pass | fail | error | unmapped>
   - justification: <one-line snippet as recorded in the verify report>
   ```

   The carry-over is verbatim by contract; it gives the drift-narrator the orienting baseline of what verify itself concluded.
3. **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.
4. **Drift verdict contract (verbatim).** Quote the following block into the prompt verbatim, so the subagent knows the required output shape:

   ```
   Return exactly one drift verdict from the set:
     {no-drift, spec-tighter-than-code, code-tighter-than-spec, contradiction}.

   Required output shape:

     verdict: <no-drift | spec-tighter-than-code | code-tighter-than-spec | contradiction>
     narrative: <one-line snippet, MAXIMUM 500 characters>
     evidence:
       - <file path, commit SHA, or _tests/<ac-slug>.md reference>
       - ...

   Verdict semantics:
   - `no-drift`                  = the code matches what the AC requires.
   - `spec-tighter-than-code`    = the spec requires more than the code delivers.
   - `code-tighter-than-spec`    = the code enforces stricter behavior than the spec named.
   - `contradiction`             = the code does something the spec actively disallows
                                   or does not name as a valid alternative.

From specscore/specstudio-skills, MIT.

More from specscore/specstudio-skills