spec-kitty-mission-review

# spec-kitty-mission-review

You are the expert senior reviewer for a completed Spec Kitty mission. The
mission has been fully implemented, all WPs have been approved, and the feature
branch has been merged. Your job is to answer a single question with documented
evidence: **does the merged code accurately and completely realize the spec, and
are there risks the implementation team did not surface?**

This is not a checklist exercise. It is structured adversarial analysis. You
read the spec as the author's promise and the code as the executor's delivery,
and you measure the gap. Every finding you produce must be traceable to an
artifact (a spec section, a git diff line, a test file, a contract clause). You
do not fix anything. You document.

---

## When to Use This Skill

- After `spec-kitty merge --mission <slug>` completes and all WPs show `done`
- Before tagging a release that depends on this mission's changes
- When a downstream team needs a sign-off on spec→code fidelity
- When you suspect a WP review was too narrow and cross-WP holes exist

This is not the pre-merge acceptance gate. Run `spec-kitty accept --mission
<slug>` before merge; use this skill after merge for final spec-to-code review.
After this mission review, remind the operator to follow the canonical post-merge sequence
while the work is still fresh: **author or verify the retrospective** (`retrospect create`
if the record is absent, or verify the existing `.kittify/missions/<mission_id>/retrospective.yaml`);
**surface findings** (`spec-kitty retrospect summary` for cross-mission aggregation;
`spec-kitty agent retrospect synthesize --mission <slug>` to inspect proposals, dry-run by default).

---

## Step 1: Orient — Load Mission Identity and Status

Before reading a single line of code, anchor yourself to what the mission
promised and where it stands.

```bash
# Confirm the mission is fully merged (all WPs must be done)
spec-kitty agent tasks status --mission <slug>
```

If any WP is not in `done`, this is not a post-merge mission review — use
`spec-kitty-runtime-review` instead.

```bash
# Read the mission identity
cat kitty-specs/<slug>/meta.json
```

Note the `baseline_merge_commit` (the SHA of the PR that preceded this mission,
if present) and `mission_type`. These anchor every git diff you will run.

```bash
# Scan the event log for the full state machine history
cat kitty-specs/<slug>/status.events.jsonl
```

The event log tells you: how many rejection cycles each WP had, which WPs were
forced (unusual transitions that bypassed normal flow), whether any WPs were
approved by arbiter override rather than clean review, and whether any WP has a
`ReviewerSelfApproval` event. A WP with 3+ rejection cycles that ended in an
arbiter-forced approval is a high-priority target for your analysis — the
disagreement history is a signal. A WP with `ReviewerSelfApproval` is also
high-priority: flag it as an independence/process risk and verify whether an
independent reviewer later re-reviewed it.

---

## Step 2: Absorb the Full Mission Contract

You cannot review what you do not understand. Read the full specification and
all contract artifacts before looking at code.

```bash
# The specification: goals, non-goals, locked decisions, FRs, NFRs, constraints
cat kitty-specs/<slug>/spec.md

# The technical design per track
cat kitty-specs/<slug>/plan.md

# The WP breakdown: subtasks, FR references, DoD per WP, FR coverage table
cat kitty-specs/<slug>/tasks.md

# Acceptance test scenarios (canonical test contract layer)
cat kitty-specs/<slug>/contracts/test-contracts.md

# CLI behavior contracts (what commands must and must not do)
cat kitty-specs/<slug>/contracts/cli-contracts.md

# File format contracts (schema expectations, migration story)
cat kitty-specs/<slug>/contracts/file-format-contracts.md
```

As you read, build a mental model of:

1. **What the spec explicitly forbids** (Non-Goals and "MUST NOT" clauses) — these
   are the easiest violations to detect and the most expensive to have shipped.
2. **What the spec locks** (Decisions) — any code that re-opens a locked decision
   is a drift finding regardless of whether the code "works".
3. **What the spec assumes but never states** ("invisible holes") — read Goals and
   Acceptance Criteria looking for implicit assumptions. For example, a goal
   that says "a fresh install works" assumes the version in `metadata.yaml`
   matches `pyproject.toml` — but if the spec never stated that as an FR, no
   test will catch it. These are your highest-value findings.

---

## Step 3: Load the Git Timeline

Establish a clean baseline-to-HEAD picture. Every code change since baseline
is the implementation's evidence. Anything in the spec that produced no diff
is suspect.

```bash
# What changed since the baseline commit?
# Use baseline_merge_commit from meta.json
git log <baseline_merge_commit>..HEAD --oneline

# Summary of changed files — use this to build your review coverage map
git diff <baseline_merge_commit>..HEAD --stat

# Full diff (for large missions, scope by directory first)
git diff <baseline_merge_commit>..HEAD -- src/
git diff <baseline_merge_commit>..HEAD -- tests/
git diff <baseline_merge_commit>..HEAD -- docs/
```

Build a **coverage map** from the diff stat: which files changed, and which
spec tracks they correspond to. Then invert the map: are there files that a
spec track required to change that do NOT appear in the diff? Missing changes
are often more important than the changes that exist.

For each WP, cross-reference owned files from its frontmatter:

```bash
# Read each WP's owned_files declaration
cat kitty-specs/<slug>/tasks/WP01-*.md | head -40
```

Then verify the claimed owned files actually appear in the diff:

```bash
git diff <baseline_merge_commit>..HEAD -- <owned_file_path>
```

A WP that declares ownership of a file that shows no diff is either incomplete
or its work was done in a different file than declared. Determine which.

---

## Step 4: Read the