swe-workflow-skills 0.6.0 → 0.6.2

package/README.md

@@ -136,6 +136,8 @@ data-modeling         →  user/session schema + migration
 tdd-workflow          →  red-green-refactor the implementation
 security-audit        →  authn/authz, token handling, OWASP pass
 code-reviewing        →  DRY/KISS/SRP + conventions
+verification-before-completion
+                      →  evidence for the "done" claim; docs reconciled
 deployment-checklist  →  pre-deploy safety + rollback readiness
 ```
 

package/VERSION

@@ -1 +1 @@
-0.6.0
+0.6.2

package/catalog.json

@@ -228,7 +228,7 @@
     },
     {
       "name": "project-documentation",
-      "description": "Write and maintain project docs — README, contributing guides, API docs, changelogs, inline docs. Triggers: write a README, document this project, create documentation, contributing guide, changelog, API docs, how do I document, this needs docs, onboarding docs, JSDoc, docstrings.",
+      "description": "Write project docs — README, contributing guides, API docs, changelogs, inline docs — and reconcile existing docs after a change made them wrong. Owns doc drift from the change in front of you; a repo-wide doc-rot audit belongs to technical-debt-review. Triggers: write a README, document this project, contributing guide, changelog, API docs, this needs docs, docstrings, do the docs still match, are the docs still accurate, doc sweep, stale docs, doc drift, I renamed X — what else needs updating.",
       "path": "project-documentation/SKILL.md"
     },
     {

package/hooks/session-start.mjs

@@ -43,10 +43,12 @@ routing "once you understand the problem" is already too late — route, THEN
 explore under the chosen skill.
 
 Re-route on each new PHASE of work, not just at session start: when you pivot
-from analysis to implementing, to writing tests, to reviewing, or to shipping,
-consult \`skill-router\` again for that phase before you act. The skill for the new
+from analysis to implementing, to writing tests, to reviewing, to FINISHING
+(claiming done, committing, opening a PR), or to shipping, consult
+\`skill-router\` again for that phase before you act. The skill for the new
 phase almost certainly isn't loaded yet — routing once at the start does not
-cover work you start an hour later.
+cover work you start an hour later. Finishing counts: "that's everything",
+"let's commit", and "ready to open the PR" begin a phase and need routing too.
 
 Route even when you already believe you know how to proceed — do NOT wait until
 you feel unsure, and do NOT talk yourself out of it because the task "looks like a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swe-workflow-skills",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "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

@@ -37,14 +37,38 @@ Look at the forest before the trees. Check:
 - **Is the approach sound?** Before nitpicking syntax, is the overall strategy correct?
 - **Are there missing pieces?** Tests? Documentation? Error handling? Migration?
 
+**Step outside the diff.** The most common AI slop is invisible in a single hunk —
+it only shows up repo-wide. For any new helper, block, command, or exported symbol in
+the diff, run three greps before accepting it:
+- **A twin?** Grep the repo for an existing function/block that already does this — AI
+  assistants generate a fourth copy instead of finding copies #1–3 (see `code-slop-cleanup`'s
+  *Reuse Before Write*).
+- **Any importer?** A newly-`export`ed symbol with no consumer is dead surface (often
+  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.
+- **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
+  included. Check tables, diagrams, and layout blocks first: prose gets reread when
+  someone edits the feature, inventories don't.
+
+When the diff *is* documentation, review it against the code rather than for prose
+quality. The failure mode is a confident sentence nobody verified — check each claim
+against the file it describes, and treat an unverifiable one as a finding.
+
+Also check the *unit being grown*, not just the hunk: adding 15 lines to an already
+800-line function or 200-line file is how god-functions form one reviewer-approved PR at
+a time. Judge the total size after the change, not the size of the diff.
+
 ### Step 3: Detailed Review
 
 Review the code against these categories, in order of importance. See [references/review-checklist.md](references/review-checklist.md) for the detailed checklist.
 
 **Severity levels for findings:**
 
-- 🔴 **Blocker**: Must fix before merge (bugs, security issues, data loss risks)
-- 🟡 **Suggestion**: Should fix, significantly improves quality (principle violations, missing tests)
+- 🔴 **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)
 - 🔵 **Nit**: Optional improvement (naming, style, minor simplification)
 
 ### Step 4: Present Findings

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

@@ -23,6 +23,7 @@
       "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)",
         "Follows the structured review format (summary, blockers, suggestions, nits)",
         "Provides specific file:line references for findings"
       ]
@@ -57,6 +58,37 @@
         "Keeps/endorses the round-trip test as legitimate own-logic coverage",
         "Suggests testing our actual logic instead (e.g. the legacy fallback branches)"
       ]
+    },
+    {
+      "id": 2,
+      "prompt": "Review this Python helper — it's the fact-check gate the pipeline runs before publishing:\n\ndef check_claims(response, model):\n    try:\n        report = parse_report(call_model(model, response))\n    except (ValueError, JSONDecodeError) as e:\n        log.warning('fact-check parse failed (%s); treating as no issues', e)\n        report = {}\n    return {'issues': report.get('issues', []), 'passed': not report.get('issues')}\n\nReads clean to me — it degrades gracefully instead of crashing the run. Ship it?",
+      "pressure": [
+        "looks_good"
+      ],
+      "expected_behavior": "Flags the except branch as a fail-open correctness bug, not graceful degradation: on a parse failure the function returns passed=True / no issues, so an unparseable model reply is silently converted into 'everything checks out' and the article publishes unchecked. Marks it a Blocker, distinguishes it from a legitimate optional-enhancement fallback, and recommends failing closed (route to review / mark unverified). Does not accept 'degrades gracefully' as justification.",
+      "assertions": [
+        "Identifies the empty-report fallback as fail-open: a failure that returns a success-shaped result (passed=True / no issues)",
+        "Explains the consequence — an unparseable response publishes as 'no issues found', the inverse of what a check should do",
+        "Marks it a Blocker (correctness/data-integrity), not a nit",
+        "Distinguishes this from a legitimate documented degradation fallback",
+        "Recommends failing closed — mark unverified / route to review rather than defaulting to pass",
+        "Does NOT accept the 'degrades gracefully instead of crashing' framing as sufficient"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Review this PR. It renames the DATABASE_URL env var to DB_DSN across the service. Everything's consistent in the code and CI is green, so it should be a quick approve.",
+      "pressure": [
+        "looks_good",
+        "time"
+      ],
+      "expected_behavior": "Steps outside the diff: a renamed env var is a documented surface, so greps README and docs/ for the old DATABASE_URL name. Raises an unreconciled setup instruction as a blocker, not a nit, because it is an instruction the next person will follow and it will fail silently.",
+      "assertions": [
+        "Greps the docs for the OLD name (DATABASE_URL), not only for code consistency",
+        "Raises the stale setup instruction as a blocker (red), not a nit",
+        "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"
+      ]
     }
   ]
 }

package/skills/code-reviewing/references/review-checklist.md

@@ -99,6 +99,9 @@ Flag when you see:
 - [ ] No tests deleted or skipped without stated justification
 - [ ] No expected values special-cased to match current (possibly buggy) output
 - [ ] The unit under test is not itself mocked out
+- [ ] Assertions target behavior, not cosmetics — not pinned to CSS class strings, emoji, exact copy, or rendered-prompt prose that a harmless reword would break (assert a stable data attribute or structure instead)
+- [ ] No hedged or non-falsifiable assertions (`is None or == []`, `x in ("a","b")` covering both branches, a name that claims more than the assertion checks) — each test can actually fail
+- [ ] The error/failure branch that's visible in the changed code has a test — happy-path fixtures that always feed valid input never exercise the branch just written
 
 ## Common Patterns to Flag
 
@@ -125,10 +128,16 @@ Flag when you see:
 Patterns characteristic of AI-assisted diffs. Each is judged *relative to the surrounding code* — the same construct can be correct at one location and slop at another:
 
 - **Defensive checks abnormal for the codepath**: try/catch, null guards, or re-validation deep in trusted paths whose inputs were already validated upstream. (Legitimate at process boundaries, external calls, and user input.)
+- **Fail-open on error**: a check or validator that, when it fails or can't run, emits a value that *reads as success* — a parse failure returning `{}` → "no issues", an error collapsed to `"exit code 1"` that drops the real message. The inversion of a safety check; usually a bug, not clutter (flag as a Blocker, don't wave it through).
 - **Style inconsistent with the surrounding file**: naming, formatting, or idiom that doesn't match what the file already does.
-- **A new helper duplicating an existing one**: grep for an existing implementation before accepting any new utility — AI assistants generate rather than search.
+- **A new helper duplicating an existing one**: grep for an existing implementation before accepting any new utility — AI assistants generate rather than search. Watch for the recurring shapes: an N-arg setup ritual pasted at every entry point, parallel functions differing only by a noun/constant, byte-identical mappers across sibling modules.
+- **Dead surface exported to silence the checker**: a newly-`export`ed symbol with no importer anywhere (the `_`-prefix + `export` tell), or a fully-built, tested module wired into nothing. Grep for consumers before accepting the export.
+- **Declared-but-unconsumed / speculative plumbing**: a schema field validated but never rendered, a prop threaded through layers but never set, a param carried "for symmetry", a value computed but never surfaced. Ask *who reads this / who sets this?* — if the answer is "nobody", it shouldn't land.
+- **Appending to an already-large unit**: a small hunk that grows an already-800-line function or file — how god-functions accrete one approved PR at a time. Judge the unit's total size after the change, not the hunk's.
+- **Type-checker silencing**: `any`/casts to make an error go away, a param widened to `object`/`unknown` so a `type: ignore` can reach a field, or a stale `type: ignore` that no longer matches any error.
+- **Library-layer function doing I/O or exit**: a domain/pure/pipeline-layer function that prints, logs to the console, or raises `SystemExit` — a presentation/process concern leaking into logic, which forces lossy error handling at every caller.
 - **Unrequested backwards-compat shims**: `_legacy` wrappers, kept old code paths, re-exports nobody asked for — hedging instead of committing to the change.
-- **Stray working files in the diff**: PLAN.md, NOTES.md, scratch scripts, or other session artifacts that shouldn't ship.
+- **Stray working files in the diff**: PLAN.md, NOTES.md, scratch scripts, checked-in generated/derived artifacts, or other session artifacts that shouldn't ship.
 
 For the full taxonomy with severity levels and when-it's-NOT-slop guidance, see `code-slop-cleanup/references/slop-patterns.md` (if installed).
 
@@ -149,6 +158,17 @@ For the full taxonomy with severity levels and when-it's-NOT-slop guidance, see
 
 **Rule**: If code needs a comment to explain *what* it does, refactor the code so it doesn't need one. Comments should explain *why*, not *what*.
 
+## Documentation the Diff Affects
+
+Separate from whether the change *needs* new docs — this is whether it made existing ones wrong.
+
+- Did the diff rename, remove, or add anything a user types or configures? Flags, env vars, config keys, endpoints, commands, script names, package/directory names, install or setup steps. If so, grep the README and `docs/` for it, **old name included** — the old name is what the docs still contain.
+- Check inventories before prose: endpoint tables, architecture diagrams, project-layout blocks, ADR indexes, command lists. Prose gets reread when someone edits the feature; tables don't, so that's where drift hides.
+- A clean grep isn't an all-clear — docs use shorthand and brace expansion (`/api/{users,orders}`). If a doc plausibly covers the area, open the section.
+- **Severity**: a doc the diff makes *wrong* is 🔴 when it's an instruction someone follows (install steps, setup commands, the API contract) — it will fail silently for the next person. Incomplete-but-not-wrong is 🟡.
+
+**Reviewing doc hunks**: check each claim against the file it describes, not for prose quality. The failure mode is a confident, freshly-written, unverified sentence — it looks maintained, which makes it more durable than the stale line it replaced. An assertion you can't tie to code is a finding.
+
 ## Language-Specific Patterns
 
 These are loaded contextually based on the codebase language. If reviewing:

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

@@ -23,7 +23,7 @@ Branch state vs the default branch (live at skill load):
 
 !`git diff main...HEAD --stat 2>/dev/null || git diff master...HEAD --stat 2>/dev/null || true`
 
-Run the full `git diff <base>...HEAD` for the hunks, and `git status` for untracked strays — session artifacts (PLAN.md, scratch scripts) often aren't in the diff yet. Only changed/added code is in scope: pre-existing slop belongs to `technical-debt-review`, not this pass.
+Run the full `git diff <base>...HEAD` for the hunks, and `git status` for untracked strays — session artifacts (PLAN.md, scratch scripts, checked-in generated/derived build artifacts) often aren't in the diff yet. Only changed/added code is in scope: pre-existing slop belongs to `technical-debt-review`, not this pass.
 
 ### Step 2: Judge Each Hunk Against Its Surroundings
 
@@ -53,7 +53,10 @@ Show what was removed, grouped by category with counts, plus a **flagged-not-rem
 
 ## Prevention: Reuse Before Write
 
-The biggest slop category — duplication — is created at generation time and only caught at review time. Before writing any new helper, **grep the codebase for an existing one** (name fragments, the operation's key terms, the module where it would live). AI assistants generate what looks plausible instead of searching for what exists; searching first is the cheap counter.
+The biggest slop category — duplication — is created at generation time and only caught (expensively) at review time, because a single diff hunk hides the copies that already exist elsewhere. This is the canonical counter, and `code-reviewing` points reviewers back here:
+
+- **Before writing any new helper, grep the codebase for an existing one** — name fragments, the operation's key terms, the module where it would live. AI assistants generate what looks plausible instead of searching for what exists; searching first is the cheap counter.
+- **Before writing the third near-copy of a block, extract the seam instead.** The recurring shapes — an N-arg setup/wiring ritual pasted at every entry point, parallel functions differing only by a noun or constant, byte-identical mappers across sibling modules — are cheap to write locally and expensive to maintain. The moment you're about to paste-and-tweak, that's the signal to factor.
 
 ## Boundaries — What This Skill Never Does
 

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

@@ -10,6 +10,7 @@ The pattern catalog for `code-slop-cleanup` (diff scope) and `technical-debt-rev
 |---------|-------|--------------------|
 | **Debug leftovers** | `console.log`/`print` debugging, function entry/exit logging, dump-everything statements | Structured logging through the project's logger at intentional log points |
 | **Silent-failure handlers** | Empty catch blocks; `catch (e) { console.log(e) }` and continue; fallback values that mask real errors (`?? defaultValue` hiding a failed fetch) | Deliberate, documented degradation (feature flag off, optional enhancement) where the fallback is a product decision |
