| name | simplify |
| version | 1 |
| owner | compass-maintainers |
| last_verified | 2026-08-25T00:00:00.000Z |
| description | Reviews changed Compass code for duplication, unnecessary complexity, weak boundaries, and overused React state/effects, then applies behavior-preserving improvements using repo conventions. Use when asked to simplify, clean up, make DRY, reduce complexity, or improve maintainability, and during the simplification gate in /ship. |
When
Asked to simplify, clean up, make DRY, or during /ship simplify gate.
Steps
High-value detectors, then Compass conventions, then Verify.
Output
Behavior-preserving diff; separate commit when files change.
Pass
No behavior change; conventions from AGENTS.md kept.
Anti-patterns
Do not “improve” by rewriting unrelated files. See
_evals/anti-patterns.md.
Escalate
A simplification that would change public behavior or contracts.
Simplify Compass code
Favor the smallest, clearest implementation. This is a quality pass, not a
correctness or security review. /ship invokes this skill rather than
inlining these detectors.
Scope
- Default to the complete branch diff against its base. Honor a narrower file
or feature scope when the user names one.
- Preserve behavior. Do not expand into unrelated cleanup.
- Find existing abstractions before creating new ones.
- If an inspected pattern should stay, state why.
High-value detectors
Inspect in this order:
- Largest churn — start where the diff added the most code and branches.
- Repeated scaffolding — extract one helper only when the shared intent and
parameter surface are clear.
- Test-only production hooks — prefer narrow dependency injection over
registries or environment branches added only for tests.
- Casts and broad mocks — reshape the seam instead of hiding type or
process-global coupling.
- Dead exports and unreachable guards — verify call sites and invariants,
then delete misleading code.
- Hidden shared state — fix ownership/reset/injection rather than test
ordering or timeouts.
- Comments explaining mechanics — simplify the mechanism; retain comments
that document constraints the code cannot express.
Do not unify code that only looks similar or break a repo-wide convention in
one file merely to remove repetition.
Principles
Minimal surface
- Add only what the current requirement needs.
- Prefer direct, boring code over generic machinery.
- Delete indirection that does not clarify ownership or contracts.
- Keep one responsibility per function and React component.
- Use guard clauses over nested conditionals.
Extract versus inline
Extract when logic is used in multiple places, has shared intent, and admits a
narrow stable API. Inline when it is used once or extraction needs vague names,
optional parameters, or special cases.
React state and effects
Challenge every added useEffect, useRef, and useState:
- Derive values during render when possible.
- Let Zustand own shared transient state and TanStack Query own server state.
- Prefer an event handler or existing browser API over lifecycle
synchronization.
- Move or split the ownership boundary when local hook coordination is the
real complexity.
Keep hooks that genuinely synchronize with non-React systems, hold imperative
DOM handles, or own isolated UI state. Record why they remain.
Compass conventions
- Use package aliases and concrete source imports; do not add barrels.
- Put shared web/backend Zod contracts in
packages/core.
- Keep React components in their own files.
- Preserve semantic web test queries and
user-event.
- Use Tailwind semantic colors and canonical scale utilities.
- Prefer existing package locations:
- shared logic:
packages/core/src/util or validators
- web helpers:
packages/web/src/common
- backend helpers:
packages/backend/src/common
- sync ownership:
packages/sync/src
Read the applicable .cursor/rules and linked docs before changing package or
test architecture.
Verify
Run the smallest checks that cover touched behavior:
packages/core → bun run test:corepackages/web → bun run test:webpackages/backend → bun run test:backendpackages/sync → bun run test:syncpackages/scripts → bun run test:scripts- shared contracts → affected package tests plus
bun run type-check
Use /verify-change for a diff-derived selection. Run bun run lint for
non-docs changes.
Commit and report
When /simplify was explicitly invoked to change code, commit the
simplification separately from implementation after verification, using a
lower-case conventional message such as:
refactor(web): simplify event form state
Never amend implementation or push from this skill. If nothing changed, do not
create an empty commit.
Report:
- the behavior-preserving simplification
- principles applied and tradeoffs
- checks run
- React hook count direction and justification for retained hooks
- commit hash/message, or that no commit was needed
