@jesdi/skills 0.0.15 → 0.0.16

package/README.md

@@ -58,7 +58,7 @@ which ones are part of the standard setup, where they come from, and (under
 upstream with the [skills.sh](https://skills.sh/) CLI:
 
 ```bash
-npx skills add mattpocock/skills          # grill-me, grill-with-docs, grilling, improve-codebase-architecture, to-questionnaire, tdd, code-review, codebase-design, diagnosing-bugs, resolving-merge-conflicts
+npx skills add mattpocock/skills          # grill-me, grill-with-docs, grilling, improve-codebase-architecture, to-questionnaire, tdd, code-review, codebase-design, diagnosing-bugs, resolving-merge-conflicts, handoff, teach, wait-what
 npx skills add JuliusBrussee/caveman      # caveman suite
 npx skills add vercel-labs/skills         # find-skills
 npx skills add vercel-labs/agent-skills   # vercel-react-best-practices

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesdi/skills",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "jesdi's agent skills (content package consumed by @jesdi/skills-cli)",
   "license": "MIT",
   "repository": {

package/skills/deep-quality-review/SKILL.md

@@ -34,23 +34,33 @@ size, orchestration.
 causes it (an invariant enforced by an optional parameter is a structure
 finding). Everything else belongs in a different review.
 
+**Repo conventions come first.** Read the repo's AGENTS.md (and CLAUDE.md,
+CONTRIBUTING.md, or coding-standards file) before the diff. A breach of a
+documented rule is a finding; cite the file and the rule. A documented rule
+overrides a smell: when the repo endorses a pattern the table would flag,
+don't flag it.
+
 ## The smells
 
 Run every meaningful change through this table, top to bottom. Each row is one
 concept; the *Ask* is the question that exposes it, the *Remedy* is what to
-push for.
+push for. Names in parentheses are the matching Fowler smells (*Refactoring*,
+ch. 3), folded into the row that already covers them.
 
 | # | Smell | Ask | Remedy |
 |---|-------|-----|--------|
-| 1 | **Duplicated concept** — one idea expressed twice: near-duplicate helper, parallel model, copy-pasted branch, a flag *and* an optional both meaning "off", the same predicate reimplemented instead of reused | What single concept are these copies of? Where is its canonical home? | Name the concept once; make the variants its data or parameters; delete the copies. Never accept a second copy because the first one exists. |
+| 1 | **Duplicated concept** — one idea expressed twice: near-duplicate helper, parallel model, copy-pasted branch (Duplicated Code), a flag *and* an optional both meaning "off", the same predicate reimplemented instead of reused, the same `switch`/`if`-cascade on the same type in two places (Repeated Switches) | What single concept are these copies of? Where is its canonical home? | Name the concept once; make the variants its data or parameters (one map or one polymorphic dispatch both sites share); delete the copies. Never accept a second copy because the first one exists. |
 | 2 | **Complexity rearranged, not deleted** — the diff moves code around but the reader still holds the same number of branches, modes, and helpers | Which reframing of the model or ownership makes these branches disappear? | Change the model so the special case becomes the default flow. Prefer the version that feels inevitable in hindsight. |
 | 3 | **Special case in a shared flow** — new `if`, one-off boolean, nullable mode, or feature check bolted into an unrelated path | Whose decision is this, and why is it made here? | Move it behind its own abstraction (policy, resolver, dispatcher, module); keep the shared path linear. |
-| 4 | **Wrong layer / boundary leak** — feature logic in a shared module, implementation details through an API, callers re-deriving what the owner already knows | Which module owns this concept? | Move the logic to the owner; callers receive results, not raw inputs to recompute. |
-| 5 | **Indirection without clarity** — thin wrapper, pass-through helper, "generic" mechanism hiding a simple data shape | What does the reader learn from this layer? | Delete it and keep the direct call. Boring and direct beats clever. |
-| 6 | **Weak contract** — `any`, `unknown`, casts, optional params, silent fallbacks that paper over an unclear invariant | What invariant is this hiding? | Make the boundary explicit in the type so the control flow simplifies. |
-| 7 | **File sprawl** — the diff pushes a file past a healthy size boundary (~1k lines) | Should this be decomposed *before* adding to it? | Split by concept first; waive only with a compelling structural reason. |
-| 8 | **Needless sequencing / non-atomic update** — independent work serialized, related updates that can leave state half-applied | Is this actually dependent? Can it be observed half-done? | Parallelize independent work; group related updates. Not micro-optimization — brittleness. |
-| 9 | **Short-horizon change** — "temporary", TODO-later, quick patch, deferred cleanup, a shape chosen because it is the smallest diff | What does this look like when its reason is gone? What does removing it cost? | Do the durable fix now, or structure the stopgap so removal is a pure deletion (one branch, one file), never a refactor of live callers. |
+| 4 | **Wrong layer / boundary leak** — feature logic in a shared module, implementation details through an API, callers re-deriving what the owner already knows, a function that works on another module's data more than its own (Feature Envy), callers walking `a.b().c().d()` to reach what they need (Message Chains) | Which module owns this concept? | Move the logic to the owner; callers receive results, not raw inputs to recompute. Hide a navigation walk behind one method on the first object. |
+| 5 | **Change doesn't follow module lines** — one logical change forces small edits scattered across many files (Shotgun Surgery), or one module is edited for several unrelated reasons (Divergent Change) | If this rule changes again, how many files move? Does this module have one reason to change? | Gather what changes together into one module; split a module that changes for unrelated reasons. |
+| 6 | **Indirection without clarity** — thin wrapper, pass-through helper or class that only delegates (Middle Man), "generic" mechanism hiding a simple data shape, parameters, hooks or abstractions for needs nobody has yet (Speculative Generality) | What does the reader learn from this layer? Who needs this flexibility today? | Delete it and keep the direct call. Boring and direct beats clever. |
+| 7 | **Refused inheritance** — a subclass or implementer that ignores, stubs out, or overrides most of what it inherits (Refused Bequest) | Is this really a kind of its parent? | Drop the inheritance; compose, or implement a narrower interface. |
+| 8 | **Weak contract** — `any`, `unknown`, casts, optional params, silent fallbacks that paper over an unclear invariant; a string or number standing in for a domain concept (Primitive Obsession); the same few fields or params always travelling together (Data Clumps) | What invariant is this hiding? Which type wants to be born? | Make the boundary explicit in the type, a small domain type or one bundled type, so the control flow simplifies. |
+| 9 | **Mysterious name** — a function, variable, or type whose name hides what it does or holds, or says something it no longer does | Could a reader predict the body from the name? | Rename it. If no honest name comes, the concept is murky: fix the design, not the name. |
+| 10 | **File sprawl** — the diff pushes a file past a healthy size boundary (~1k lines) | Should this be decomposed *before* adding to it? | Split by concept first; waive only with a compelling structural reason. |
+| 11 | **Needless sequencing / non-atomic update** — independent work serialized, related updates that can leave state half-applied | Is this actually dependent? Can it be observed half-done? | Parallelize independent work; group related updates. Not micro-optimization — brittleness. |
+| 12 | **Short-horizon change** — "temporary", TODO-later, quick patch, deferred cleanup, a shape chosen because it is the smallest diff | What does this look like when its reason is gone? What does removing it cost? | Do the durable fix now, or structure the stopgap so removal is a pure deletion (one branch, one file), never a refactor of live callers. |
 
 Short-horizon change is the long-term rule and it applies to every other smell: prefer
 consolidating now over a third copy later; prefer the simplification that
@@ -88,9 +98,11 @@ Write the review in this shape:
 
 Working code is not the bar. `REQUEST CHANGES` when any of Duplicated
 concept, Complexity rearranged, Special case in a shared flow, Wrong layer,
-Indirection without clarity, Weak contract, or Short-horizon change is present
-and unjustified, or when a visible code-judo move was skipped. File sprawl and
-Needless sequencing block when the cleaner structure is obvious.
+Change doesn't follow module lines, Indirection without clarity, Refused
+inheritance, Weak contract, or Short-horizon change is present and
+unjustified, when a documented repo rule is broken, or when a visible
+code-judo move was skipped. Mysterious name, File sprawl and Needless
+sequencing block when the cleaner structure is obvious.
 
 ## Author pushback
 
@@ -102,6 +114,9 @@ Needless sequencing block when the cleaner structure is obvious.
 | "The existing code already does it this way" | Existing mess licenses fixing the concept, not adding a copy of it. |
 | "A restructure is out of scope" | If the restructure deletes the complexity this change adds, it is the scope. |
 
+The Fowler smell list is an idea from mattpocock/skills `code-review`; the
+wording here is ours.
+
 ## Review Tone
 
 Be direct, serious, and demanding about quality.

package/skills/review-diff/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: review-diff
+description: >-
+  Review a branch before merge: first a gate (the repo's check command plus
+  crap-gate), then three independent reviewers in parallel — spec (did we build
+  what was asked, no more, no less), correctness via Codex (races, idempotency,
+  money, time, authz, indexes, N+1, migrations, error paths, test quality) and
+  structure (deep-quality-review). `--quick` runs only spec and correctness,
+  shortened, for a live interview. Use when the user says "/review-diff",
+  "review this branch", "review this slice", "review before merge", or before
+  closing out a spec task.
+---
+
+# /review-diff
+
+One gate, then three reviewers that never see each other's output. Each
+answers one question; their reports stay separate, because a strong answer
+on one axis must not hide a failure on another.
+
+| Reviewer | Question | Runs as |
+|---|---|---|
+| Spec | Did we build what the spec asked, no more, no less? | subagent, `spec.md` |
+| Correctness | Can this lose money or corrupt data? | `codex exec`, `correctness.md` |
+| Structure | Is the code getting messier? | subagent, `deep-quality-review` |
+
+`spec.md` and `correctness.md` sit next to this file (`<skill-dir>`).
+
+## Arguments
+
+- A range (`A..B`) or a base ref. Default: the merge-base with the repo's
+  default branch (`origin/main`, else `main`). Review `git diff <base>...HEAD`.
+- A spec path, optional.
+- `--quick`: interview mode. Gate, then spec + correctness only; each report
+  keeps its top 3 findings in under 150 words. Default: all three, full
+  reports.
+
+Before anything else, confirm the range resolves and the diff is non-empty. A
+bad ref fails here, not inside three reviewers.
+
+## Step 0 — gate (sequential, a precondition, not a reviewer)
+
+1. Run the repo's check command: `make check` if the Makefile has it,
+   otherwise the one AGENTS.md / CONTRIBUTING.md / package.json documents. None
+   documented → say so and continue.
+2. Run crap-gate if the repo has `.crap-gate.json`: prefer its wrapper
+   (`make crap-gate` / `make crap`), else `sh <crap-gate-dir>/run.sh`, where
+   the dir is the first of `.my-skills/crap-gate`, `.agents/skills/crap-gate`,
+   `.claude/skills/crap-gate`, `~/.my-skills/crap-gate` that exists. No
+   config → "crap-gate: not configured, skipped". Config but skill missing →
+   "crap-gate: skill not installed, skipped".
+
+Either red → **stop**. Report the failing command and the first failures, and
+no review: reviewing red code wastes the reviewers, and "is there a test for
+this scenario" means nothing while tests fail.
+
+## Steps 1–3 — reviewers, in parallel
+
+Launch all of them in one go; don't let one wait for another. Give each only
+the range, the commit list (`git log --oneline <range>`) and its brief. Never
+paste one reviewer's output into another's prompt.
+
+- **Spec.** Find the spec: the path argument, then a spec under `specs/`
+  matching the branch or feature (skip templates), then issue refs in the
+  commits (`#123`, fetched with `gh issue view`). None → skip: "Spec: no spec
+  found, skipped". Otherwise spawn a subagent: "Read and follow
+  `<skill-dir>/spec.md`. Range: <range>. Commits: <list>. Spec: <path or fetched text>."
+- **Correctness.** If `codex` is on PATH, run it (in the background while
+  the others run):
+
+  ```bash
+  out=$(mktemp) && codex exec -s read-only --ephemeral -o "$out" \
+    "Read and follow <skill-dir>/correctness.md. Range: <range>. Commits: <list>.<quick>" \
+    >/dev/null 2>&1; cat "$out"
+  ```
+
+  No Codex → spawn a subagent with the same instruction and note "Correctness:
+  Codex unavailable, ran on <current model>". The second model is the point;
+  never drop the note.
+- **Structure** (skipped in `--quick`). Spawn a subagent: "Use the
+  `deep-quality-review` skill on range <range>." Skill not installed → skip:
+  "Structure: deep-quality-review not installed, skipped".
+
+In `--quick`, append to each brief: "Quick mode: top 3 findings, under 150
+words." No subagents in this harness → run them one after another, each in a
+fresh context if you can, and say so.
+
+## Output
+
+```
+Gate: `make check` green · crap-gate green
+
+## Spec
+<report, verbatim or lightly cleaned>
+
+## Correctness (Codex)
+<report>
+
+## Structure
+<report>
+
+Spec: 3 findings — worst: <one line>
+Correctness: 1 finding — worst: <one line>
+Structure: REQUEST CHANGES, 2 findings — worst: <one line>
+```
+
+A skipped step keeps its place with its one-line note (in the gate line, or
+as the section body and summary line). `--quick` has no Structure section and
+no Structure summary line. A clean reviewer's summary line is `0 findings`.
+
+Do not merge, dedupe or re-rank findings across reviewers, and do not pick an
+overall winner. A finding two reviewers both raise stays in both reports; that
+is signal.
+
+## Dependencies
+
+Needs the `deep-quality-review` and `crap-gate` skills (install them with the
+skills CLI next to this one) and, for the second model, the `codex` CLI. Any
+of them missing skips that step with a one-line note; it never fails the
+review.
+
+The spec axis is an idea from mattpocock/skills `code-review`; the wording
+here is ours.

package/skills/review-diff/correctness.md

@@ -0,0 +1,29 @@
+# Correctness reviewer
+
+You check one thing: **can this diff lose money, corrupt data, or let the
+wrong person act?** Not style, not structure, not spec coverage. Assume lint,
+types and tests already pass.
+
+Read `git diff <range>` in full, then only the surrounding code a check needs
+(the model behind a query, the existing indexes, the caller of a handler).
+
+| Check | Flag |
+|---|---|
+| Concurrency | Read-then-write without a lock, conditional `UPDATE … WHERE`, or DB constraint: overselling, double-spend, lost updates. Transactions that commit half the work. |
+| Idempotency | Webhooks, payment callbacks, retries and queue consumers that do the work twice when the same message arrives twice. |
+| Money | Floats for amounts (use integer cents or decimal), rounding in more than one place, currency dropped. |
+| Time | Naive datetimes, local time stored, "today" computed without the business timezone. Store UTC. |
+| Authorization | A check done only in the client, or missing on the server: can user A read or change user B's rows by changing an id? |
+| Foreign keys | A new FK column that is filtered or joined on without an index. |
+| N+1 | One query per loop iteration where a join or `IN (…)` would do. |
+| Migrations | Not reversible, or unsafe on a live table (a NOT NULL column without a default, a rewrite under lock). |
+| Failure paths | A payment-provider, checkout or stock-decrement call whose failure (timeout, decline, provider error) is unhandled or silently swallowed. |
+| Test quality | Tautological tests (asserting a mock's return value, or a value the test just set with no code in between) and tests on internals instead of the public seam. Say what they should assert. |
+
+Every finding: `file:line`, the concrete failure scenario (inputs or
+interleaving → wrong result), and the fix. "Consider reviewing" is not a
+finding. Report only what you can point at; mark anything unconfirmed
+"(unverified)".
+
+Output: findings, worst first, then one line naming the checks with nothing
+to report ("Clean: money, time, …"). Under 400 words.

package/skills/review-diff/spec.md

@@ -0,0 +1,24 @@
+# Spec reviewer
+
+You check one thing: **did this diff build what the spec asked, no more, no
+less?** Not style, not structure, not bugs outside the spec.
+
+1. Read the spec in full, then `git diff <range>` in full (not a summary),
+   then the tests the diff adds or touches.
+2. Walk the spec requirement by requirement and report:
+   - **Missing / partial**: asked for, not built or only half built.
+   - **Scope creep**: built, not asked for (endpoints, flags, fields, UI,
+     options). Say what to delete.
+   - **Built wrong**: looks implemented, but behaves differently from the
+     spec line.
+   - **Untested scenario**: each Given/When/Then scenario with no test that
+     exercises it through the public seam (the API, the UI, the use case), not
+     through an internal helper. A test that only passes because a layer
+     above the one the scenario names stops the input (e.g. API validation
+     hiding an untested DB constraint) does not count.
+3. Every finding quotes the spec line it rests on, then `file:line` and the
+   concrete fix. No spec line → not a finding.
+
+Output: findings grouped under those four headings. Leave out empty groups
+and end with one line naming them ("Clean: scope creep, built wrong"). Don't
+list what was fine. Under 400 words.

package/skills-manifest.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "generatedAt": "2026-09-13T13:58:48.949Z",
+  "generatedAt": "2026-09-23T16:36:43.907Z",
   "skills": [
     {
       "name": "backlog",
@@ -28,8 +28,8 @@
     },
     {
       "name": "deep-quality-review",
-      "version": "0.1.1",
-      "hash": "sha256-da5ce29dc5349bcbed74589f3475fa12907ae7eed385e4ecc680bf67edae7e43",
+      "version": "0.1.2",
+      "hash": "sha256-134c1a194e9ec53f244e6500e68cf963b384759d8b5f5c934784665b6ef4b8f6",
       "description": "Extremely strict maintainability review of a branch's changes: duplicated concepts, complexity that got rearranged instead of deleted, spaghetti branching, boundary leaks, weak type contracts, file sprawl, and \"temporary\" fixes that will outlive their reason. Use when the user asks for a \"deep code quality review\", \"thermonuclear review\", \"harsh maintainability review\", \"code judo\", \"is this making the codebase messier\", or before merging a change that touches shared code. Not a correctness, security, or test-coverage review."
     },
     {
@@ -56,6 +56,12 @@
       "hash": "sha256-211e0e116ff6efbc4589ea7264835855b9495ba535f242733af913903fe7707d",
       "description": "Build a throwaway prototype to answer a design question, delivered as one self-contained HTML file. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like."
     },
+    {
+      "name": "review-diff",
+      "version": "0.1.0",
+      "hash": "sha256-f1efdffdad0abf536777a3afcc733b2612ed51abad0b1a04d24f280bf2f223d3",
+      "description": "Review a branch before merge: first a gate (the repo's check command plus crap-gate), then three independent reviewers in parallel — spec (did we build what was asked, no more, no less), correctness via Codex (races, idempotency, money, time, authz, indexes, N+1, migrations, error paths, test quality) and structure (deep-quality-review). `--quick` runs only spec and correctness, shortened, for a live interview. Use when the user says \"/review-diff\", \"review this branch\", \"review this slice\", \"review before merge\", or before closing out a spec task."
+    },
     {
       "name": "to-spec",
       "version": "0.1.0",