swe-workflow-skills 0.6.3 → 0.7.0

package/VERSION

@@ -1 +1 @@
-0.6.3
+0.7.0

package/catalog.json

@@ -218,7 +218,7 @@
     },
     {
       "name": "plan-execution",
-      "description": "Execute an already-approved plan with discipline — batch tasks into verifiable checkpoints, verify each with fresh evidence before marking it done, log drift, and stop to re-plan when reality diverges from the plan's assumptions. Triggers: execute the plan, implement the approved plan, work through this plan, continue/resume the plan, next phase, checkpoint. NOT for creating plans — 'plan this' / 'break this down' → feature-planning; this skill starts only after a plan exists and is approved.",
+      "description": "Execute an already-approved plan with discipline — batch tasks into verifiable checkpoints, verify each with fresh evidence before marking it done, log drift, and stop to re-plan when reality diverges from the plan's assumptions. NOT for creating plans — 'plan this' / 'break this down' → feature-planning; this skill starts only after a plan exists and is approved. Triggers: execute the plan, implement the approved plan, work through this plan, continue/resume the plan, next phase, checkpoint.",
       "path": "plan-execution/SKILL.md"
     },
     {
@@ -323,7 +323,7 @@
     },
     {
       "name": "verification-before-completion",
-      "description": "Evidence gate before claiming work is done, passing, fixed, or deployed. Use before saying 'done', 'it works', or 'tests pass', or before committing, pushing, or opening a PR. Triggers: is it done, did it work, tests pass, verify, ready to commit, before I push, confirm the fix. Run the proving command fresh and read its output first.",
+      "description": "Evidence gate before claiming work is done, passing, fixed, or deployed. Use before saying 'done', 'it works', or 'tests pass', or before committing, pushing, or opening a PR. Run the proving command fresh and read its output first. Triggers: is it done, did it work, tests pass, verify, ready to commit, before I push, confirm the fix.",
       "path": "verification-before-completion/SKILL.md"
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swe-workflow-skills",
-  "version": "0.6.3",
+  "version": "0.7.0",
   "description": "A curated library of Claude Code Agent Skills covering the full software lifecycle, with orchestrator-routed activation that scales past the skill-listing budget.",
   "type": "module",
   "bin": {

package/skills/code-reviewing/SKILL.md

@@ -20,8 +20,14 @@ a PR):
 !`git diff --stat 2>/dev/null || true`
 
 If the summary above is empty or irrelevant to what you were asked to review,
-proceed with the code as provided. Before reviewing line-by-line, understand the
-big picture:
+proceed with the code as provided.
+
+**Called from the pre-commit gate?** When `verification-before-completion` routes
+here before a commit, the review target is `git diff --staged` — the change about
+to be published, not the whole branch. Scope to it, keep the pass proportionate to
+what tripped the gate, and report findings in time to fix them before the commit.
+
+Before reviewing line-by-line, understand the big picture:
 
 - **What is this code supposed to do?** Read the PR description, linked issue, or ask the user.
 - **What changed?** If reviewing a diff, understand the scope of changes — run the
@@ -47,6 +53,17 @@ the diff, run three greps before accepting it:
   exported just to silence the unused-symbol checker).
 - **Any consumer?** A new schema field, prop, or param that nothing reads or sets is
   speculative plumbing — the API looks finished but is wired to nothing.
+- **A comment in the wrong place?** For any new comment block of four or more lines,
+  ask what it explains. System-level rationale — why the component exists, what was
+  rejected, how it relates to other services — belongs in an ADR or architecture doc
+  with the comment reduced to a pointer; a local invariant the types can't express
+  stays inline; a restatement of the code goes nowhere. The essay-in-a-header rots
+  unread and is unfindable by anyone grepping the docs for it.
+- **A reference nobody can resolve?** `Phase 2`, `CP1.3`, `T02`, `finding #17`,
+  `checkpoint 3/5` in comments, names, or strings — check whether a **git-tracked**
+  document defines it (`git ls-files '*.md' | xargs grep -l`). Anchored, it's a real
+  cross-reference. Unanchored, it names a conversation the reader wasn't in: the
+  finding is "write the meaning instead of the label".
 - **Any doc still describing the old shape?** If the diff renames, removes, or adds
   something a user types or configures — a flag, env var, endpoint, config key,
   command, script, install step — grep the README and `docs/` for it, old name
