Skip to content

Commit e177ff8

Browse files
committed
feat: add maintenance routine skills (dup-unifier, dead-code-remover, abstraction-police)
1 parent 0306388 commit e177ff8

3 files changed

Lines changed: 224 additions & 0 deletions

File tree

‎skills/abstraction-police/SKILL.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
---
2+
name: abstraction-police
3+
allowed-tools: Read, Bash, Edit, Write, Grep, Glob
4+
description: Find leaky abstractions - internals escaping through interfaces, callers reaching around APIs, boundaries that force callers to know implementation details - and fix one leak per PR. Narrow mechanical maintenance routine intended to run on a schedule.
5+
---
6+
7+
# /abstraction-police - Fix leaky abstractions
8+
9+
A leak is when a caller must know how something works to use it. Find leaks,
10+
fix the boundary, one leak per PR.
11+
12+
## Leak patterns to scan for
13+
14+
- **Reach-around**: callers importing from `foo/internal/*`, `foo/lib/*`, or
15+
deep paths when `foo` has an index/public surface.
16+
`rg "from ['\"].*/(internal|lib|dist)/" --type ts`
17+
- **Type leakage**: public function signatures exposing internal types (ORM
18+
entities, raw API response shapes, third-party client types) instead of
19+
domain types.
20+
- **Config leakage**: callers passing implementation-specific options through
21+
a supposedly generic interface (`{ redisTtl }` on a generic cache).
22+
- **Error leakage**: raw driver/library errors crossing a boundary uncaught,
23+
forcing callers to catch `PrismaClientKnownRequestError` and friends.
24+
- **Sibling knowledge**: module A grepping/parsing module B's files, env
25+
vars, or storage format instead of calling B.
26+
- **Boolean/mode flags** that make one function behave as two
27+
(`doThing(x, true, false)`), forcing callers to know internal branches.
28+
29+
Rank by blast radius: leaks on boundaries with the most callers first.
30+
31+
## Fix
32+
33+
For the top leak:
34+
35+
1. Define the honest interface: what callers actually need, in domain terms.
36+
2. Fix the boundary - wrap the internal type, translate the error, narrow
37+
the config, export the missing public function.
38+
3. Migrate every call site. A fix that leaves both the leak and the new path
39+
alive is worse than no fix; finish the migration or split it across
40+
sequential PRs with the leak marked deprecated in the first.
41+
4. Enforce where cheap: an eslint `no-restricted-imports` rule, an
42+
`@internal` tag, or a lint on the deep-import pattern, so the leak cannot
43+
silently return.
44+
5. Verify: typecheck, lint, tests of every touched package.
45+
46+
## Hard rules
47+
48+
- Behavior-preserving. Error translation must preserve information (cause
49+
chaining), not swallow it.
50+
- No speculative interfaces. Fix the leak that exists; do not design for
51+
hypothetical future backends.
52+
- If the "leak" is load-bearing (perf escape hatch, intentional low-level
53+
API), skip it and record it below.
54+
- Max one boundary per PR, ~300 changed lines. Large migrations become a
55+
deprecation PR followed by call-site PRs on later runs.
56+
57+
## PR conventions
58+
59+
- Branch: `chore/abstraction-<slug>`
60+
- Commit: `refactor: seal <boundary> leak (<pattern>)`
61+
- Labels: `refactor` + `agent:mechanical`
62+
- PR body: the leak pattern, list of offending call sites, the new
63+
interface, and the enforcement added.
64+
65+
## Tuning
66+
67+
This file is the routine. When a PR is rejected, record the case below and
68+
adjust the patterns or hard rules.
69+
70+
Intentional leaks (do not touch):
71+
72+
- (none yet)