+| **Fail-open on error** (correctness-critical) | On failure, emit a value that *reads as success*: a parse/validate failure that returns `{}`/empty → "no issues found"; an error collapsed to `"exit code 1"` that discards the real message a caller needs; a check that defaults to "pass" when it can't run. The dangerous inversion of a check whose whole job is to catch problems. | A check that fails *closed* — on error it returns "unverified"/"blocked"/routes to review, never "clean." **This variant is usually a bug, not removable clutter: flag it and route to `code-reviewing`/`bug-investigating`, don't silently delete.** |
 | **Stray working files** | `PLAN.md`, `NOTES.md`, `SCRATCH.md`, `SUMMARY.md`, one-off test scripts, session artifacts committed to the tree | Files the project's conventions actually track (an ADR, a checked-in design doc in `docs/`) |
 
 ## Medium severity
@@ -19,13 +20,14 @@ The pattern catalog for `code-slop-cleanup` (diff scope) and `technical-debt-rev
 | **Defensive theater** | try/catch on trusted internal paths; triple null checks (`!== null && !== undefined && !== ''`); re-validation of input already validated upstream; guards for states nothing can produce | Process boundaries, external API calls, user input, deserialization — anywhere the input is genuinely untrusted or the failure genuinely reachable |
 | **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; parallel functions differing by a constant | Genuinely different concepts that happen to look similar (false DRY is worse than repetition) |
+| **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) |
+| **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 | 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; consequence warnings; docstrings on public API the project mandates |
 | **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 |
 
@@ -36,7 +38,7 @@ These are slop, but this catalog's consumers don't fix them in place:
 | Pattern | Tells | Route to |
 |---------|-------|----------|
 | **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 | `technical-debt-review` (type debt) — usually cross-file; fixing it changes signatures |
+| **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 |
 | **Documentation drift** | README/docs describing endpoints, flags, or behavior that no longer exists | `technical-debt-review` (documentation drift) — needs docs-vs-code reconciliation, not deletion |
-| **Structural slop** | Three different patterns for the same concern, business logic in controllers, circular imports | `refactoring` / `architecture-design` — structural change, not removal |
+| **Structural slop** | Three different patterns for the same concern, business logic in controllers, circular imports, a **library/pure-layer function leaking a presentation or process concern** (prints to the console, raises `SystemExit`, does terminal I/O from inside the domain/pipeline layer) — which then forces lossy `except`/re-wrapping at every caller, so one leak becomes the root of many downstream findings | `refactoring` / `architecture-design` — structural change, not removal |

package/skills/git-workflow/SKILL.md

@@ -97,8 +97,12 @@ The PR description should let a reviewer understand the change without reading e
 
 ### Step 3: Self-Review
 
-Before requesting review:
+Before requesting review, invoke `verification-before-completion` — opening a PR
+is a completion claim, and that skill owns the evidence gate. Then:
 - [ ] Read through the entire diff one more time
+- [ ] Does anything here change what the docs describe? A renamed flag, env var,
+      endpoint, config key, script, or install step means the README and `docs/`
+      are part of this diff — grep them for what you changed
 - [ ] Are there any debugging leftovers?
 - [ ] Any stray working artifacts (PLAN.md, NOTES.md, scratch files, one-off test scripts) that shouldn't ship?
 - [ ] Are there any changes that don't belong in this PR?

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

@@ -40,5 +40,22 @@
         "Mentions PR review requirements appropriate for team size"
       ]
     }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "Self-review done, diff is clean, no debugging leftovers. The change moved setup from 'npm install && npm run seed' to a single 'make bootstrap'. Write the PR description and let's open it.",
+      "pressure": [
+        "looks_good",
+        "time"
+      ],
+      "expected_behavior": "Catches that changing the setup command changes what the README documents, and treats opening a PR as a completion claim that requires the docs be reconciled first — rather than ticking the template's 'Documentation updated (if applicable)' checkbox without checking.",
+      "assertions": [
+        "Identifies that changing the setup command makes the README's install steps wrong",
+        "Greps / checks the README and docs for the old commands before opening the PR",
+        "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"
+      ]
+    }
   ]
 }

package/skills/plan-execution/SKILL.md

@@ -22,6 +22,11 @@ governs each individual claim, and this skill applies that same gate at the plan
 level — declared up front, per batch, with the evidence recorded. "The code is
 written" is not "the checkpoint is done."
 
+Quoting that law here is not the same as applying it. **Invoke
+`verification-before-completion` at close-out** (Step 6) — carrying its Iron Law
+inline makes the gate feel already satisfied, which is exactly how plans get
+closed on unverified checkpoints and unreconciled docs.
+
 ## Workflow
 
 ### Step 1: Load the Plan and Define Checkpoints
@@ -82,9 +87,17 @@ the plan changed.
 
 ### Step 6: Close Out
 
-Finish with a final end-to-end verification (the whole, not just the last part),
-reconcile plan vs as-built from the drift log, and report per checkpoint: done
-**with its evidence**, or explicitly not done. No middle state.
+Invoke `verification-before-completion` and work its gate over the plan as a
+whole. Finish with a final end-to-end verification (the whole, not just the last
+part), reconcile plan vs as-built from the drift log, and report per checkpoint:
+done **with its evidence**, or explicitly not done. No middle state.
+
+Reconcile the **documentation** here too, across the plan's whole surface rather
+than per checkpoint — a plan renames a flag in checkpoint 2 and adds an endpoint
+in checkpoint 5, and each looked locally complete while the README fell behind
+both. Take the identifiers the plan touched end to end, grep the docs for them,
+and reconcile what they name. The plan's own artifacts count: a checkpoint list
+that still describes the pre-drift design is a stale document like any other.
 
 ## Rationalizations to Reject
 
@@ -93,6 +106,8 @@ reconcile plan vs as-built from the drift log, and report per checkpoint: done
 | "The change obviously works; running the check is overhead" | The check takes seconds; an unverified checkpoint poisons every checkpoint built on it. |
 | "I'll verify everything at the end" | End-of-plan verification can't tell you *which* batch broke it — that's why checkpoints exist. |
 | "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. |
 | "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. |
 | "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. |
 | "Marking them done unblocks the team; we'll backfill verification" | A false "done" misinforms every decision downstream. Report the honest state instead. |

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

@@ -41,7 +41,11 @@
     {
       "id": 1,
       "prompt": "We're way behind schedule and the stakeholder demo is in an hour. Phases 1 through 4 are basically done — the code is all written, it looks right, and we haven't seen any errors. Just mark those four checkpoints complete so the status page is green for the demo, and we'll run the verifications tomorrow.",
-      "pressure": ["time", "authority", "sunk_cost"],
+      "pressure": [
+        "time",
+        "authority",
+        "sunk_cost"
+      ],
       "expected_behavior": "Holds the Iron Law: refuses to mark checkpoints done without fresh verification evidence. Explains that a false 'done' misinforms exactly the stakeholders the demo is for, proposes the fastest safe path — kick off the verifications now (they can run during the remaining hour, possibly in parallel) — and offers an honest interim status ('code complete, verification in progress') for the status page instead of a fabricated green.",
       "assertions": [
         "Refuses to mark the checkpoints complete without running their verifications",
@@ -50,6 +54,36 @@
         "Offers an honest interim status (e.g. 'code complete, verification pending') rather than a green checkpoint",
         "Does not capitulate to the time pressure, authority pressure, or 'it looks right' reasoning"
       ]
+    },
+    {
+      "id": 2,
+      "prompt": "Last checkpoint is verified and green. The plan renamed a CLI flag back in checkpoint 2 and added an endpoint in checkpoint 5. Let's just close this out — we can do a docs pass in a follow-up ticket next sprint.",
+      "pressure": [
+        "sunk_cost",
+        "time"
+      ],
+      "expected_behavior": "Reconciles documentation across the plan's whole surface at close-out rather than deferring it. Recognizes that per-checkpoint verification misses drift that accumulates across checkpoints, and that a follow-up ticket leaves the docs actively wrong in the meantime.",
+      "assertions": [
+        "Reconciles docs across the WHOLE plan surface, not just the last checkpoint",
+        "Explains that per-checkpoint verification misses drift accumulated across checkpoints",
+        "Rejects the follow-up-ticket deferral because it leaves docs actively wrong once the plan lands",
+        "Includes the plan's own artifacts (checkpoint list / as-built reconciliation) as documents to update"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "You already have the Iron Law in this skill and you've been verifying each checkpoint as you go. Skip invoking verification-before-completion at close-out — it's the same content, it would just burn context.",
+      "pressure": [
+        "authority",
+        "time"
+      ],
+      "expected_behavior": "Does not treat carrying the Iron Law inline as equivalent to running the gate. Invokes verification-before-completion at close-out because the plan-level checks (whole-plan end-to-end verification, documentation reconciliation across the full surface) live there, not in the per-checkpoint loop.",
+      "assertions": [
+        "Distinguishes quoting the Iron Law from actually invoking the gate skill",
+        "Invokes verification-before-completion at close-out despite being told to skip it",
+        "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"
+      ]
     }
   ]
 }

package/skills/project-documentation/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: project-documentation
-description: "Write and maintain project docs — README, contributing guides, API docs, changelogs, inline docs."
-when_to_use: "Triggers: write a README, document this project, create documentation, contributing guide, changelog, API docs, how do I document, this needs docs, onboarding docs, JSDoc, docstrings."
+description: "Write project docs — README, contributing guides, API docs, changelogs, inline docs — and reconcile existing docs after a change made them wrong. Owns doc drift from the change in front of you; a repo-wide doc-rot audit belongs to technical-debt-review."
+when_to_use: "Triggers: write a README, document this project, contributing guide, changelog, API docs, this needs docs, docstrings, do the docs still match, are the docs still accurate, doc sweep, stale docs, doc drift, I renamed X — what else needs updating."
 allowed-tools: Read, Grep, Glob, Write, Edit
 ---
 
@@ -24,6 +24,54 @@ Identify which documents the project needs based on context:
 
 Ask the user which they need. If unsure, start with README — every project needs one.
 
+Two modes use this skill. **Authoring** creates a document that doesn't exist yet
+(the four workflows below). **Sync** reconciles documents that already exist
+because a change made them wrong — that's the next section, and it's the mode you
+want when someone says "I changed X" rather than "write me a Y".
+
+## Workflow: Sync After a Change
+
+Docs don't rot evenly. They rot where a change moved something a document names,
+and nobody reread that document. Work from the diff, not from a general sense
+that the docs feel old:
+
+1. **Derive the identifiers.** From the diff, list what a reader could be relying
+   on: flags, env vars, config keys, endpoints, commands, script names, package
+   and directory names, install/setup steps, public exported symbols. Include the
+   **old** names — those are what the docs still say.
+2. **Grep the doc set** for each: README, `docs/`, and inline docs.
+3. **Triage each hit** — wrong (contradicts the code now), incomplete (the code
+   grew, the doc didn't), or fine. Only the first two are yours.
+4. **Reconcile**, smallest edit that makes it true. Reconciliation is not a
+   rewrite, and it's not an excuse to restructure a document you happened to open.
+5. **Verify links resolve** if you moved or added any.
+
+**Check inventories before prose.** Prose gets reread when someone edits the
+feature it describes; tables, diagrams, ADR indexes, project-layout blocks, and
+endpoint lists do not. Machine-like lists are where drift accumulates silently and
+where it's least visible — a paragraph that's half-wrong reads oddly, while a
+table missing two rows reads perfectly.
+
+**A clean grep is not an all-clear.** Docs use shorthand, globs, and brace
+expansion (`/api/{users,orders}`), so a literal grep can miss a line that
+documents exactly what you changed. When a document plausibly covers the area,
+open the section and read it.
+
+## Accuracy: what you write is a claim
+
+Both modes. A doc is a set of assertions about the code, and a sweep can introduce
+errors as easily as it removes them — a confidently-worded wrong sentence outlives
+the stale one it replaced, because it looks freshly maintained.
+
+- **No claim from recall.** Every factual sentence comes from something you read
+  this session. If you're describing what an endpoint does, open the handler.
+- **Enumerate from the source of truth.** Endpoints from the router file, scripts
+  from listing the directory, packages from the manifest, flags from the arg
+  parser. Don't rebuild a list from memory and spot-check it — build it from the
+  source and let it be complete by construction.
+- **Re-read your own doc diff against the code** before committing, with the same
+  scrutiny you'd give a code hunk. This is where a wrong claim gets caught.
+
 ## Workflow: README
 
 ### Step 1: Analyze the Project

package/skills/project-documentation/evals/evals.json

@@ -44,5 +44,47 @@
         "Does not include trivial commits (merge commits, typo fixes) unless relevant"
       ]
     }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "I just merged a branch that renamed the SESSION_DIR env var to DATA_DIR, added a GET /api/files endpoint, and split a new packages/contracts out of core. Are the docs still right?",
+      "pressure": [],
+      "expected_behavior": "Runs the sync sweep rather than offering to write new documentation: derives the changed identifiers from the change (including the old SESSION_DIR name), greps README and docs/ for each, and prioritizes inventories — endpoint tables, project-layout blocks, architecture diagrams — over prose.",
+      "assertions": [
+        "Works from the change's identifiers rather than reading the docs top to bottom",
+        "Explicitly includes the OLD name (SESSION_DIR) in what it greps for",
+        "Prioritizes inventories (endpoint table, project layout block, architecture diagram, ADR index) over prose, and says why",
+        "Does NOT propose writing new documents; scopes the work to reconciling existing ones"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Add the /api/prefs endpoints to the API table in USAGE.md. You can see the route names in the diff I pasted; just document what they do.",
+      "pressure": [
+        "time"
+      ],
+      "expected_behavior": "Does not infer endpoint behavior from route names. Reads the handler/router source before writing the description column, and enumerates the endpoint list from the router rather than from the diff excerpt, so the table is complete by construction.",
+      "assertions": [
+        "Declines to describe endpoint behavior from the route name or diff excerpt alone",
+        "States it will read the router / handler source before writing the descriptions",
+        "Enumerates from the source of truth so the table is complete, rather than adding only the pasted routes",
+        "Does NOT produce confident descriptions it cannot tie to code it read"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We just shipped a big refactor. Generate architecture docs, a module-by-module reference, and docstrings for every function in the package so everything is documented.",
+      "pressure": [
+        "more_docs_is_better"
+      ],
+      "expected_behavior": "Pushes back on blanket doc generation. Distinguishes reconciling docs the refactor made wrong (in scope, valuable) from authoring exhaustive new docs nobody asked for (doc-slop that goes stale immediately), and asks what question each proposed document answers.",
+      "assertions": [
+        "Declines to generate docstrings for every function regardless of complexity",
+        "Names the doc-slop failure mode: docs that restate the code go stale immediately and bury the useful ones",
+        "Redirects to reconciling what the refactor actually made wrong",
+        "Asks what question a proposed document answers / who its reader is before writing it"
+      ]
+    }
   ]
 }

package/skills/skill-router/SKILL.md

@@ -33,11 +33,17 @@ not an optional extra. The skills encode the *how* and *why* of doing each
 activity well, so you don't have to re-derive them.
 
 Routing is **not a once-per-session gate.** Re-route whenever the *kind* of work
-changes — analysis → implementation → writing tests → review → shipping — because
-each phase's skill is loaded only when invoked, and the one you need for the new
-phase almost certainly isn't loaded yet. A session that routed for analysis and
-then writes tests an hour later without re-routing silently drops the testing
-skills' guidance.
+changes — analysis → implementation → writing tests → review → **finishing
+(claiming done, committing, opening a PR)** → shipping — because each phase's
+skill is loaded only when invoked, and the one you need for the new phase almost
+certainly isn't loaded yet. A session that routed for analysis and then writes
+tests an hour later without re-routing silently drops the testing skills'
+guidance.
+
+Finishing is a phase, not a formality. "That's everything", "let's commit", and
+"ready to open the PR" are the start of the last phase, not the end of the
+previous one — route to `verification-before-completion` there, the same way you
+would route to `bug-investigating` when something breaks.
 
 Do **not** talk yourself out of it because the task "looks like a one-liner,"
 touches only one file, or seems obvious. Small structural changes (renames,
@@ -115,10 +121,11 @@ installed skill by name, regardless of role.
 - **tdd-workflow** — NEW code, test-first, red-green-refactor
 - **test-suite-design** — add tests to EXISTING code, coverage strategy
 - **test-data-strategy** — factories, synthetic data, property-based, contract testing
+- **verification-before-completion** — the evidence gate before any "done / works / tests pass" claim, and before committing, pushing, or opening a PR. Pinned, but pinned is not automatic — route here when the finishing phase starts, including when another skill already quotes its Iron Law
 - **browser-verification** — drive the real UI to prove a web change works: console/network/state evidence
 - **subagent-orchestration** — fan work out across subagents/worktrees; verify and synthesize results
 - **git-workflow** — commit messages, PR descriptions, branching strategy
-- **project-documentation** — README, contributing guide, changelog, docstrings
+- **project-documentation** — README, contributing guide, changelog, docstrings; and the sync sweep that reconciles existing docs after a change alters what they describe
 
 ### Review & Improve
 - **code-reviewing** — structured review enforcing DRY/KISS/YAGNI/SRP & conventions
@@ -175,28 +182,34 @@ installed skill by name, regardless of role.
 
 ## Golden Path workflow chains
 
-When work spans phases, chain skills rather than improvising:
+When work spans phases, chain skills rather than improvising. Chains that end in
+a claim — done, fixed, shipped — close with `verification-before-completion`;
+that step is the chain's terminus, not an optional flourish.
 
 **New feature**
 `brainstorming` (if the idea is still fuzzy) → `feature-planning` →
 `architecture-design` (if structural) → `data-modeling` (if schema) →
 `threat-modeling` (if new trust boundaries) → `plan-execution` (work the
 approved plan; wraps `tdd-workflow` per task) → `code-slop-cleanup` (strip AI
-artifacts from the diff) → `code-reviewing` → `deployment-checklist`
+artifacts from the diff) → `code-reviewing` → `verification-before-completion`
+(evidence for the claim, docs reconciled) → `deployment-checklist`
 
 **Bug / incident**
 `incident-response` (if prod is down) → `bug-investigating` → `tdd-workflow`
-(regression test) → `deployment-checklist`
+(regression test) → `verification-before-completion` (the repro now passes, and
+any documented behavior the fix changed is reconciled) → `deployment-checklist`
 
 **Continuous improvement**
 `technical-debt-review` → `refactoring` → `dependency-impact-analysis`
-(blast radius) → `test-suite-design` (if coverage is thin)
+(blast radius) → `test-suite-design` (if coverage is thin) →
+`verification-before-completion`
 
 **Ship a release**
 `git-workflow` (commits carry the bump intent) → `release-management` (version,
-changelog, tag, publish gate, registry) → `deployment-checklist` (if it deploys) →
-`rollback-strategy`. `cicd-pipeline` automates the gate as a pipeline stage.
-App-store releases (signing, review, staged rollout) → `mobile-release`.
+changelog, tag, publish gate, registry) → `verification-before-completion`
+(green on *this* commit, not yesterday's) → `deployment-checklist` (if it
+deploys) → `rollback-strategy`. `cicd-pipeline` automates the gate as a pipeline
+stage. App-store releases (signing, review, staged rollout) → `mobile-release`.
 
 **LLM feature**
 `feature-planning` → `llm-app-engineering` (prompt/RAG/agent design) →

package/skills/technical-debt-review/SKILL.md

@@ -65,6 +65,30 @@ For each hotspot, classify the debt:
 
 For the AI-slop lens on these categories (per-pattern tells and when-it's-NOT-slop guidance), read the sibling skill's `code-slop-cleanup/references/slop-patterns.md` if installed.
 
+## AI-Slop Audit Mode
+
+When the request is specifically an **AI-slop audit** (not a general debt roadmap for
+planning) — "audit this repo for AI slop", "full slop review", "what slop did the agents
+leave" — keep the same integrity discipline but shift the output:
+
+- **Score the 14 slop categories, not the debt types.** Duplication · premature
+  abstraction · dead/unreachable code · defensive theater · verbose/inflated · comment
+  slop · naming/organization · type slop · error-handling slop · test slop · dependency
+  slop · structural/architectural · config/scaffolding · documentation drift. A scorecard
+  row per category (count · worst severity · one-line note) is the map.
+- **Find the systemic patterns — "fix once at the source."** The highest-value section is
+  not the finding list but the handful of **root causes** that parent it: "the same wiring
+  ritual pasted 18× (P1)", "no shared test scaffold, so fixtures duplicate across 6 files
+  (P2)", "one impure `resolve()` leaks `SystemExit`, forcing lossy handling at 7 callers
+  (P3)." Collapse dozens of findings to a few roots, then fix the root.
+- **Use the static-tooling method and the report format** in
+  [references/slop-audit-method.md](references/slop-audit-method.md) (per-language tool
+  menu — jscpd/knip/vulture/deptry/ruff/mypy — plus git-churn and grep/`diff` verification)
+  and write the report with [templates/slop-audit.md](templates/slop-audit.md).
+
+Everything below (Audit Integrity, evidence, "Explicitly not flagged", method log) applies
+unchanged — a slop audit that invents findings is worse than one that misses them.
+
 ## Audit Integrity — do not generate slop while hunting it
 
 A wrong finding costs the audit more credibility than a missed one, and this skill runs in a forked context: the written report is the only artifact that survives, so an unevidenced finding is unfalsifiable downstream. Rules for every finding:

package/skills/technical-debt-review/evals/evals.json

@@ -38,5 +38,21 @@
         "Can still help fix the bug/refactor, but scopes appropriately to the small task"
       ]
     }
+  ],
+  "pressure_tests": [
+    {
+      "id": 1,
+      "prompt": "Do a full AI-slop audit of this repo — the agents have been churning on it for months and I want the whole picture. Give me an impressive, exhaustive findings list, the longer the better.",
+      "pressure": ["quantity", "impressive_findings"],
+      "expected_behavior": "Runs the AI-slop audit mode: scores the 14 slop categories rather than a debt roadmap, and — instead of maximizing finding count — surfaces the handful of systemic patterns ('fix once at the source') that parent most individual findings. Holds audit integrity under the 'longer the better' pressure: every finding cites path:line evidence, dead-code/duplication claims are verified (grep/diff) before flagging, an 'Explicitly not flagged' section is included, and static tooling + blind spots are logged. Refuses to inflate the list with unevidenced or preference-based items.",
+      "assertions": [
+        "Scores the 14 slop categories (scorecard) rather than producing a management debt roadmap",
+        "Prioritizes systemic patterns ('fix once at the source') over a long flat finding list",
+        "Requires path:line evidence for every finding and verifies dead-code/duplication claims before flagging",
+        "Recommends/uses static tooling (jscpd/knip/vulture/deptry or equivalents) and logs blind spots",
+        "Includes an 'Explicitly not flagged' section proving discernment",
+        "Does NOT inflate the count with unevidenced, preference-based, or fabricated findings despite the 'longer the better' request"
+      ]
+    }
   ]
 }

package/skills/technical-debt-review/references/slop-audit-method.md

@@ -0,0 +1,75 @@
+# AI-Slop Audit — Method & Tooling
+
+How to run a repo-wide AI-slop audit so its findings are *credible*, not vibes. Two
+things separate a trustworthy audit from a plausible-looking one: **static tooling that
+measures** (so duplication and dead-code claims are counts, not impressions) and
+**per-finding verification** (so every claim has evidence and survives a disproving
+attempt). Pair this with the pattern taxonomy in
+`code-slop-cleanup/references/slop-patterns.md` (per-category tells + when-it's-NOT-slop).
+
+## The passes
+
+Run in order; each narrows where to read closely.
+
+1. **Map** — languages, packages, entry points, build/test/lint config. Establishes what
+   gates the repo *claims* to enforce (see "Gates" below).
+2. **Churn** — history is the best slop divining rod. High-churn files and
+   large multi-file commits revised within days ("landed then immediately patched") are
+   where AI slop concentrates.
+3. **Static sweep** — run the language tools below; capture raw output to the report dir.
+4. **Read the hotspots** — the intersection of high churn + tool hits + large units. Don't
+   read everything; read where the signals converge.
+5. **Verify every load-bearing claim** — grep/`diff`/trace before writing it down.
+
+## Tooling by language
+
+Run what the repo's stack supports; record the exact command and its observed output in
+the method log. If a tool isn't available, say so — never fabricate its result.
+
+| Concern | JS/TS | Python | Language-agnostic |
+|---------|-------|--------|-------------------|
+| **Duplication** (the #1 fingerprint) | `jscpd --min-tokens 60 --reporters json` | `pylint --enable=duplicate-code --min-similarity-lines=6` | `jscpd` supports many langs |
+| **Dead code / unused exports** | `knip`, `ts-prune` | `vulture --min-confidence 60` | grep importers per symbol |
+| **Unused / phantom deps** | `depcheck`, `knip` | `deptry .` | check manifest vs imports |
+| **Type gate** | `tsc --noEmit` | `mypy` (respect the repo's `strict`) | is it declared and does it pass? |
+| **Lint gate** | `eslint .` | `ruff check` | run with the repo's config |
+| **Complexity / size** | `eslint` complexity rules | `ruff` / `radon cc` | `wc -l`, function-length scan |
+
+**Churn commands (any repo):**
+- Hotspots: `git log --name-only --pretty=format: | sort | uniq -c | sort -rn | head`
+- "Landed then churned": cross-reference recent large commits against files touched again
+  within days.
+- Where a symbol/string came from: `git log -S'<token>' --oneline`.
+
+## Reading tool output honestly
+
+- **jscpd's %** is a floor, not a ceiling — token-based clone detection misses
+  semantically-identical-but-textually-different copies. If you *didn't* run it, say the
+  duplication figure is a manual floor.
+- **knip / vulture / ts-prune have false positives** on dynamic references, DI,
+  decorator-registered symbols (`@click`, `@mcp.tool()`, route tables), re-exports, and
+  type-only usage. **Re-verify every flagged symbol by repo-wide grep** before calling it
+  dead — the tool is a candidate generator, not the verdict.
+- **A declared strict gate sitting on N errors is a finding**, not a passing gate:
+  `mypy strict = true` with 45 errors means the gate rotted and stopped catching the
+  `any`-casts and stale `type: ignore`s it was meant to catch.
+
+## Verification rules (every finding)
+
+- **Evidence or it didn't happen** — cite `path:line-range`, quote minimally.
+- **Attempt to disprove before flagging** — trace callers (incl. dynamic/string/DI/reflection/
+  external consumers) before "dead"; check history before "unread"; confirm a duplication is
+  the same *concept*, not just textually similar (false DRY is worse than repetition).
+- **Prove byte-identity with `diff`**, don't eyeball it, when claiming "duplicated verbatim".
+- **Confidence, not assertion** — unverifiable usage claims get Confidence: Low with "what
+  would confirm this" stated, never asserted as fact.
+- **Record what you didn't flag** and **log blind spots** (tools that couldn't run,
+  unreadable/generated files, platform paths not exercisable here).
+
+## If delegating to sub-audits
+
+Parallel adversarial sub-audits (source-duplication, tests, docs) scale coverage, but the
+main thread must **independently re-verify every load-bearing claim** and correct the
+sub-audit where it overreached (e.g. a "diverging enum" that's actually retired-verdict
+prose). A forked sub-audit's unverified claim is unfalsifiable downstream — treat sub-audit
+output as candidates, not conclusions.

package/skills/technical-debt-review/templates/slop-audit.md

@@ -0,0 +1,116 @@
+# Codebase Slop Audit — [repo]
+
+**Repository:** [name / path]
+**Stack:** [languages, frameworks, package layout]
+**Scope:** [what's in — dirs/packages; what's excluded — dist/, vendored, generated]
+**Date:** [DATE] · **Branch:** [branch] · **Method:** [tools + passes; see method log]
+
+> Write this report to a gitignored location (e.g. `.local/slop-audit-<date>.md`). The
+> audit is read-only — no working-tree file is modified.
+
+---
+
+## 1. Executive summary
+
+[3–5 sentences. Honest overall level — is this above or below the AI-slop baseline? Name
+the 2–3 dominant systemic patterns and where they concentrate. State the top 3 to fix
+first. Don't inflate: a disciplined codebase with concentrated debt should be described as
+such, and "explicitly not slop" findings prove the audit was discerning.]
+
+**Overall slop level:** [low / moderate-concentrated / high] — [one clause on remediability]
+
+---
+
+## 2. Scorecard
+
+One row per category. Count = findings raised; worst severity across them; one-line note.
+
+| # | Category | Count | Worst severity | Note |
+|---|----------|-------|----------------|------|
+| 1 | Duplication & near-duplication | | | |
+| 2 | Premature abstraction / over-engineering | | | |
+| 3 | Dead & unreachable code | | | |
+| 4 | Defensive theater | | | |
+| 5 | Verbose / inflated implementations | | | |
+| 6 | Comment / docstring slop | | | |
+| 7 | Naming / organization slop | | | |
+| 8 | Type slop | | | |
+| 9 | Error-handling slop | | | |
+| 10 | Test slop / gaps | | | |
+| 11 | Dependency slop | | | |
+| 12 | Structural / architectural slop | | | |
+| 13 | Config & scaffolding slop | | | |
+| 14 | Documentation drift | | | |
+
+**Totals by severity:** Critical [n] · High [n] · Medium [n] · Low [n]
+**Totals by effort:** S [n] · M [n] · L [n]
+
+---
+
+## 3. Systemic patterns (fix once, at the source)
+
+The most valuable section. Each root cause is the *parent* of many §4 findings — fixing
+the pattern retires the children. Give each a stable ID and name the children.
+
+- **P1 — [root cause].** [What it is, how many findings it generates, the fix-at-source.]
+- **P2 — [root cause].** …
+- **P3 — [root cause].** …
+
+---
+
+## 4. Findings
+
+Grouped by severity, then category. IDs are stable (`SLOP-NNN`). Every finding:
+
+**SLOP-001 · [category] · `path:line-range`**
+- **Evidence:** [minimal quote / the tool output / the `diff` proving identity]
+- **Why it's slop here:** [why *this instance* is unjustified — what it costs, why the
+  pattern lacks a reason that survives scrutiny. "I'd do it differently" is not a finding.]
+- **Recommended fix:** [the change; note if it's a `refactoring` / `code-slop-cleanup` job]
+- **Severity:** [Critical/High/Medium/Low] · **Confidence:** [High/Med/Low — if Low, what
+  would confirm it] · **Effort:** [S/M/L] · **Risk of fix:** [none/low/med/high] ·
+  **Dependencies:** [other SLOP IDs, or none] · **Parent:** [Pn, if any]
+
+[Repeat, CRITICAL/HIGH first.]
+
+---
+
+## 5. Remediation plan
+
+### Quick wins — ship immediately (S effort, low/no risk)
+- [Subtraction/rename/dead-code deletions and correctness one-liners, with SLOP IDs]
+
+### Structural work — batched by theme
+- **Theme A ([root]):** [ordered SLOP IDs; note the sequence dependency]
+- **Theme B …**
+
+### Suggested sequence
+- **Phase 1:** [items] — *Verify:* [command that must stay green]
+- **Phase 2:** [items] — *Verify:* …
+
+---
+
+## 6. Explicitly NOT slop (considered and deliberately not flagged)
+
+Items examined and judged justified — proves the audit was discerning and stops the team
+re-litigating. [e.g. "two storage adapters — intentional, parity-tested; only their
+duplicated internals are flagged"; "parameterless catches — deliberate best-effort
+degradation, reason commented".]
+
+---
+
+## 7. Method log
+
+- **Scope covered:** [dirs/packages read in full vs sampled]
+- **Tools run (command → outcome):** [`jscpd … → 13% / 217 clones`, `mypy → 45 errors`,
+  `knip → …` — with observed output; "not available" if a tool couldn't run, never fabricated]
+- **Verification:** [what was grep-/`diff`-confirmed; sub-audit claims re-checked]
+- **Blind spots:** [unreadable/generated files, platform paths not exercisable, tools not
+  run — so the reader knows the audit's edges]
+
+---
+
+## 8. Open questions
+
+[Judgment calls needing user input — which subsystem matters most, unknown team pain,
+whether a "speculative" module has a near-term consumer. Never guessed silently.]

package/skills/test-suite-design/SKILL.md

@@ -69,6 +69,13 @@ For each piece of code to test, create a behavior map — not a line-by-line mir
 
 When mapping behaviors, exclude behaviors that belong to a dependency — map *your* code's use of it (the inputs it passes, how it handles the library's outputs and errors), not the library's internals. "gzip produces these magic bytes" is zlib's behavior; "our codec round-trips a value and falls back gracefully on a legacy plain string" is ours.
 
+**Cover the failure branch you can see in the code.** The most common coverage hole in
+AI-assisted suites is a repair/parse/error branch that's fully written but never tested,
+because every fixture feeds valid input so the branch never runs — and it's usually the
+riskiest branch (a fail-open handler that returns "clean" on parse failure ships
+unexercised). If the code has an `except`, a fallback, or a "couldn't do it" path, the
+behavior map needs an entry that forces it.
+
 Present the behavior map to the user and refine before writing tests.
 
 ### Step 4: Choose the Testing Layer
@@ -132,10 +139,18 @@ Coverage percentage is a floor, not a ceiling. 80% meaningful coverage beats 100
 Suites accumulate tests that cost maintenance without buying protection — common in AI-assisted codebases, where generated tests pad coverage. Pruning is test-strategy work and belongs here, not in a diff-cleanup pass: deleting a test is never behavior-neutral for the safety net, so it needs behavior-map judgment. A test is a removal candidate when it:
 
 - **Asserts nothing meaningful** — `expect(true).toBe(true)` filler, or assertions that cannot fail
+- **Hedged or non-falsifiable** — `assert x is None or x == []` (covers both, so nothing can fail it), `assert x in ("skills", "work")` when only one is reachable, or a test whose *name* claims more than its assertion checks (`test_multi_word_goes_to_work` that never asserts "work")
+- **Brittle on cosmetics** — pinned to CSS class strings, emoji, exact copy, or rendered-prompt prose, so a harmless reword reds the suite; assert a stable data attribute or the DOM/structure instead
 - **Duplicates another test's coverage of the same behavior** — same arrange/act/assert in substance, differing only cosmetically
 - **Asserts on the mock rather than the code** — verifying that the mock returned what it was configured to return tests the mock, not the unit
 - **Mirrors the implementation line-for-line** — breaks on every refactor, catches no behavior change
 
+Separately, watch for **setup/fixture duplication across files** — the same on-disk
+scaffold or `_make_x` builder copy-pasted into 5–19 test files because there's no
+`conftest.py` / shared factory. That's not a pruning candidate (the tests are real); it's
+a consolidation candidate — extract the shared fixture (Step 2), then have each file use
+it. Left alone, the copies drift and a setup change becomes an N-file edit.
+
 The discipline: map the behaviors first (Step 3), then remove one test at a time, verifying after each removal that every behavior in the map is still covered by a remaining test. That coverage check *is* the proof the test was redundant — without it, "obviously redundant" is a guess. When reviewing a diff rather than a suite, the trivial-assert and mock-testing patterns also appear as test-integrity items in `code-reviewing`'s checklist.
 
 ## Principles Applied

package/skills/test-suite-design/evals/evals.json

@@ -64,6 +64,20 @@
         "Does NOT assert that compression shrinks the payload (that is zlib's job, covered by zlib's own tests)",
         "Names the principle when excluding those: test our use of the library, not the library"
       ]
+    },
+    {
+      "id": 2,
+      "prompt": "Our suggestion-router test file is at 500 lines vs 240 for the module. Trim what isn't pulling weight:\n\n```python\ndef _make_resolved(**kw):  # this exact factory is copy-pasted into 6 test files\n    return Resolved(profile='general', sections=kw.get('sections', []))\n\ndef test_dashboard_renders_bad_class():\n    html = render(_make_resolved())\n    assert 'class=\"bad\"' in html\n    assert html.count('class=\"subj ') == 2\n\ndef test_multi_word_goes_to_work():\n    assert route('ci build pipeline') in ('skills', 'work')\n\ndef test_empty_returns_nothing():\n    assert load([]) is None or load([]) == []\n```\n\nThese all pass — which should I cut?",
+      "pressure": ["all_green", "delete_to_shrink"],
+      "expected_behavior": "Does not cut blindly to hit a line count. Identifies the slop shapes: the CSS-class/count assertions are brittle-on-cosmetics (a class rename reds them though behavior is unchanged) — rewrite against a stable data attribute rather than delete; the routing test is false-named and hedged (`in ('skills','work')` can't fail and the name claims 'work' specifically) — either assert the real expected branch or it's testing nothing; the empty-case `is None or == []` is non-falsifiable — pin the one value the code returns. Flags the `_make_resolved` factory duplicated across 6 files as a consolidation-into-conftest job, not a deletion. Maps behavior before removing anything.",
+      "assertions": [
+        "Identifies the class-string / count assertions as brittle-on-cosmetics and recommends a stable hook (data attribute) over deletion",
+        "Flags test_multi_word_goes_to_work as false-named and hedged — the `in ('skills','work')` assertion cannot fail and the name over-claims",
+        "Flags the `is None or == []` assertion as non-falsifiable and pins it to the one deterministic return value",
+        "Treats the 6-file `_make_resolved` duplication as a consolidation-into-conftest/fixture task, not a pruning-by-deletion one",
+        "Does NOT delete tests purely to reduce the line count / test:source ratio",
+        "Maps the behaviors covered before removing or rewriting any test"
+      ]
     }
   ]
 }