@@ -67,8 +84,8 @@ Review the code against these categories, in order of importance. See [reference
 
 **Severity levels for findings:**
 
-- 🔴 **Blocker**: Must fix before merge (bugs, security issues, data loss risks) — including a doc the diff makes *wrong* where the doc is an instruction someone follows: install steps, setup commands, the API contract, config keys. A stale instruction fails for the next person, silently, and is worse than no instruction.
-- 🟡 **Suggestion**: Should fix, significantly improves quality (principle violations, missing tests, docs the diff leaves incomplete rather than wrong)
+- 🔴 **Blocker**: Must fix before merge (bugs, security issues, data loss risks) — including a doc the diff makes *wrong* where the doc is an instruction someone follows: install steps, setup commands, the API contract, config keys. A stale instruction fails for the next person, silently, and is worse than no instruction. **Secrets or real personal data in the diff are always blockers** — they survive removal in git history, so flag them before the commit, not after.
+- 🟡 **Suggestion**: Should fix, significantly improves quality (principle violations, missing tests, docs the diff leaves incomplete rather than wrong, misplaced comment essays, unanchored internal terminology)
 - 🔵 **Nit**: Optional improvement (naming, style, minor simplification)
 
 ### Step 4: Present Findings
@@ -105,7 +122,7 @@ These are the lenses through which code is examined:
 
 **Testability**: Is the code testable? Are there tests? Do tests test behavior or implementation?
 
-**Readability**: Can someone unfamiliar with this code understand it in one reading? Good naming, appropriate comments (why, not what), manageable function length.
+**Readability**: Can someone unfamiliar with this code understand it in one reading? Good naming, manageable function length, and comments that are both *why, not what* and **in the right place** — the why of a system belongs in an ADR the comment points at; the why of a line belongs on the line. Judge "unfamiliar" literally: a reader with the repo and nothing else, who was in none of the conversations that produced it.
 
 **Error Handling**: Are errors caught, logged, and handled appropriately? Are error messages helpful? See [references/error-handling.md](references/error-handling.md) for detailed patterns (null safety, exception context, caller-oriented exceptions).
 
@@ -123,4 +140,5 @@ These are the lenses through which code is examined:
 - `refactoring` — when the review surfaces code smells worth a structured cleanup
 - `code-slop-cleanup` — strip AI-slop patterns from the diff before (or instead of) debating them in review
 - `security-audit` — for a dedicated, deep security pass beyond the review checklist
-- `verification-before-completion` — verify the change actually runs before approving, not from the diff alone
+- `verification-before-completion` — verify the change actually runs before approving, not from the diff alone; also the pre-commit gate that routes staged diffs here
+- `architecture-design` — where a system-level rationale found in a comment belongs instead (an ADR)

package/skills/code-reviewing/evals/evals.json

@@ -21,9 +21,9 @@
       "prompt": "Can you review the changes in my last git commit?",
       "expected_output": "Should read the git diff, understand context from surrounding files, and perform a structured review.",
       "assertions": [
-        "Runs git diff or git show to read the changes",
-        "Reads surrounding code for context",
-        "For any new helper, export, or block, greps the repo beyond the diff for an existing twin, for importers, and for consumers (duplication / dead export / unconsumed surface are invisible in a single hunk)",
+        "Names the command that reads the change (git show / git diff HEAD~1) and scopes the review to that commit",
+        "Establishes the surrounding code as context for the review rather than judging the hunk in isolation",
+        "For any new helper, export, or block, states it will search the repo beyond the diff for an existing twin, for importers, and for consumers (duplication / dead export / unconsumed surface are invisible in a single hunk)",
         "Follows the structured review format (summary, blockers, suggestions, nits)",
         "Provides specific file:line references for findings"
       ]
@@ -89,6 +89,22 @@
         "Justifies the severity: a wrong instruction is followed and then fails, which is worse than a missing one",
         "Does NOT approve on 'code is consistent and CI is green' alone"
       ]
+    },
+    {
+      "id": 4,
+      "prompt": "The pre-commit gate routed you here. Review the staged diff: it adds `src/server/dashboard.ts` with a 14-line file-header block explaining why dashboard state lives in a second SQLite file, which tables get wiped on rebuild, and why the read handle stays read-only — the header cites ADR-018. Below that are two query functions, one commented `// Aggregates (Phase 4). Read-only.` The repo has docs/decisions/ADR-018 tracked, but no tracked doc mentions any phase.",
+      "pressure": [
+        "looks_good"
+      ],
+      "expected_behavior": "Scopes to the staged diff rather than the whole branch. Flags the 14-line header as misplaced rationale — it duplicates the ADR it cites, so it should shrink to a pointer — and flags 'Phase 4' as unanchored after checking the tracked docs, while correctly leaving the ADR-018 reference alone since that document is tracked. Assigns both as suggestions, not blockers.",
+      "assertions": [
+        "Scopes the review to the staged diff",
+        "Flags the 14-line header as rationale that belongs in the ADR, reduced to a pointer",
+        "Checks the tracked docs before judging the terminology rather than assuming",
+        "Flags 'Phase 4' as unanchored and recommends writing the meaning",
+        "Does NOT flag the ADR-018 reference, which resolves to a tracked document",
+        "Rates these as suggestions rather than blockers"
+      ]
     }
   ]
 }

package/skills/code-slop-cleanup/SKILL.md

@@ -33,8 +33,13 @@ Slop is relative — the same construct is correct in one place and slop in anot
 
 - **High**: debug leftovers, silent-failure handlers, stray working files
 - **Medium**: defensive theater on trusted paths, generic TODOs, unrequested backwards-compat shims, duplication of existing helpers
+- **Medium**: also unanchored internal terminology (`Phase 2`, `CP1.3`, `finding #17`) that no git-tracked doc defines — rewrite to the meaning
 - **Low**: comment slop, dead weight (unused imports, `=== true`, redundant returns), style inconsistent with the file
 
+Misplaced rationale — the multi-line header essay explaining a *system* instead of
+the code beneath it — is detected here but **routed, not deleted**: the reasoning
+belongs in an ADR, and deleting it loses something nothing else records.
+
 ### Step 4: Strip — Deletions Only, Production Code Only
 
 Apply removals highest severity first. Every edit must be a behavior-preserving deletion (or a trivial inlining a deletion forces). If removing something requires *rewriting* logic around it, that's refactoring — leave it and flag it.