‎skills/dead-code-remover/SKILL.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
---
2+
name: dead-code-remover
3+
allowed-tools: Read, Bash, Edit, Write, Grep, Glob
4+
description: Remove statically unreachable code immediately, and instrument suspected-but-unproven dead code with probe logging so a later run can confirm and remove it. Narrow mechanical maintenance routine intended to run on a schedule.
5+
---
6+
7+
# /dead-code-remover - Remove dead code, probe suspected dead code
8+
9+
Two lanes each run: (1) delete code that is provably unreachable, (2) plant
10+
probes on code that looks dead but cannot be proven dead statically, and
11+
harvest probes planted by earlier runs.
12+
13+
## Lane 1: provably dead - delete now
14+
15+
Static signals, by ecosystem:
16+
17+
```bash
18+
bunx knip # JS/TS: unused files, exports, deps
19+
cargo machete # Rust: unused deps
20+
```
21+
22+
Plus: exports with zero imports (`rg` the symbol), branches behind
23+
always-false flags, code behind removed feature flags, unreferenced assets.
24+
25+
Provable means: no dynamic dispatch, no reflection, no string-keyed lookup,
26+
not a public API of a published package, not referenced from config,
27+
templates, or CI. If any of those apply, it goes to Lane 2.
28+
29+
Delete it, then verify: build, typecheck, full test suite. One theme per PR
30+
(e.g. "remove unused exports in packages/x"), max ~400 deleted lines.
31+
32+
## Lane 2: suspected dead - probe, then harvest
33+
34+
For code that looks dead but is only provably-unused at runtime:
35+
36+
1. Plant a probe at the entry point with a greppable marker:
37+
38+
```ts
39+
// DEADCODE-PROBE 2026-08-23 remove-after 2026-08-30
40+
console.warn("[deadcode-probe] <symbol> reached");
41+
```
42+
43+
Use the codebase's existing logger if one exists. Probes ship in their own
44+
PR labeled `agent:probe`.
45+
46+
2. On every run, harvest expired probes:
47+
48+
```bash
49+
rg -n "DEADCODE-PROBE" --no-heading
50+
```
51+
52+
For each probe past its `remove-after` date, check the log store (or Sentry
53+
breadcrumbs, or grep production logs if accessible) for the probe message.
54+
55+
- Never fired: delete the probe and the code it guards, in a normal Lane 1 PR.
56+
- Fired: delete the probe only, and record the symbol under "Confirmed alive"
57+
below so no future run re-probes it.
58+
59+
## Hard rules
60+
61+
- Never delete: public API of published packages, migration code, error
62+
handlers for rare-but-real paths, platform-conditional code for platforms
63+
still supported.
64+
- Deleting a file also means deleting its tests, mocks, stories, and exports.
65+
Leftover references fail the verify step.
66+
- Probe windows are 7 days minimum. Do not remove a probe early.
67+
68+
## PR conventions
69+
70+
- Branch: `chore/dead-code-<slug>`
71+
- Commit: `chore: remove dead <thing>` / `chore: probe suspected dead <thing>`
72+
- Labels: `refactor` + `agent:mechanical` (removals), `agent:probe` (probes)
73+
- PR body: evidence per deletion (tool output or zero-reference proof; for
74+
harvested probes, the probe date range checked and where logs were checked).
75+
76+
## Tuning
77+
78+
This file is the routine. When a PR is rejected or a deletion gets reverted,
79+
add the case below and tighten the rules.
80+
81+
Confirmed alive (never re-probe):
82+
83+
- (none yet)

‎skills/dup-unifier/SKILL.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
name: dup-unifier
3+
allowed-tools: Read, Bash, Edit, Write, Grep, Glob
4+
description: Scan the codebase for similar-yet-slightly-divergent abstractions and put up small PRs that unify them. Narrow mechanical maintenance routine intended to run on a schedule.
5+
---
6+
7+
# /dup-unifier - Unify divergent duplicate abstractions
8+
9+
Find pairs or clusters of code that started as the same idea and drifted apart
10+
(copy-pasted helpers, parallel components, re-implemented utilities), then
11+
unify each cluster in its own small PR.
12+
13+
## Scan
14+
15+
Run in order, cheapest first:
16+
17+
```bash
18+
bunx jscpd --min-tokens 50 --reporters json --output .tmp/jscpd .
19+
```
20+
21+
- `jscpd` catches literal near-duplicates
22+
- `ast-grep` catches structural duplicates that differ in identifiers:
23+
scan for repeated shapes (same function skeleton, same hook pattern,
24+
same error-handling wrapper) across files
25+
- Grep for naming smells: `*Util`, `*Helper`, `format*`, `parse*`, `is*`,
26+
`get*` defined in more than one module with near-identical bodies
27+
28+
Rank candidates by: (uses x divergence risk) descending. Skip vendored code,
29+
generated files, tests that intentionally duplicate fixtures, and anything in
30+
`.gitignore`d paths.
31+
32+
## Unify
33+
34+
One cluster per PR. For the top candidate:
35+
36+
1. Pick the canonical location (most imported, or the shared package if one
37+
exists). Do not invent a new `utils/` dumping ground for a single pair.
38+
2. Merge the variants: the union of behavior only if every difference is
39+
intentional; otherwise prefer the newest/most-tested variant and note the
40+
dropped behavior in the PR body.
41+
3. Point all call sites at the canonical version. Delete the copies.
42+
4. Verify: typecheck, lint, and the test suites of every touched package.
43+
44+
## Hard rules
45+
46+
- Behavior-preserving only. If unification would change observable behavior,
47+
stop and open an issue instead of a PR.
48+
- Max ~300 changed lines per PR. Bigger clusters get split across days.
49+
- Never unify two things that merely look alike but serve different domains
50+
(false-positive duplication). When in doubt, skip and record why below.
51+
- No new abstraction layers. Unifying two functions must not produce a
52+
factory, base class, or config object.
53+
54+
## PR conventions
55+
56+
- Branch: `chore/dup-unify-<slug>`
57+
- Commit: `refactor: unify duplicated <thing> into <location>`
58+
- Label: `refactor` + `agent:mechanical`
59+
- PR body: the cluster (file:line for each copy), the chosen canonical
60+
location and why, and any dropped divergence.
61+
62+
## Tuning
63+
64+
This file is the routine. When a PR from this routine is rejected, add the
65+
reason to the list below and adjust the rules so it does not recur.
66+
67+
Known false positives (do not attempt again):
68+
69+
- (none yet)

0 commit comments

Comments
 (0)