swe-workflow-skills 0.6.1 → 0.6.3

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.3

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.3",
   "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/architecture-design/SKILL.md

@@ -10,6 +10,36 @@ Help the user make well-reasoned architectural decisions and document them in Ar
 
 ## Workflow
 
+### Step 0: Inventory What Already Exists
+
+If a system is already running, establish what it already provides before
+proposing a new service, module, boundary, or pattern. Map the current state
+**directly** from the codebase — don't infer it from the requirements, the docs,
+or memory. Docs describe the system someone intended; the code is the one you
+have.
+
+Cover both:
+
+- **Artifacts** — existing services, modules, and seams that already own, or
+  could own, the responsibility in question. Search by capability, not just by
+  name: the component that does this may be called something else entirely.
+- **Written decisions** — the ADR log, established conventions, and prior audit
+  findings. A decision already made and recorded is not yours to re-litigate
+  silently; supersede it explicitly or work within it.
+
+**Exit condition** — one line, then keep going in the same response:
+*"`<existing component>` already handles `<responsibility>`; it does / does not
+serve this because `<reason>`."*
+
+**This step is not a gate on delivering.** Greenfield — nothing built yet, or
+nothing you can reach — closes it in one line: say so and go straight to Step 1.
+When you can't inspect, name what you would check and continue under stated
+assumptions. Never answer a design question with inventory and questions alone;
+carry the options, the recommendation, and the trade-offs in the same reply.
+
+This constrains the input, not the choice. A new component is a fine outcome;
+an unexamined one isn't.
+
 ### Step 1: Frame the Decision
 
 Identify the exact decision to be made. A good architectural question is specific and scoped:
@@ -26,7 +56,8 @@ If the user's question is too broad, help narrow it by asking:
 
 Understand the current state before proposing changes:
 
-- **Current architecture**: What exists today? Read the codebase if available.
+- **Current architecture**: the Step 0 finding — what exists today, established
+  from the code rather than assumed. If you can't state it, Step 0 isn't done.
 - **Quality attributes that matter**: Performance? Scalability? Developer experience? Maintainability? Deployment simplicity?
 - **Team context**: Team size, expertise, on-call burden
 - **Growth trajectory**: Expected scale in 6-12 months (not 5 years — YAGNI)

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/configuration-strategy/SKILL.md

@@ -8,6 +8,33 @@ allowed-tools: Read, Grep, Glob, Write, Edit
 
 Design configuration that is safe, auditable, and easy to change. Most configuration problems (hardcoded secrets, production config in dev, feature flags with no off-switch) come from not designing the system upfront.
 
+## Step 0: Inventory What Already Exists
+
+Before introducing a new environment variable, secret, feature flag, or
+constant, establish what the project already defines. Inspect the current state
+**directly** — grep the tree; don't infer it from the requirements or memory.
+
+Cover both:
+
+- **Artifacts** — existing key names *and* the values themselves. Search for the
+  literal value, not just the name: the same timeout or limit is often already
+  hardcoded in two places, and adding a third is the common failure.
+- **Written decisions** — config conventions, naming schemes, `.env.example`,
+  and prior audit findings that already govern where things live.
+
+**Exit condition** — one line, then keep going in the same response:
+*"`<existing key>` already carries `<value>`; it does / does not serve this
+because `<reason>`."*
+
+**This step is not a gate on delivering.** Greenfield — nothing configured yet,
+or nothing you can reach — closes it in one line: say so and go straight to
+Step 1. When you can't inspect, name what you would check and continue under
+stated assumptions. Never answer with inventory and questions alone; produce the
+configuration design in the same reply.
+
+This constrains the input, not the choice. A new key is a fine outcome; an
+unexamined one isn't — and a duplicated value will drift.
+
 ## Step 1: Identify All Configuration Needed
 
 List every piece of configuration the feature or service requires:

package/skills/data-modeling/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: data-modeling
 description: "Design database schemas, relationships, indexes, and migration strategies — relational and document stores. Triggers: data model, schema design, ER diagram, database schema, table design, foreign key, index strategy, normalization, denormalization, migration plan, document model, partition key."
-allowed-tools: Read, Grep, Glob, Write, Edit
+allowed-tools: Read, Grep, Glob, Write, Edit, Bash
 ---
 
 # Data Modeling
@@ -10,6 +10,36 @@ Guide the user through designing data models that are normalized, consistent, an
 
 ## Workflow
 
+### Step 0: Inventory What Already Exists
+
+If any database exists, establish what it already holds before proposing a
+single new table, column, or index. Inspect the current schema **directly** —
+don't infer it from the requirements, the ORM models, or memory. Dump it from
+the live database where you can reach one, otherwise read the migration history
+end to end.
+
+Cover both:
+
+- **Artifacts** — existing tables, columns, and indexes that hold, or could
+  hold, the fact in question. Grep for the concept by name and by synonym; the
+  right table is often named for a different concern than the one you're serving.
+- **Written decisions** — ADRs, schema conventions, and prior audit findings
+  that already constrain the shape.
+
+**Exit condition** — one line, then keep going in the same response:
+*"`<existing table>` already stores `<fact>`; it does / does not serve this
+because `<reason>`."*
+
+**This step is not a gate on delivering.** Greenfield — no database yet, or none
+you can reach — closes it in one line: say so and go straight to Step 1. When
+you can't inspect (no repo access, a conversational answer), name what you would
+check and continue under stated assumptions. Never answer a schema request with
+inventory and questions alone; produce the model in the same reply.
+
+This constrains the input, not the choice. A new table is a fine outcome; an
+unexamined one isn't — and a second home for the same fact is duplication
+however well it's named.
+
 ### Step 1: Understand the Domain
 
 Before touching schemas, understand the business domain:

package/skills/frontend-architecture/SKILL.md

@@ -14,6 +14,35 @@ Design the technical structure of frontend applications — component hierarchy,
 
 ## Workflow
 
+### Step 0: Inventory What Already Exists
+
+In an existing codebase, establish what the app already provides before adding a
+new component, hook, store, or token. Search the shared surfaces **directly** —
+`components/`, `hooks/`, `lib/`, the token file, and each feature's public
+`index.ts` — rather than inferring from the design or from memory.
+
+Cover both:
+
+- **Artifacts** — existing components, hooks, stores, and tokens that already
+  cover, or nearly cover, the need. Search by behavior, not just by name: the
+  component you want often exists under a different label.
+- **Written decisions** — established conventions, the design system's rules,
+  and prior audit findings.
+
+**Exit condition** — one line, then keep going in the same response:
+*"`<existing component/hook>` already covers `<behavior>`; it does / does not
+serve this because `<reason>`."*
+
+**This step is not a gate on delivering.** Greenfield — a new app, or a codebase
+you can't reach — closes it in one line: say so and go straight to Step 1. When
+you can't inspect, name what you would check and continue under stated
+assumptions. Never answer with inventory and questions alone; produce the
+architecture in the same reply.
+
+This constrains the input, not the choice. A new component is a fine outcome; an
+unexamined one isn't — a near-duplicate of an existing one is how design systems
+rot.
+
 ### Step 1: Design the Component Hierarchy
 
 Start from the UI design (or the screen spec from `ui-ux-design`) and decompose into components:

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
@@ -75,6 +80,14 @@ when any of these fires:
 - two consecutive checkpoints failed verification
 - you catch yourself thinking "the plan didn't anticipate this, but I'll just…"
 
+A **structural question the plan didn't answer** fires this too: where a piece
+of state lives, whether to add a table, column, service, module, store, or
+config key. Don't settle it inline — **invoke `data-modeling` (data shape) or
+`architecture-design` (structure and boundaries)** and let it run its inventory
+of what already exists. These decisions arrive disguised as implementation
+details, and they're the ones the plan is least able to absorb silently:
+persistent constructs outlive the plan that introduced them.
+
 Re-planning openly is cheap; silently executing a plan that no longer matches
 reality delivers the wrong thing with perfect discipline. Sunk progress is not a
 reason to continue — the remaining work costs the same whether or not you admit
@@ -82,9 +95,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,7 +114,10 @@ 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. |
+| "This is an implementation detail, not an architecture decision" | Anything that persists — a table, a column, a config key, a shared module — is structure, whatever task it arrived under. Route it to the design skill. |
 | "We're 80% through; re-planning now wastes all that work" | Sunk cost. Verified work survives a re-plan; pushing a broken plan wastes the remaining 20% *and* the rework. |
 | "Marking them done unblocks the team; we'll backfill verification" | A false "done" misinforms every decision downstream. Report the honest state instead. |
 
@@ -103,11 +127,15 @@ reconcile plan vs as-built from the drift log, and report per checkpoint: done
 - You can't say what command verified the last checkpoint.
 - "Should work" / "looks done" appearing in your status report.
 - Mid-execution, you're building something the plan never mentioned.
+- You're about to add a persistent construct (table, column, config key, shared
+  module) that the plan never named — and you haven't checked what already exists.
 - You've stopped consulting the plan and are working from memory.
 
 ## Cross-Skill References
 
 - `feature-planning` — creates and (on re-plan) revises the plan this skill executes
+- `data-modeling` — where a schema question surfaced mid-execution belongs
+- `architecture-design` — where a structural or boundary question belongs
 - `verification-before-completion` — the per-claim evidence gate each checkpoint applies
 - `tdd-workflow` — how the implementation tasks inside a batch get built
 - `git-workflow` — commit at checkpoint boundaries; the evidence belongs in the message

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'"
+      ]
     }
   ]
 }

package/skills/writing-skills/SKILL.md

@@ -104,7 +104,10 @@ As base models improve, a skill can become pure overhead. Once per release cycle
 — or on a major base-model update — re-run the skill's 3 evals RED on shipping
 models via `evals/workflow-runner.mjs`; re-sample ×3 on borderline scores and
 read the judge journal before calling a result variance (a "flaky" case is often
-a real content gap the skill causes). If RED ≈ GREEN across all 3 evals (0/0
+a real content gap the skill causes). **First check the skill's reference mass:**
+the harnesses can't read `references/` or `templates/`, so where that content
+rivals `SKILL.md` the RED ≈ GREEN verdict is a harness artifact — judge those by
+hand instead. Otherwise, if RED ≈ GREEN across all 3 evals (0/0
 tool-dependent assertion pairs don't count), **slim first** — cut what the model
 does unaided; keep the Iron Law, boundaries, and cross-skill references — then
 re-run GREEN (gate: GREEN ≥ RED per case). Retire only after a slimmed skill