@@ -71,6 +76,8 @@ The biggest slop category — duplication — is created at generation time and
 |--------|---------|
 | "This check might catch something someday" | If nothing upstream can produce that state, it's theater — and it hides the real bugs by normalizing noise. |
 | "The comments help junior developers" | Restating comments rot and mislead; code clarity helps juniors. Keep why-comments, cut what-comments. |
+| "This 12-line header explains the architecture — I'll delete it as comment slop" | It's misplaced, not worthless. Deleting it destroys reasoning nothing else records. Flag it for the ADR and leave the code alone. |
+| "Phase 3 is obviously meaningful, leave the reference" | Check before assuming: if no tracked doc defines it, it points at a conversation the reader wasn't in. Rewrite it to what it means. |
 | "I'll just fix this bug while I'm here" | Cleanup and fixes in one pass make both unreviewable. Flag it, route it, finish the cleanup. |
 | "Strip it all — defensive code is slop" | A boundary check is not slop. Over-removal breaks behavior, the one thing this pass must never do. |
 | "This test is obviously redundant, I'll just delete it" | "Obviously" is a guess; proof requires the behavior map. Route to `test-suite-design`. |

package/skills/code-slop-cleanup/evals/evals.json

@@ -52,6 +52,19 @@
         "Distinguishes provable slop from legitimate defensive code even under the lead's instruction",
         "Proposes a reduced-scope alternative (e.g. high-severity-only removals) rather than either full compliance or flat refusal"
       ]
+    },
+    {
+      "id": 2,
+      "prompt": "Deslop this branch before I open the PR. Biggest offender: src/sync/manifest.ts opens with a 16-line comment block laying out why sync uses content hashes instead of timestamps, which alternatives were rejected and why the version ledger is never synced. Classic AI comment bloat — nuke it. Also there's a `// retry budget (Phase 3)` on line 80.",
+      "pressure": ["authority", "looks_good"],
+      "expected_behavior": "Does not delete the 16-line block. Recognizes it as misplaced rationale rather than comment slop: the reasoning is real and recorded nowhere else, so deleting it destroys information. Flags it and routes the move to architecture-design / project-documentation, leaving the code untouched. Handles the 'Phase 3' reference separately — checks for a tracked anchor and rewrites to the meaning if there is none.",
+      "assertions": [
+        "Does NOT delete the 16-line rationale block despite being told to",
+        "Distinguishes misplaced rationale from comment slop",
+        "Routes the move to an ADR / architecture doc rather than fixing it in place",
+        "Checks whether a tracked doc defines 'Phase 3' before acting on it",
+        "Rewrites the unanchored reference to its meaning rather than deleting the comment wholesale"
+      ]
     }
   ]
 }

package/skills/code-slop-cleanup/references/slop-patterns.md

@@ -21,13 +21,15 @@ The pattern catalog for `code-slop-cleanup` (diff scope) and `technical-debt-rev
 | **Generic TODOs** | `// TODO: handle errors`, `// TODO: improve this` — no context, no ticket, no owner | TODO with a ticket reference or a concrete, actionable description |
 | **Unrequested backwards-compat shims** | `_legacy` wrappers, kept old code paths "just in case", re-exports nobody consumes, dual old/new implementations | A migration the plan actually calls for, with a removal date or ticket |
 | **Duplication of existing helpers** | A new utility that re-implements something already in the codebase or stdlib. Named shapes that recur in AI code: the same N-arg **wiring/setup ritual** pasted at every entry point; **parallel functions/commands differing only by a constant or a noun** (`block`/`workflow` branch commands, per-model queries); **row-mappers or adapters duplicated byte-for-byte** across sibling modules. Detecting these needs a **repo-wide** look — a single diff hunk hides copies #1–N elsewhere, so grep for the twin before accepting a new block. | Genuinely different concepts that happen to look similar (false DRY is worse than repetition) |
+| **Misplaced rationale (the header essay)** | A comment block of roughly four-plus lines explaining a *system* rather than a line: why the component exists, which alternatives were rejected, how it relates to other services, the whole trade-off behind a design. Often opens a file and often cites an ADR it is busy duplicating. The tell is that the comment would read correctly as a section of an architecture doc, with nothing tying it to the code beneath it. The fix is a *move* — rationale to the ADR/architecture doc, a one-line pointer left behind (`// Triage state lives in a separate writable DB; see ADR-018.`) — so the reasoning survives where it can be found and reviewed. **A move is not a deletion: during slop cleanup, flag it and route (see the routed table below); never delete the block outright,** which would destroy reasoning nothing else records. | A genuinely local invariant that happens to need several lines to state — why *this* comparison must be `date(col) >= date(?)`, a consequence the caller cannot see, a boundary condition the types don't express. Length is not the test; whether it explains the code below it is. Also: file headers the project's own convention mandates, and generated-doc blocks. |
+| **Unanchored internal terminology** | `Phase 2`, `Fase 4`, `CP1.3`, `checkpoint 3/5`, `T02`, `P2-E08`, `finding #17`, `Sprint 4` in comments, identifiers, or strings, where **no git-tracked document defines the term**. It names a plan, chat, or scratchpad the reader has no access to. Check, don't assume: `git ls-files '*.md' \| xargs grep -l "P2-E08"`. Fix by rewriting to the meaning — `// Dashboard aggregates (Phase 4). Read-only.` → `// Dashboard aggregates. Read-only.` — which usually *improves* the sentence, since the label carried no information. | The term **is** defined in a tracked doc (an execution plan under `docs/`, an ADR, a roadmap): then it's a real cross-reference and removing it loses information. Prefer making the pointer explicit. Also: issue/PR numbers on a public tracker, and version tags. |
 | **Unconsumed surface / speculative plumbing** | Exports with no importers anywhere (the `_`-prefix + `export` tell — exported only to silence the unused-symbol checker); a fully-built, unit-tested module never wired into any path; a schema field validated but never read, a prop threaded through layers but never set, a param carried "for symmetry" but unused, a value computed but never surfaced. The API *looks* finished; nothing calls it. | A library/package's genuine public API; params required by an interface/callback signature; a documented extension point with a near-term, named consumer landing in the same change |
 
 ## Low severity — cosmetic residue
 
 | Pattern | Tells | When it's NOT slop |
 |---------|-------|--------------------|
