Simplify

Post-implementation quality review focused on simplicity, reuse, and clarity — then fix what the user approves. The counterpart to gap-check: gap-check finds missing things, simplify finds too much stuff.

When to Use

• Right after implementing a feature, to prune over-engineering before it calcifies
• User says "simplify", "clean up", "make this shorter", "too complex", "is there a simpler way"
• User asks "DRY this", "any duplication?", "any dead abstractions?"
• User pastes a code snippet and asks for a leaner version
• After gap-check flags simplification-shaped findings (unused abstractions, duplicate logic)

Do not use this skill to:

• Add features (that's implementation)
• Fix bugs (that's gap-check → fix)
• Rename for style preferences without a clear benefit

Preflight — classify the review target

The 11 find-categories below are weighted toward TypeScript/JavaScript/Python application code. On docs, skills, markdown, or shell scripts, rebalance toward the "Cross-file divergence" and "Over-engineering" categories, and de-emphasize the code-only ones (state sprawl, premature error handling, test cruft).

Target types:

• Code repo / app feature — default. Use all 11 categories.
• Docs / skills / markdown — Cross-file divergence is usually the dominant finding. Taxonomy categories 3, 4, 7, 8 still apply (YAGNI, clever, comment rot, import/link surface).
• Shell / infra / tooling — focus on categories 2 (dead abstractions), 3 (YAGNI), 4 (clever), 7 (comment rot). Bash scripts over-engineer quickly.
• Mixed — surface per-file which category applies.

State the target type as the first line of your output.

Steps

Phase 1 — Find

Identify the change surface — the files touched in the current session, or what the user asked to review. Then check each for:

1. Duplication (DRY). Near-identical blocks across files, or within a file. Three similar lines is a yellow flag, three near-identical blocks is a red flag. Do not extract a helper after only two similar lines — that's premature abstraction. Look for copy-paste patterns across routes, components, handlers.
2. Dead abstractions. Helper functions called from exactly one place. Config objects with one key. Wrapper components that add nothing. Strategy patterns with one strategy. If it's invoked once, inline it.
3. Over-engineering (YAGNI). Features not in the current spec: retry loops, caching layers, generic type parameters, plugin systems, config for things that never change. Hypothetical future flexibility that's not paying rent.
4. Unclear / clever code. Chained ternaries. Nested destructuring beyond two levels. Single-letter variable names outside tight loops. Regex without a comment explaining intent. One-liner that would read better as four lines.
5. State sprawl. Component state that could be derived. useEffect setting a state that's a pure function of other state. Redux/Zustand for component-local data. Context providers wrapping the whole app for one deep-tree consumer.
6. Premature error handling. try/catch that rethrows unchanged. Validation for conditions that can't happen (framework guarantees them). Null checks for values the type system already proves non-null. Fallbacks for cases that would be better as crashes during development.
7. Comment rot. Comments that repeat what the code says. Comments describing the current fix or author ("added for bug #123" — belongs in git history). Stale comments that no longer match the code. JSDoc on self-explanatory functions.
8. Import surface. Unused imports. Importing the whole library (import _ from 'lodash') when one function is used. Circular imports. Re-exports with no renaming or aggregation value.
9. Test cruft. Tests that duplicate what another test covers. Tests testing the framework instead of your code. Tests that snapshot entire rendered DOMs. beforeEach setup code longer than the tests.
10. Config duplication. Same constant inlined in three files instead of one source of truth. Env var names hardcoded instead of a typed config module.
11. Cross-file divergence / prose duplication. Sibling files that repeat the same rule, diagram, worked example, or invariant — and drift out of sync. Common in docs repos, skill collections, and monorepo shared types. This is the dominant simplification target when reviewing prose-heavy repos. Examples:
    • A pipeline diagram repeated in 5 SKILL.md files when one README section would do
    • The same "do not fix during review" rule worded differently in 4 skills
    • Sibling docs describing the same concept in different vocabulary (one says "component", another says "widget")
    • Worked examples sharing the same fictional scenario without a shared source When flagged: suggest consolidating to a single source (usually a README section) with backrefs — but only if the downstream files remain readable standalone. Standalone readability of a SKILL.md outweighs minor prose duplication; use judgment.

Phase 2 — Present findings

List every finding, numbered, with:

• File path + line range (use path:line-line format)
• Category (one of the 10 above)
• What's there now (short code quote, ≤5 lines)
• Proposed change (what it would become, ≤5 lines)
• Savings (lines removed, concepts collapsed, indirection removed)
• Risk (none / low / medium — does this change runtime behavior?)

Group findings by category. Within each category, order by impact (biggest savings first).

End the findings with:

• Summary: N lines removed, M abstractions inlined, K comments deleted
• Recommendation: which findings to apply (default: all the "no risk" ones)

Phase 3 — Ask before implementing

Output the findings and stop. Ask the user which to apply. Do not touch code in Phase 2.

Offer three modes for Phase 4:

• (A) Apply all findings — when the user trusts the review
• (B) Apply only no-risk findings — inlines, dead-code removal, comment deletion
• (C) Apply a specific list — user names the numbers

Phase 4 — Implement

For each approved finding:

1. Make the edit
2. Run type-check / lint if available for the project (tsc --noEmit, ruff, cargo check, etc.)
3. Run tests if available and relevant
4. Note any finding that couldn't be applied cleanly, with a reason

Never proceed to the next finding if the current one broke the build.

Phase 5 — Verify + report

After all approved changes:

• Re-run type-check and tests
• Output a final diff summary: files touched, net lines removed, categories addressed
• If anything is left flagged from the original review (e.g., medium-risk finding the user deferred), list it as "parked for later"

Output Format (Phase 2 report)

# Simplify Review — {{scope}}

## Findings

### Duplication (DRY)
1. `src/lib/api/users.ts:12-24` + `src/lib/api/orgs.ts:15-28`
   - **Now:** two 12-line functions differing only in the collection name
   - **Proposed:** single `fetchById(collection, id)` helper
   - **Savings:** 11 lines, 1 abstraction unified
   - **Risk:** none — both sites have identical error handling

### Dead abstractions
2. `src/utils/format.ts:8-14` — `wrapInBraces(s)` is a 2-line helper called from exactly one place (`src/components/Debug.tsx:42`). Inline it.
   - **Savings:** 6 lines
   - **Risk:** none

### Over-engineering (YAGNI)
3. `src/api/events/route.ts:30-48` — retry loop with exponential backoff on an internal DB call that can't fail transiently. Spec doesn't require it.
   - **Proposed:** remove the loop, let failures propagate
   - **Savings:** 18 lines, 1 dependency (`p-retry`) potentially removable
   - **Risk:** low — failures now become 500s instead of silent retries

### Unclear / clever code
4. `src/pages/dashboard.tsx:88` — nested ternary assigning `variant`. 4 levels deep, reads right-to-left.
   - **Proposed:** `if`/`else if` ladder assigning a local const
   - **Savings:** 0 lines, +3 readability points
   - **Risk:** none

## Summary
- Findings: 4 (3 no-risk, 1 low-risk)
- Potential savings: 35 lines, 2 abstractions inlined, 1 dep removable
- Recommendation: apply all 4 — 1–3 are pure wins, 4 is a readability improvement

Rules

1. Don't fix during review. Phase 2 is find-only. Ask before Phase 4. Users need the list before the edits — otherwise they can't calibrate trust.
2. Three is the DRY threshold. Two similar blocks stay. Three or more suggests extraction — but only if the pieces are genuinely the same logic, not just the same shape.
3. Inlining beats extracting when something is called once. Indirection is a tax; one-call sites don't earn it.
4. Don't recommend removing validation at system boundaries. User input, external API responses, filesystem paths — these are load-bearing. Trust internal code and framework guarantees, not user input.
5. Don't rename for taste. user to usr or result to r is not a simplification; it's a style preference and costs readability.
6. Flag — don't fix — format-only changes. If prettier/eslint would disagree with the code, note it but don't reformat in this skill. That's a linter's job.
7. Preserve git blame when splitting files. If a simplification involves moving code to a new file, note this creates blame churn — worth the user's awareness.
8. Respect the session's scope by default — session-touched files or what the user explicitly names. If the user explicitly asks to review a whole repo/directory, expand scope to the named target only. Never grep the whole codebase unprompted.
9. Measure savings, not lines alone. "Removing 3 lines by adding a 6-line abstraction" is a net loss. Always count the full delta.
10. When in doubt, flag and ask. A finding marked "needs judgment" with a clear tradeoff is more useful than a confident wrong call.
11. In subagent / headless mode, emit the Phase 2 report and stop. Do not prompt for approval — the calling agent handles Phase 3–5. Findings should still be complete and ready to apply.
12. Prose duplication across standalone files is often fine. Category 11 is a finding, not a mandate — a SKILL.md that works offline beats a modularized one that requires the reader to jump to a README. Flag divergence, not mere repetition.

Pipeline position

This skill is the middle step of the review team pipeline:

write-plan → plan-review → (implement) → gap-check → simplify → pre-ship → (deploy)

• gap-check finds missing things (bugs, unhandled paths, dead imports)
• simplify finds excess things (duplication, over-engineering, cleverness)
• pre-ship verifies the whole thing is production-ready

Run gap-check first (what's missing), then simplify (what's excess), then pre-ship (is it safe to deploy). Running simplify before gap-check risks simplifying away code that gap-check would have flagged as incomplete.