simplify
Reduce complexity in recently changed code — cut needless abstraction, dead code, and duplication; improve names and structure — WITHOUT changing behavior. Quality only; it does not hunt for bugs (use review for that). Use after implementing a chunk of work, before review, or whenever a diff feels more complicated than the problem it solves. Triggers on "clean this up" / "tidy this" / "refactor this" when code already exists; for an underspecified goal with no code yet, use `clarify`.
- License 许可
- MIT
- 最近更新
- 2026-11-06
- Stars
- ★ 44
- Forks
- 4
01 前言 Front Matter
- name
- simplify
- description
- Reduce complexity in recently changed code — cut needless abstraction, dead code, and duplication; improve names and structure — WITHOUT changing behavior. Quality only; it does not hunt for bugs (use review for that). Use after implementing a chunk of work, before review, or whenever a diff feels more complicated than the problem it solves. Triggers on "clean this up" / "tidy this" / "refactor this" when code already exists; for an underspecified goal with no code yet, use `clarify`.
03 SKILL.md 正文
Simplify
Make a change simpler and clearer without changing what it does. The bar: readable, explicit code over
clever, compact code — would a senior engineer call this overcomplicated? Scope is the recently
changed code — the working diff (e.g. git diff against the branch point) unless the caller names
files. This is quality-only: it does not hunt for bugs (that's review).
Step 0 — the invariant
Preserve functionality. Never change what the code does, only how it does it. Every original
feature, output, and behavior stays intact. If a simplification would alter behavior, it is a review
or implementation concern, not a simplification — stop and surface it.
Scan — three buckets
Look at the changed code for:
- Structural — nesting depth ≥ 3, functions longer than ~50 lines, nested ternaries, boolean-flag parameters that select behavior, indirection that only forwards a call.
- Naming —
data/result/temp/foo, names that mislead, names that imply something broader or different than the thing actually is. - Redundancy — duplicated logic, dead/unreachable code, unused parameters/variables/fields, over-abstraction (a helper, wrapper, or interface used in exactly one place), defensive code for states an upstream invariant already makes impossible.
The deletion test
For each abstraction or layer of indirection, ask: would removing it concentrate complexity (then keep it — it's earning its keep) or merely relocate it (then remove it — it's not)? A single-use helper usually relocates; inline it. A wrapper that hides a genuinely complex subsystem behind a small interface usually concentrates; keep it.
Two-sided guardrail
Simplifying is a balance, not a race to fewer lines. Pair every "look for" with a "don't":
| Look for | Don't |
|---|---|
| reduce nesting and indirection | introduce a nested ternary or a dense one-liner |
| inline a single-use helper | inline a helper that names a genuinely complex step |
| remove a redundant abstraction | remove a helpful abstraction that organizes the code |
| consolidate duplicated logic | merge unrelated concerns into one function |
| clearer names, fewer obvious comments | make the code harder to debug or extend |
If the "simplified" version is longer or harder to follow, it isn't a simplification — revert it.
Report mode
When the caller asks for report mode (for example review-pr, reviewing someone else's pull
request), do not edit anything. Run the scan, the deletion test, and the guardrail below against the
caller's diff, then return each candidate as a finding: file:line, the bucket (structural, naming,
or redundancy), what to change, and why it is clearer. Mark every finding Suggestion unless the
complexity hides a real defect. Skip the Process steps, which only apply when you own the code.
Process
- Establish a baseline. Run the tests covering the change — or, if there is no suite or it cannot run, the narrowest available behavior check (build, typecheck, or lint) — and confirm it is green before you start. Never fabricate a green result; if the baseline is already red for unrelated reasons, note that and rely on the narrower check.
- Understand before changing (Chesterton's Fence). Work out why the code is shaped the way it
is — a guard, retry, or special case may exist for a real reason. Remove a guard only when its
premise is verifiable in the code you can see; if confirming it needs reasoning about whether an
upstream invariant truly holds, leave it and flag for
review. - One simplification at a time → re-run that check → keep it only if it stays green; revert immediately if not. Tests are necessary but not sufficient: for a change on a path the suite does not exercise, reason explicitly about input/output equivalence — error paths, ordering, side effects, short-circuit evaluation — before keeping it.
- Tests are out of scope. Never edit a test to make it pass — a breaking test means behavior changed, so revert the simplification, not the test. Do not refactor, consolidate, or delete tests or fixtures even when they look redundant; that silently weakens coverage.
- Keep the simplify diff separate from feature/fix changes, so a reviewer reads pure refactor.
- Verify functionality preserved at the end: the baseline check is green and you have reasoned about any untested paths you touched.
Red flags
- The simplified code is longer, or harder to follow, than before.
- Editing, consolidating, or deleting a test or fixture (tests are out of scope).
- Calling behavior "unchanged" from a passing suite alone, on code the suite does not exercise.
- Removing an abstraction or guard without applying the deletion test / Chesterton's Fence.
- Touching code outside the working diff ("while I'm here…").
- Optimizing for fewer lines at the cost of clarity.
Verification checklist
- [ ] The baseline check (tests for the changed code, or build/typecheck/lint) is green before and after — never a fabricated green.
- [ ] For any change on a path the suite does not cover, I reasoned about input/output equivalence, not just "tests pass".
- [ ] No test or fixture was edited, consolidated, or deleted — tests stayed out of scope.
- [ ] Every removed abstraction/guard passed the deletion test (and Chesterton's Fence for guards).
- [ ] The change stayed within the working diff.
- [ ] The diff is genuinely clearer — not merely shorter.
04 同仓库更多 Skills
write-like-me
Write or edit prose in author's voice, or check that a draft sounds like them. Use for blog posts, design and strategy docs, PR descriptions, commits and review comments, chat / agent instructions, peer feedback, or any first-person writing on their behalf, and whenever an agent is producing text that will go out under their name and needs to sound like them, not like a generated reply.
validate
Verify a change is ready to ship by checking it against its acceptance criteria and running the repo's own quality gates in order, then report a pass/fail verdict with the exact failures. Use to decide go/no-go right before shipping — when you want a pass/fail verdict against acceptance criteria and the repo's quality gates (lint/build/test), not a code critique (use `review` for that). It reports — it does not fix (route failures to `pr-fix`/`implement`) and does not ship.
todo
Capture, list, and complete repo-scoped todos
tl
Manage a Relay program as the CEO-facing tech lead: shape goals and contracts, prioritize dependency-aware work, dispatch senior worker agents, and surface every decision without writing production code or merging.
stack-ship
Use only for a standalone stack explicitly launched with `relay --workflow stack-ship`; never invoke inside a tech-lead-managed Relay program. Decompose one goal into small PRs, delegate build and monitor work, surface author decisions, and auto-merge only after human approval.
review
Review a change for correctness, quality, and guideline compliance using a library of specialized reviewer roles. Use before opening a PR, after finishing a chunk of work, or to review an existing PR. Two output modes — a local severity-ranked report for a fix loop (default), or inline GitHub comments (--comment). Scores every finding for confidence, filters the noise, and delegates each role adversarially.