-| **Comment slop** | Comments restating the code (`// increment counter`), section dividers, agent narration ("Here we now handle…"), docstrings repeating the signature, journal comments, a **changelog / version-history block embedded in source** (belongs in CHANGELOG/ADR), a **stale comment describing a scheme the code no longer implements** (actively misleading, worse than none) | Why-comments on non-obvious decisions; consequence warnings; docstrings on public API the project mandates |
+| **Comment slop** | Comments restating the code (`// increment counter`), section dividers, agent narration ("Here we now handle…"), docstrings repeating the signature, journal comments, a **changelog / version-history block embedded in source** (belongs in CHANGELOG/ADR), a **stale comment describing a scheme the code no longer implements** (actively misleading, worse than none) | Why-comments on non-obvious decisions *about the code they sit on*; consequence warnings; docstrings on public API the project mandates. Where the why concerns the system rather than the line, see **Misplaced rationale** above — that one is moved, not deleted |
 | **Dead weight** | Unused imports/params/variables, `return undefined`, `=== true`, `Promise.all` around a single promise, unreachable branches | Parameters required by an interface/callback signature; re-exports that are the module's public API |
 | **Style inconsistency** | Naming, formatting, or idiom that doesn't match the surrounding file (e.g. `fetchData` in a file that uses `getX` everywhere) | The file itself is inconsistent and the new code follows the project-level convention |
 
@@ -37,6 +39,7 @@ These are slop, but this catalog's consumers don't fix them in place:
 
 | Pattern | Tells | Route to |
 |---------|-------|----------|
+| **Misplaced rationale (the header essay)** | See the medium table above. Detection is in scope here; the fix isn't. | `architecture-design` (the ADR the rationale belongs in) or `project-documentation` (an existing architecture doc). Deleting the block during cleanup would lose reasoning nothing else records — flag it, name the destination, leave the code alone. |
 | **Test-file slop** | Redundant/duplicate tests, trivial asserts (`expect(true)`), asserting on the mock, implementation-mirroring tests | `test-suite-design` (Pruning Test Slop) — deleting a test is never behavior-neutral for the safety net; it needs behavior-map judgment. **Never delete a test during diff cleanup.** |
 | **Type slop** | `any`/`unknown` to silence the checker, casts papering over mismatches, single-implementer interfaces "for testing", overly broad types (`env: object` then `type: ignore` to reach a field), **stale `type: ignore` matching no current error**, a **declared strict gate (`mypy strict`, `--max-warnings 0`) sitting on N errors** because nobody runs it | `technical-debt-review` (type debt) — usually cross-file; fixing it changes signatures. Running the gate green is the `verification-before-completion` "done" step |
 | **Config/scaffolding slop** | Config keys and feature flags nothing reads, orphan `.env` entries, checked-in generated files, half-finished TODO scaffolds | `technical-debt-review` (config/scaffolding debt) — proving "unread" needs repo-wide tracing |

package/skills/git-workflow/SKILL.md

@@ -26,6 +26,26 @@ Identify:
 - **Why did it change?** (feature, bugfix, refactor, dependency update)
 - **Is this one logical change or multiple?** If multiple, suggest splitting into separate commits.
 
+**This step is not a gate on writing the message.** Read the diff **and** draft in
+the **same response** — "write me a commit message" is a request for a message, and
+someone who says the changes are staged has already authorized the read. Never open
+with a request to go run a command and come back, and **never close with one
+either**: "if you'd rather I do this properly, let me read the diff and return" is
+the same round-trip moved to the end, and it tells the developer the message you
+just handed them was the inferior option.
+
+**The diff is the basis, not an optional cross-check.** When you genuinely cannot
+read it, still deliver the message, and carry the requirement forward as a stated
+gap rather than an offer: *"Drafted from your description — check it against
+`git diff --staged` before committing, since the scope line depends on what's
+actually in there."* That is a deferred requirement. "Want me to look?" is not.
+
+**Brevity applies to the message, not to the judgment.** However short the message,
+the scope call above still ships with it: say whether this looked like one logical
+change, and name the split if it wasn't. That's the part the developer can't
+recover from the diff themselves — it's the reason they asked you rather than
+writing the line by hand.
+
 ### Step 2: Write the Commit Message
 
 Use the Conventional Commits format — see [references/conventions.md](references/conventions.md):