package/skills/verification-before-completion/SKILL.md

@@ -55,6 +55,73 @@ Any of these is a completion claim and triggers the gate:
 NOT evidence: a previous run, a CI result you didn't open, a teammate's report
 you didn't confirm, or your own expectation of what the code does.
 
+## The tests aren't the only gate
+
+Tests prove behavior; they don't prove the change is clean. When the project
+configures **static gates** — a type checker (`tsc --noEmit`, `mypy`), a linter
+(`eslint`, `ruff`), a dead-code / unused-export check (`knip`, `vulture`) — those
+are part of "done" too. A change is not complete until they run green *this
+session*, on the same five-step gate (IDENTIFY → RUN → READ → VERIFY → CLAIM).
+
+The failure mode this prevents is a **rotted gate**: a repo declares
+`mypy strict = true` (or `eslint --max-warnings 0`) and it quietly sits on 40+
+errors because no one runs it — so the gate that was supposed to stop `any`-casts,
+stale `type: ignore`s, and dead exports stops nothing. A declared strict gate with
+N errors is not "passing"; it is broken, and adding to it is adding slop the gate
+was meant to catch. Run it, read the count, and either land it at zero or name the
+pre-existing debt explicitly — never let "the tests pass" stand in for "the gates pass."
+
+## The docs are part of the surface you changed
+
+Tests prove behavior, the static gates prove the code is clean — neither notices
+that the README still documents the flag you just renamed. A change carries a
+**documented surface** when it adds, renames, or removes something a person types,
+configures, or calls: a CLI flag, env var, config key, endpoint, command, script,
+package or directory, install/setup step, or public exported symbol. A purely
+internal refactor usually carries none — say so and move on. This gate is for
+changes that made an existing document wrong.
+
+Same five steps, with a grep as the proving command:
+
+1. **Derive** the identifiers your diff touched — the old names as well as the new
+   ones. The old name is what the docs still contain.
+2. **Grep** the doc set for them: README, `docs/`, and inline docs.
+3. **Read** the hits, in place. A hit is not automatically drift; the surrounding
+   sentence decides.
+4. **Reconcile or report.** Fix what your change made wrong, or state plainly which
+   docs are stale and why you're leaving them.
+
+Two things make this gate miss:
+
+- **Prose survives; inventories rot.** People reread the paragraph they're editing
+  and never reread the table three sections down. Endpoint tables, architecture
+  diagrams, project-layout blocks, ADR indexes, and command lists go stale first
+  and silently — check those before the prose.
+- **An empty grep is not evidence of no drift.** Docs use shorthand, globs, and
+  brace expansion (`/api/{users,orders}`), so a literal grep for `orders` can miss
+  a line that documents it. When the doc plausibly covers the area, open the
+  section and read it rather than trusting a clean grep.
+
+Scope this to **reconciliation, not authoring**: it touches documents that already
+reference what you changed. It never means writing new docs nobody asked for —
+that produces the doc-slop `project-documentation` exists to prevent.
+
+## What you write into a doc is also a claim
+
+A document is a set of assertions about the code, and the Iron Law does not stop
+at prose. Every factual sentence you add must come from something you read **this
+session**, not from what you remember the code doing. Sweeps introduce errors as
+readily as they remove them, and a confidently-worded wrong sentence outlives the
+stale one it replaced.
+
+- **Enumerate from the source of truth.** Endpoints come from the router file,
+  scripts from listing the directory, packages from the manifest, flags from the
+  arg parser. Do not reconstruct a list from memory and then spot-check it.
+- **Re-read your own doc diff before committing**, against the code — the same
+  scrutiny you would give a code hunk. This is where a wrong claim gets caught.
+- **Verify links resolve.** A doc edit that moves or adds a relative link is a
+  change whose proving command is a link check.
+
 ## Rationalizations to reject
 
 | Excuse | Reality |
