code-simplifier

Codex compatibility note:

• Invoke $skill-name: load the registered .agents/skills/<name>/SKILL.md and execute it with Codex tools; no separate Skill tool or Claude mode switch is needed. Author .claude/**; mirrors are generated.
• Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
• Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
• Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required spawn_agent subagent(s) for that task.
• Preserve protocol order unless the user approves a deviation. Workflows use $start-workflow: gates stay fixed; other steps may flex with logged reasons and evidence.

[BLOCKING] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. Inside a workflow run, $start-workflow → Workflow-step mode bounds this rule. [BLOCKING] Before each step or sub-skill call, update todo tracking: set in_progress when step starts, set completed when step ends. [BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason. [BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.

Quick Summary

Goal: Lower the cost of the next change — cut coupling, hidden state, duplicated knowledge, unclear intent — by simplifying and refining code for clarity, consistency, and maintainability without altering any observable behavior. — why: every simplification serves future change cost, not aesthetics.

Summary: (read-this-if-nothing-else digest — purpose + every main step)

• Purpose — skeptical-first MUTATOR, not a suggester: grep all usages + trace consumers (grep/read; an optional graph downstream trace may hint at more) and cite file:line BEFORE touching anything; apply a simplification ONLY when certain it preserves behavior, never when unsure. — why: an unverified "safe" rewrite silently breaks a downstream consumer.
• Main steps, run in order: (1) Phase 0 Detect target + scope from project config/source; (2) Identify Targets — recent git changes or named files, HARD-SKIP generated/migration/vendor; (3) Analyze via the 5 Simplification Dimensions, marking inapplicable ones N/A with a reason; (4) Apply one refactoring type at a time (KISS/DRY/YAGNI, behavior-preserving); (5) Verify related tests after EACH change; (6) Self-Recursive Loop (analyze→simplify→verify) until the current round's exit bar is clear (round 1: zero open findings; round 2: zero CRITICAL/HIGH/MEDIUM, LOW deferred) or a no-progress/unsafe/owner-decision stop hits — do NOT spawn a fresh-context reviewer for your own findings; (7) Self-Review Gate.
• The 5 Simplification Dimensions (step 3): readability · DRY/abstraction (compare real repetition; apply YAGNI) · responsibility based on the project's documented architecture and evidenced ownership · complexity reduction · persistence/query bounds on applicable changed paths only (otherwise N/A) — every technique answers ONE test: does this make the next change cheaper?
• Self-Review Gate (step 7) — this skill owns review of its own output: when it changed any file, self-invoke $code-quality-review scoped to ONLY those changed files (recursion-safe leaf — NEVER $changes-review); skip + log the reason when nothing changed. Only an explicit --defer=review from a caller that runs a FULL review of the settled state afterwards skips it (see .claude/skills/workflow-review-changes/references/caller-mode.md); no flag means the gate runs. — why: the simplifier rewrites code after the main review batch, so its output ships unreviewed without this gate.
• --report-only: read-only mode for a caller that owns every fix (e.g. a review skill's simplification dimension or a workflow review barrier) — steps 1–3 only, each finding with file:line + proposed change + behavior-preservation note, no edit of any file, no nested sub-agent, no user question, only the report written; see Report-Only Mode.
• Read FIRST: code-review-rules.md (anti-patterns/checklists) then project-structure-reference.md, both under the reference-docs root (default docs/project-reference; docsRoots.projectReference.path in docs/project-config.json overrides) — before any modification.