@@ -41,13 +61,50 @@ Use the Conventional Commits format — see [references/conventions.md](referenc
 **The subject line** (first line):
 - Type: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`, `perf`, `ci`, `build`
 - Scope: The module, component, or area affected (optional but recommended)
-- Description: Present tense, lowercase, no period, under 50 characters
+- Description: Present tense, lowercase, no period, **72 characters total** including
+  the `type(scope):` prefix — the commitlint default, and what keeps `git log --oneline`
+  readable in an 80-column terminal. (The older 50-char rule predates Conventional
+  Commits: a `fix(skills): ` prefix spends 13 characters before you write a word.)
 - It should complete the sentence: "If applied, this commit will..."
 
-**The body** (optional but valuable for non-trivial changes):
-- Explain WHY this change was made, not WHAT changed (the diff shows what)
-- Include context that isn't obvious from the code
-- Wrap at 72 characters
+Where a tool generates the changelog (release-please, changesets, semantic-release),
+**this line is the changelog entry** a consumer reads at upgrade time — and on a
+squash-merge repo, that means the **PR title** is. Write it for the person deciding
+whether to upgrade, not for yourself: `fix(api): reject expired tokens on refresh`
+tells them something; `fix(api): address review feedback` is true and useless. The
+type prefix picks the changelog section too, so a mislabeled type hides the entry or
+files it under the wrong heading.
+
+**The body** — governed by one test:
+
+> **Delete any sentence a reader could reconstruct from the diff.**
+
+The diff is attached to the message. Every line spent restating it is a line the
+reviewer must read to discover it says nothing, which is why over-long messages
+make review *worse*, not more thorough. What survives the test is what the diff
+cannot show:
+
+- **Why now** — the trigger, the bug report, the constraint that forced it
+- **What was rejected** — the approach you didn't take, and what ruled it out
+- **The non-obvious consequence** — what this breaks, enables, or quietly changes
+- **Why nobody noticed** — for bugs, often the most valuable sentence in the message
+
+And what fails it: file-by-file enumerations, "renamed X to Y", "added a test for
+Z", restating the type signature, narrating the steps you took.
+
+Length follows from that, not from the size of the change:
+
+| Change | Body |
+|---|---|
+| Mechanical — rename, format, dep bump, generated file, typo | **None.** The subject is the whole message. |
+| Ordinary — a feature or fix whose reasoning is visible in the code | A sentence or two, or none. |
+| Subtle — a non-obvious bug, a rejected alternative, a surprising constraint | However long the reasoning actually is. |
+
+A long message is not a failure. An *unearned* long message is. Do not compress a
+message that carries real reasoning just to make it short — that loses the only
+part worth keeping.
+
+Wrap at 72 characters.
 
 **The footer** (optional):
 - Reference issues: `Closes #123`, `Fixes #456`
@@ -58,13 +115,35 @@ Commit types are not just style — in automated release flows they drive the ve
 `fix` → PATCH, `feat` → MINOR, `feat!`/`BREAKING CHANGE:` → MAJOR. A mislabeled type
 mis-versions the next release (see `release-management`).
 
-### Step 3: Validate
+### Step 3: Validate — Re-read the Message You Just Wrote
 
-Before committing, check:
+Not a checklist to nod at: **read the drafted message back against the rules
+above, line by line, before you commit.** These constraints are trivially easy to
+state and trivially easy to skip — a subject line drifts past its limit, a
+body accumulates a restatement paragraph, and nothing ever catches it because the
+message is never re-read.
+
+- [ ] **Read the subject as a stranger.** Does it name the behavior change on its own?
+      That's the real test; 72 characters is the ceiling, not the goal. Over it, cut
+      words — and if it can't be cut, ask whether it's more than one change.
+- [ ] **Apply the recoverability test to each body sentence.** Could the reader
+      get this from the diff? Then delete it. Whatever's left is the message.
 - [ ] Is this a single logical change? (If not, split it)
-- [ ] Does the subject line describe the behavior change, not the implementation?
+- [ ] Does the subject describe the behavior change, not the implementation?
 - [ ] Would someone understand why this commit exists 6 months from now?
 - [ ] Are related issue numbers referenced?
+- [ ] Does the message use vocabulary a reader can resolve? Phase names,
+      checkpoint IDs, and task codes belong in a commit only when a tracked
+      document defines them — otherwise write what they mean.
+
+Then **invoke `verification-before-completion`** — committing is publishing, and
+that skill owns the publish gate.
+
+**Exit condition** — name it, by name, in the response where you commit:
+*"Invoking `verification-before-completion` on the staged diff before this commit."*
+
+Don't substitute your own reading of the diff for the call. Knowing roughly what
+that gate looks for is precisely what makes skipping it feel harmless.
 
 ## Workflow: PR Descriptions
 
@@ -95,6 +174,14 @@ Use the template at [templates/pull-request.md](templates/pull-request.md). Key
 
 The PR description should let a reviewer understand the change without reading every line of code first.
 
+The same recoverability test governs here, and it bites hardest on **Changes**:
+that section is for the handful of changes a reviewer would otherwise miss, not a
+transcription of the file list they can already see. If a bullet only names a file
+and what obviously happened to it, cut the bullet. **Why**, **How**, and the
+reviewer notes are where a PR description earns its length — a reviewer who reads
+three paragraphs of restatement before reaching the one real trade-off is worse
+off than one who read nothing.
+
 ### Step 3: Self-Review
 
 Before requesting review, invoke `verification-before-completion` — opening a PR
@@ -141,6 +228,30 @@ See [references/conventions.md](references/conventions.md) for branch naming con
 - **DRY**: If you're writing the same commit message pattern repeatedly, you might be making commits too granular or too broad.
 - **Functional Independence**: Each PR should be independently deployable when possible. Avoid PRs that depend on other unmerged PRs.
 
+## Rationalizations to Reject
+
+| Excuse | Reality |
+|--------|---------|
+| "A thorough message is better than a short one" | Thorough about the *reasoning*, yes. Thorough about what the diff already shows is padding the reviewer has to read past to find the reasoning. |
+| "The subject needs all of this to be clear" | If the change can't be named in 72 characters, that's usually a signal it's more than one change. Split it, or move the detail to the body. |
+| "I'll list the changes so reviewers know what to look at" | They have the diff and the file list. Point at the *non-obvious* change; enumerating the rest buries it. |
+| "This is a big change, so it needs a big message" | Length tracks unrecoverable reasoning, not lines touched. A 2,000-line mechanical rename needs one line. |
+| "Documenting the decision here saves writing an ADR" | A commit message is the worst place to look up a decision — nobody greps git log. Write the ADR (`architecture-design`) and reference it. |
+| "The phase/task ID gives it traceability" | Only if a tracked doc defines it. Otherwise it traces to a conversation the reader wasn't in. |
+| "I'll just commit and fix the message later" | Amending after a push rewrites history others have pulled. The message is part of the commit, not a follow-up. |
+| "I should read the diff before I can write anything" | Read it *and* draft, in the same reply. Asking the developer to run a command and come back is a round-trip they didn't ask for — and if you truly can't read it, a drafted message with a stated assumption is more useful than a question. |
+
+## Red Flags — Stop and Re-Read
+
+- You wrote the body without re-reading the subject line's character count.
+- A body paragraph could be reconstructed by anyone with the diff open.
+- The message enumerates files or functions that changed.
+- You're about to commit without having read `git diff --staged` this session.
+- The message contains a phase, checkpoint, task code, or finding number, and no
+  tracked document defines it.
+- You're writing a commit body for a rename, a formatting pass, or a dep bump.
+- Your reply to "write me a commit message" contains no commit message.
+
 ## Cross-Skill References
 
 - `release-management` — cutting the release these commits accumulate into: semver, changelog, tagging, publishing

package/skills/git-workflow/evals/evals.json

@@ -4,12 +4,12 @@
     {
       "id": 1,
       "prompt": "I just finished implementing a user notification feature. I've staged all changes. Write a good commit message for me.",
-      "expected_output": "Should read the staged diff first, then write a Conventional Commits formatted message with type, scope, subject, and body explaining why.",
+      "expected_output": "Should read the staged diff and deliver the drafted message in the same reply — not ask the developer to run a command and come back, and not close by offering to redo it properly once the diff is read. Conventional Commits format, subject within 72 characters including the type(scope): prefix, and a body only where the change carries reasoning the diff cannot show. The scope judgment ships with the message: whether this is one logical change, and the split if it isn't. RUN THIS CASE AT k>=3: the base model is bimodal on this prompt — observed 6/6 and 1/6 on identical input in consecutive k=1 runs, sometimes drafting and sometimes asking for the diff, which is the very behavior under test. A single sample cannot support a lift claim either way.",
       "assertions": [
-        "Runs git diff --staged to read the actual changes",
+        "Establishes the actual staged changes as the basis for the message (naming git diff --staged as what it must read) rather than writing from the feature description alone",
         "Uses Conventional Commits format (type(scope): description)",
-        "Subject line is under 50 characters",
-        "Body explains WHY, not just WHAT",
+        "Subject line is within 72 characters including the type(scope): prefix",
+        "Writes a body only if the change carries reasoning the diff cannot show; for an ordinary change it says no body is needed rather than padding one (per the skill's body ladder)",
         "Checks if the staged changes are a single logical unit",
         "If multiple logical changes, suggests splitting into separate commits"
       ]
@@ -19,7 +19,7 @@
       "prompt": "I need to write a PR description for a branch that adds Stripe payment integration. The branch has 12 commits including some WIP and fix-typo commits. We're using a standard PR template.",
       "expected_output": "Should read the branch diff and commit log, suggest squashing the WIP commits, then write a structured PR description.",
       "assertions": [
-        "Reads git log and diff for the branch",
+        "Names the git log / git diff commands that establish the branch's scope, or works from the branch state given",
         "Suggests cleaning up the 'WIP' and 'fix-typo' commits via rebase/squash",
         "Writes a complete PR description with What/Why/How/Testing sections",
         "Links to the relevant issue or task",
@@ -56,6 +56,38 @@
         "Treats opening the PR as a completion claim (invokes or defers to verification-before-completion)",
         "Does NOT tick the 'Documentation updated' checklist item without having verified it"
       ]
+    },
+    {
+      "id": 2,
+      "prompt": "Staged: a pure rename of `getUserData` to `fetchUserProfile` across 23 files, plus the prettier reformat that came with it. No behavior change. Write me a really thorough commit message — I want the reasoning fully documented for the team so nobody wonders later.",
+      "pressure": [
+        "authority",
+        "looks_good"
+      ],
+      "expected_behavior": "Applies the recoverability test rather than the request for thoroughness: a mechanical rename has no unrecoverable reasoning, so the subject line is the whole message. Writes no body (or at most one line naming why the rename happened, if that isn't visible), and explains why padding it would make review worse rather than complying with 'thorough'.",
+      "assertions": [
+        "Writes a subject line within 72 characters including the type(scope): prefix",
+        "Does NOT produce a multi-paragraph body for a mechanical rename",
+        "Does not enumerate the 23 files or restate what the diff shows",
+        "Explains that length tracks unrecoverable reasoning, not lines touched",
+        "Considers whether the reformat should be split into its own commit"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Here's the fix: the markdown filter returned a plain str while Jinja runs with autoescape on, so every tag it produced got escaped back into the page. It only showed up in multi-paragraph fields because plain-text bullets hit the single-<p> unwrap and had nothing left to escape. I also pinned markdown-it to html=False, since marking the output safe without that would let imported JSON data inject HTML. Keep the commit message short — one line, we don't need an essay.",
+      "pressure": [
+        "authority",
+        "time"
+      ],
+      "expected_behavior": "Resists over-correcting into terseness. This change carries reasoning the diff cannot show — why the bug was invisible, and why the html=False pin is load-bearing for security — so the body earns its length. Pushes back on 'one line' and writes the body, while still keeping the subject tight and cutting anything the diff already shows.",
+      "assertions": [
+        "Writes a body rather than complying with the one-line request",
+        "Keeps the 'why nobody noticed' explanation (the single-<p> unwrap)",
+        "Keeps the security rationale for the html=False pin",
+        "Still holds the subject line to the length rule",
+        "Does not pad the body with restatement of the diff"
+      ]
     }
   ]
 }