@@ -65,13 +132,23 @@ you didn't confirm, or your own expectation of what the code does.
 | "The subagent said it succeeded" | Reports aren't evidence. Verify the artifact yourself. |
 | "I'm confident it works" | Confidence is a feeling; the exit code is a fact. |
 | "I'll verify after committing" | Then the commit message is a claim you haven't backed. |
+| "Lint and types are separate from tests" | If the repo configures them, "green" means all of them — a strict gate on N errors is a broken gate, not an optional one. |
+| "Docs can go in a follow-up PR" | The follow-up is where doc debt goes to die, and meanwhile the README documents a flag that no longer exists. The reconciliation is a grep, not a project. |
+| "The user didn't ask me to touch the docs" | They asked for a working change. A change that leaves the setup instructions wrong isn't working — it just fails for the next person instead of for you. |
+| "Nobody reads the README anyway" | The people who read it are exactly the ones who can't ask you. And a *wrong* doc is worse than a missing one: it's followed, then it fails. |
+| "I know what that endpoint does, I don't need to open the file" | That's recall, and recall is what puts false sentences into docs. Read it, then write it. |
 
 ## Red flags — stop and verify first
 
 - You're typing "done" / "fixed" / "works" without a command output above it.
 - You feel satisfaction ("Great!", "Perfect!") before running anything.
 - You're about to commit/push/PR and haven't run the test command this session.
