review-coverage

Files (5)

• SKILL.md
• host-matrix.md · references/
• review_coverage.md · references/
• review_coverage.short.md · references/
• review-coverage · scripts/

SKILL.md (first lines)

# Review Coverage

**Plan directive + post-ship residual campaign** — not an exit hook and not a
second review-plan. Residual campaigns are **finite** (residual×2 success or
stopped halt) — never open loops.

```text
review-plan      →  plan quality (pre-exit)
review-coverage  →  plan directive + residual×2 after implement   ← THIS SKILL
review-converge  →  default residual×2 engine (one round / turn)
review-fix       →  optional first-pass code review before coverage
improve-loop     →  optional broader improve campaign
```

**Primary interface:** invoke this skill like any other skill. The agent follows
Phase A or Phase B below. Optional CLI helpers exist for humans/CI lint; they
are **not** required to run the skill.

## Invocation

```text
/review-coverage
/review-coverage <path-to-plan.md>
review-coverage on this plan
add Review Coverage to the plan
run residual×2 / post-ship coverage for this plan
```

| Situation | Mode |
|-----------|------|
| Plan exists, no filled `## Review Coverage` (or user asks to add/waive it) | **Phase A** |
| Implementation landed / user asks to run residual / improve-to-exhaustion | **Phase B** |
| Section already filled and user only wants status | Report filled/waived; offer Phase B if shipped |

Resolve the plan path from the invocation, the current session plan, or ask once.
Do **not** require the user to run shell scripts to use this skill.

### Optional helper binding from an installed package

Use a CLI helper only after the host has identified the **selected, loaded**
`SKILL.md`. Let `SKILL_ROOT` be the absolute directory containing that file and
bind the bundled helper from it for the current tool call:

```sh
# Replace this illustrative path with the selected absolute location before running.
SKILL_ROOT="/absolute/directory-containing-the-loaded-SKILL.md"
CLI="$SKILL_ROOT/scripts/review-coverage"
python3 "$CLI" template --short
```

Do not infer `SKILL_ROOT` from the user's project cwd, a source checkout,
`PATH`, a same-named skill, or a guessed cache layout. If the host presents a
skill-root alias, expand the alias selected for this loaded card first. Claude
Code may render `${CLAUDE_SKILL_DIR}` in card text on versions that support that
substitution; it is not a portable shell environment variable. Rebind the
absolute `CLI` in each independent shell call, quote it, and keep plan/run
state under the target repository rather than this package. If the bundled file
or `python3` is unavailable, report that prerequisite instead of falling back
to a similarly named executable.

## Definitions

| Term | Meaning |
|------|---------|
| **Review Coverage** | Durable plan **H2 only** `## Review Coverage` + this skill (H1/H3+ are not recognized). After ship: prove code matches specs and **stop** when proof is stable. |
| **Status / Log / landed** | Driver ledger at repo-root `REVIEW_CONVERGE.md`. **Landed** = latest Log `Committed: yes` and `review-converge: round N —`. |
| **residual** | Forward (specs→code) + reverse (diff vs Base ref); material fixes only; pathspec commits. |
| **clean / residual×2** | Clean = **only trivial findings remaining this cycle** (not “fixed some material and left minors”). Review success = two consecutive cleans with second-pass verification as defined below. Fixing material resets the streak. |
| **`/goal` body** | Outer multi-turn objective: **static complete-when sentence** + plan bindings (see below). Do not paraphrase the static sentence. |
| **`/review-converge`** | Default Driver: **one** residual round per outer turn. |
| **complete** | residual×2 review success + landed Log. Delivery success additionally requires the current-candidate Finalization record below. |
| **stopped (...)** | Terminal halt without residual×2 success; still ends `/goal`. |

### Static complete-when (byte-exact — do not paraphrase)

```text
quality review changes and consider improvements, review the last 10 git commit messages for learnings, anchoring each spec item in code changes and verify use cases/corner cases, git commit between each iteration with a verbose message with key learnings, complete when only trivial findings remaining for 2 consecutive cycles
```

### Host `/goal` line (operator paste — not agent-executable on Grok)

On Grok, `/goal` is a **user-typed pager slash**. The agent must not type it
and wait. Prefer CLI when available (avoids compose drift) **for the optional
operator paste**:

```sh
python3 "$CLI" goal-body --plan <ABS_PLAN> --slash
```

Show that output to the operator labeled **user-typed slash — not
agent-executable on Grok**. Fallback only if the CLI is missing: STATIC + the
same trailer fields/order as `references/review_coverage.md` (Plan absolute, Base
ref, Target paths, Test command, Driver one round, Max review-converge rounds + halt rules,
Ledger clean = only trivial findings remaining this cycle + landed SUCCESS, and
the Finalization current-candidate evidence, pathspec). Include `Repo:` when
set. Default Max review-converge rounds **N** = 12. The CLI
fills those slots and prints; it does not author the sentence. The **executable**
driver is in-session **review-converge** (or `update_goal` when that tool exists).

### Nesting

```text
/review-coverage (this skill)
  → Phase A: edit plan ## Review Coverage
  → Phase B: open host /goal with composed line
       → each turn: one /review-converge
```

## When to use

- Non-trivial **code** plans about to be approved — ensure `## Review Coverage` is in the plan.
- After implementation is green — run residual×2 under `/goal`.
- User asks for residual / improve-to-exhaustion / post-ship coverage.

Skip pure doc-only one-line plans unless the user asks.

## Phase A — Plan authoring / review (agent edits the plan)

1. Read the plan path (invocation, session plan, or ask once — host-neutral).

From whichguy/skill-craft, MIT.

More from whichguy/skill-craft