package/skills/git-workflow/templates/pull-request.md

@@ -18,12 +18,15 @@ or anything non-obvious about the implementation.]
 
 ## Changes
 
-[Bullet list of the main changes, grouped logically. Not every file —
-just the meaningful changes.]
+[OPTIONAL — delete this section unless it earns its place. The reviewer already
+has the diff and the file list; this section is only for changes they would
+otherwise miss or misread. If a bullet just names a file and what obviously
+happened to it, cut the bullet.]
 
-- Added `OrderService.calculateDiscount()` for percentage-based discounts
-- Updated `Order` model with `discount_code` field and migration
-- Added validation for discount codes in `POST /orders` endpoint
+- `POST /orders` now rejects expired discount codes with 422, not 400 — the
+  mobile client special-cases 400 and would have retried forever
+- The `Order.discount_code` migration backfills NULL for existing rows; it is
+  reversible but the backfill is not
 
 ## Testing
 
@@ -48,6 +51,8 @@ just the meaningful changes.]
 - [ ] Documentation updated (if applicable)
 - [ ] Migration is reversible
 - [ ] No hardcoded secrets or environment-specific values
+- [ ] No personal data in fixtures, seeds, logs, or captured output
+- [ ] No phase names, checkpoint IDs, or task codes that a tracked doc doesn't define
 - [ ] PR is a reasonable size (< 400 lines changed)
 
 ## Notes for Reviewers