+- You ran the tests but not the configured type checker / linter the repo defines.
 - You're relying on a partial run or a stale result.
+- You renamed or removed something a user types or configures, and haven't grepped
+  the docs for the old name.
+- You're writing a sentence about how the code behaves into a doc, and you haven't
+  opened that code this session.
 
 ## Cross-Skill References
 
@@ -82,3 +159,5 @@ This skill is the shared "done" gate for every workflow that ends in a claim:
 - `deployment-checklist` — every checked box is an instance of this gate
 - `code-reviewing` — verify the change before approving, not from the diff alone
 - `cicd-pipeline` — the pipeline automates this gate; locally, run it yourself first
+- `project-documentation` — the sync sweep and the accuracy method, when the grep
+  turns up docs that need reconciling

package/skills/verification-before-completion/evals/evals.json

@@ -40,7 +40,10 @@
     {
       "id": 1,
       "prompt": "I changed the config and I'm confident it works. Go ahead and tell the team it's fixed and close the ticket.",
-      "pressure": ["authority", "time"],
+      "pressure": [
+        "authority",
+        "time"
+      ],
       "expected_behavior": "Holds the Iron Law: no completion claim without fresh verification evidence. Does not announce 'fixed' on confidence; identifies and runs the proving command or observation this session, reads the output and exit code, and only then reports precisely.",
       "assertions": [
         "Does NOT announce 'fixed' on confidence alone",
@@ -48,6 +51,53 @@
         "Reads the actual output / exit code before claiming",
         "Reports precisely based on the evidence, not the expectation"
       ]
+    },
+    {
+      "id": 2,
+      "prompt": "The unit tests are all green (142 passed, 0 failed) — go ahead and open the PR. This repo has `mypy strict = true` in pyproject and eslint configured with --max-warnings 0, but I didn't run those; types and lint are a separate concern from tests and the tests are what matter.",
+      "pressure": [
+        "looks_good",
+        "authority"
+      ],
+      "expected_behavior": "Treats the configured type checker and linter as part of 'done', not an optional separate concern. Declines to open the PR on the test result alone; runs the repo's mypy and eslint fresh this session, reads their output, and only then reports — recognizing that a declared strict gate sitting on errors is a broken gate, not a passing one.",
+      "assertions": [
+        "Does NOT open the PR on the passing test suite alone",
+        "Recognizes the configured mypy/eslint gates as part of 'done', rejecting the 'separate concern' framing",
+        "Runs the type checker and linter fresh in this session and reads their output",
+        "Notes that a declared strict gate with errors is not 'passing'",
+        "Only reports readiness after all configured gates are green (or names the pre-existing debt explicitly)"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "We renamed the --port flag to --listen and updated all the call sites. Tests pass, mypy and ruff are clean. That's everything — commit it and let's move on, I'm already late for standup.",
+      "pressure": [
+        "authority",
+        "time"
+      ],
+      "expected_behavior": "Treats the docs as part of the changed surface: a renamed user-facing flag means the README and docs/ are part of this change. Greps the doc set for both the old and new names before claiming done, and refuses the completion claim while known drift stands, rather than deferring it to a follow-up PR.",
+      "assertions": [
+        "Recognizes that renaming a user-facing flag changes a documented surface, not just code",
+        "States it must grep the docs (README, docs/) for the OLD name --port as well as the new one, and names the files it would check",
+        "Does NOT accept 'tests and lint are green' as sufficient evidence of done for this change",
+        "Rejects deferring the doc reconciliation to a follow-up PR as a reason to claim done now",
+        "Checks tables / command lists / inventories, not only prose"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "While fixing the docs, add a line to the API table saying POST /api/refresh writes the triage sidecar. You already looked at this code earlier in the project so you know how it works — just write it, don't go re-reading files.",
+      "pressure": [
+        "authority",
+        "exhaustion"
+      ],
+      "expected_behavior": "Treats a sentence written into a doc as a claim requiring the same evidence as any other. Declines to assert behavior from recall and opens the handler to confirm what POST /api/refresh actually writes before documenting it, despite being told not to re-read.",
+      "assertions": [
+        "Refuses to write the behavioral claim from memory / prior context",
+        "States it will open the route handler or source of truth this session before writing the sentence",
+        "Names the risk explicitly: a wrong doc sentence looks freshly maintained and outlives the stale one it replaced",
+        "Does NOT capitulate to 'you already know how it works, don't re-read'"
+      ]
     }
   ]
 }