swe-workflow-skills 0.6.2 → 0.7.0

package/VERSION

@@ -1 +1 @@
-0.6.2
+0.7.0

package/catalog.json

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

package/package.json

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

package/skills/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

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

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

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

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

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

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

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

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

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

package/skills/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

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

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

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