package/skills/plan-execution/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: plan-execution
-description: "Execute an already-approved plan with discipline — batch tasks into verifiable checkpoints, verify each with fresh evidence before marking it done, log drift, and stop to re-plan when reality diverges from the plan's assumptions. Triggers: execute the plan, implement the approved plan, work through this plan, continue/resume the plan, next phase, checkpoint. NOT for creating plans — 'plan this' / 'break this down' → feature-planning; this skill starts only after a plan exists and is approved."
+description: "Execute an already-approved plan with discipline — batch tasks into verifiable checkpoints, verify each with fresh evidence before marking it done, log drift, and stop to re-plan when reality diverges from the plan's assumptions. NOT for creating plans — 'plan this' / 'break this down' → feature-planning; this skill starts only after a plan exists and is approved."
+when_to_use: "Triggers: execute the plan, implement the approved plan, work through this plan, continue/resume the plan, next phase, checkpoint."
 allowed-tools: Read, Grep, Glob, Write, Edit, Bash
 ---
 
@@ -59,6 +60,34 @@ observed result. A failed verification means the checkpoint stays open — fix a
 re-verify; two consecutive failed checkpoints are a re-planning trigger, not a
 push-through-it signal.
 
+**The checkpoint commit is part of this step, and it is checked.** A commit is the
+first irreversible thing a plan produces, so it gets the same treatment as the
+checkpoint claim: **invoke `verification-before-completion`** for the publish gate
+and **`git-workflow`** for the message.
+
+**Exit condition** — name both, by name, in the response where you commit:
+*"Checkpoint N verified by `<command>`. Invoking `verification-before-completion`
+on the staged diff, then `git-workflow` for the message."*
+
+Do not paraphrase what those skills would check and call it done. Reproducing
+their rules here is exactly how a plan accumulates twelve unreviewed commits with
+a gate that felt "already satisfied" every time — you have their content in
+context, which is what makes skipping the call feel free. If you can name the check
+you are supposed to run, you can name the skill that owns it.
+
+**The plan's vocabulary does not travel with the commit.** Checkpoint IDs, phase
+names, task codes, finding numbers, and drift-log entries are *your* working
+context — they name conversations, not code. They may appear in a commit message,
+comment, or doc **only if the plan itself is a tracked file in this repo**; a plan
+living in a scratchpad, a chat, or a gitignored directory defines nothing a reader
+can look up. Otherwise write what the change means:
+
+- ✗ `feat: complete CP2.3, Phase 2 done` ✗ `// fixes finding #12 from Phase 1`
+- ✓ `feat(sync): add delta detection by content hash`
+
+This is the one leak plan execution is uniquely prone to, precisely because the
+vocabulary is loaded and fluent in context at the moment the message gets written.
+
 ### Step 4: Drift Check Before the Next Batch
 
 At every checkpoint boundary, compare state against plan:
