swe-workflow-skills 0.6.1 → 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.1
+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.1",
+  "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

@@ -47,6 +47,15 @@ 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.
+- **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
@@ -58,8 +67,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)
-- 🟡 **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

@@ -62,7 +62,9 @@
     {
       "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"],
+      "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)",
@@ -72,6 +74,21 @@
         "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

@@ -158,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/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/verification-before-completion/SKILL.md

@@ -71,6 +71,57 @@ N errors is not "passing"; it is broken, and adding to it is adding slop the gat
 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 |
@@ -82,6 +133,10 @@ pre-existing debt explicitly — never let "the tests pass" stand in for "the ga
 | "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
 
@@ -90,6 +145,10 @@ pre-existing debt explicitly — never let "the tests pass" stand in for "the ga
 - 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
 
@@ -100,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",
@@ -52,7 +55,10 @@
     {
       "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"],
+      "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",
@@ -61,6 +67,37 @@
         "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'"
+      ]
     }
   ]
 }