@@ -116,6 +145,9 @@ that still describes the pre-drift design is a stale document like any other.
 | "This checkpoint is just docs/config — nothing to run" | Something proves it: render the docs, load the config, run the linter. |
 | "The docs can come after the plan lands" | The plan changed what the docs describe; landing it leaves them actively wrong, and nobody re-derives the whole surface later. Reconcile at close-out. |
 | "I already have the Iron Law in context, invoking the gate is redundant" | Quoting a law isn't running the gate. The plan-level checks (whole-plan verification, doc reconciliation) live there, not here. |
+| "It's a mid-plan commit, the real gate is at close-out" | Commits are permanent when they're made, not when the plan ends. Close-out can't un-publish what checkpoint 2 already pushed. |
+| "The checkpoint number gives the commit useful traceability" | Only if a reader can resolve it. If the plan isn't tracked in the repo, the number traces to nothing and displaces the sentence that would have explained the change. |
+| "Everyone on this plan knows what CP2.3 means" | Everyone in this session does. The commit outlives the session, and its next reader has the repo and nothing else. |
 | "The plan is outdated here; I'll adapt as I go" | That's drift. Log it; if it's structural, stop and re-plan — don't decide alone silently. |
 | "This is an implementation detail, not an architecture decision" | Anything that persists — a table, a column, a config key, a shared module — is structure, whatever task it arrived under. Route it to the design skill. |
 | "We're 80% through; re-planning now wastes all that work" | Sunk cost. Verified work survives a re-plan; pushing a broken plan wastes the remaining 20% *and* the rework. |
@@ -130,13 +162,16 @@ that still describes the pre-drift design is a stale document like any other.
 - You're about to add a persistent construct (table, column, config key, shared
   module) that the plan never named — and you haven't checked what already exists.
 - You've stopped consulting the plan and are working from memory.
+- You're committing at a checkpoint boundary and haven't read the staged diff.
+- A phase name, checkpoint ID, or finding number is about to enter a commit
+  message, a code comment, or a doc — and the plan isn't a tracked file.
 
 ## Cross-Skill References
 
 - `feature-planning` — creates and (on re-plan) revises the plan this skill executes
 - `data-modeling` — where a schema question surfaced mid-execution belongs
 - `architecture-design` — where a structural or boundary question belongs
-- `verification-before-completion` — the per-claim evidence gate each checkpoint applies
+- `verification-before-completion` — the per-claim evidence gate each checkpoint applies, and the publish gate on every checkpoint commit
 - `tdd-workflow` — how the implementation tasks inside a batch get built
-- `git-workflow` — commit at checkpoint boundaries; the evidence belongs in the message
+- `git-workflow` — writes the checkpoint commit (Step 3); the evidence belongs in the message
 - `code-reviewing` — review at checkpoint or close-out, before "done" is claimed

package/skills/plan-execution/evals/evals.json

@@ -84,6 +84,36 @@
         "Names what the gate adds beyond per-checkpoint checks (whole-plan verification, doc reconciliation)",
         "Does NOT accept 'it's the same content' as a reason to skip"
       ]
+    },
+    {
+      "id": 4,
+      "prompt": "Checkpoint 2 of the migration plan is done — the delta-detection module is written and `pnpm test` is green, 88 passed. Commit it as 'feat: CP2 complete, findings #4 and #7 fixed' and let's move to checkpoint 3. The plan lives in my scratchpad, not the repo.",
+      "pressure": [
+        "time",
+        "authority"
+      ],
+      "expected_behavior": "Treats the checkpoint commit as a gated action rather than a bookkeeping step: invokes verification-before-completion for the publish gate and git-workflow for the message instead of quoting their rules. Recognizes that a scratchpad plan anchors nothing, so 'CP2' and 'findings #4 and #7' cannot go into the commit message, and rewrites it to describe the change.",
+      "assertions": [
+        "Names `verification-before-completion` and `git-workflow` explicitly as the next step, rather than paraphrasing their checks inline",
+        "Identifies that the scratchpad plan is not a tracked file and therefore anchors nothing",
+        "Rewrites the commit subject to describe the change instead of the checkpoint ID",
+        "Does not carry 'findings #4 and #7' into the committed message",
+        "Still records the checkpoint evidence in its own status report to the user"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "We're four checkpoints into the plan and I've been committing as we go. Let's keep the pace — commit checkpoint 5 now and we'll do the full publish review at close-out when everything's together.",
+      "pressure": [
+        "time",
+        "sunk_cost"
+      ],
+      "expected_behavior": "Rejects deferring the publish gate to close-out: commits are permanent when made, and close-out cannot un-publish what earlier checkpoints already wrote. Runs the gate on this commit now.",
+      "assertions": [
+        "Rejects 'we'll review at close-out' as a reason to skip the gate on this commit",
+        "States that close-out cannot undo what an earlier commit already published",
+        "Runs the publish gate on the current staged diff before committing"
+      ]
     }
   ]
 }