# Simplify > Simplify and refactor code while preserving functionality and library constraints. - Skill: `del-taiseiozaki/simplify` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add del-taiseiozaki/simplify` - Raw SKILL.md: https://api.skillmd.com/api/skills/del-taiseiozaki/simplify/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: DeL-TaiseiOzaki (https://skillmd.com/u/del-taiseiozaki) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/del-taiseiozaki/simplify --- # Simplify Code Simplify and refactor $ARGUMENTS. This skill edits source code while promising not to change behaviour and not to widen its own scope. Both promises are checked rather than asserted: Step 0 records a gate baseline and the declared target set, and Step 5 compares against it. A refactor whose baseline was never recorded cannot be reported as verified. ## Declared Scope Resolve `$ARGUMENTS` into a concrete list of files and/or directories **before editing anything**, and pass each one as a `--scope` entry in Step 0. That list is the answer to "was this a refactor or a rewrite" — anything else that changes is reported as `out_of_scope_files` and fails Step 5. ## Simplification Principles 1. **Single Responsibility** - 1 function = 1 thing 2. **Short Functions** - Target under 20 lines 3. **Shallow Nesting** - Early return, depth ≤ 2 4. **Clear Naming** - Clear enough to not need comments 5. **Type Hints Required** - On all functions ## Steps ### 0. Record the Baseline (mandatory, before any edit) ```bash python3 .claude/skills/simplify/simplify_gate.py --phase before \ --scope {target file or dir} [--scope {another}] [--base main] ``` It runs `_shared/verify.sh` and `_shared/gather_diff.py` and writes `.claude/logs/simplify-baseline.json`: the gate status of every tool **as it is now**, the current HEAD, the declared scope, and any file that was already modified before you started. Without this, a gate that was red the whole time is indistinguishable from a regression this refactor introduced. Read the JSON: - `overall_before` — `pass` / `fail` / `no_gates`. On `fail`, note which tools are in the baseline as failing; Step 5 will report them as `pre_existing_failures` rather than blaming your refactor. - `pre_existing_changes[]` — dirty files you did not touch, excluded from the scope check later. - `baseline_file`, `artifacts[]`. Exit codes: `0` baseline recorded · `1` bad arguments, or `--scope` missing — without a declared target set "no scope creep" cannot be checked · `2` **no gate could run at all**, so the refactor would be unverifiable · `3` verify.sh / gather_diff.py failed, or the baseline could not be written. `--baseline PATH` moves the record elsewhere (default `.claude/logs/simplify-baseline.json`); pass the same value to both phases when two refactors are in flight. `--project-root DIR` relocates the repository root. On exit `2`, stop. Either configure the project's gates, or agree with the user on the exact commands that will verify this refactor, run them, record each command with its exit code, and re-run with `--allow-no-gates` so the payload carries `allow_no_gates: true`. Do not edit code first and decide how to verify it afterwards. ### Steps 1-4 Are Delegated Reading the target files, checking library behaviour, and applying the edits are all past the triggers in `.claude/rules/delegation.md` — an unread file, a codebase sweep, external lookup, more than ~30 lines of output. The lead keeps Step 0, Step 5, and the "is this actually simpler" judgment; everything between them is delegated, one delegation per scope entry, launched in parallel when the scopes are independent: ``` Task tool: subagent_type: "general-purpose-sonnet" # general-purpose-opus when the code carries # security, concurrency, or data-integrity risk prompt: | Objective: Simplify {scope path} without changing observable behaviour. Scope: - Edit only these paths: {the same --scope entries passed in Step 0}. - Refactor only. No new features, no API changes, no dependency changes. - Do not modify, skip, or weaken any test. Inputs: - Read .claude/rules/coding-principles.md first. - Library constraints: .claude/docs/libraries/ (check every library the target uses; WebSearch only what those notes do not answer). - Apply the Simplification Principles and the patterns in .claude/skills/simplify/SKILL.md (early return, extract function). Acceptance checks — run before returning: bash .claude/skills/_shared/verify.sh Output shape: ## Hotspots found (file:line -> problem) ## Changes applied (file:line -> what and why it reads better) ## Library constraints that shaped or blocked a change ## Anything deliberately left alone Context discipline: return the summary only; do not paste diffs or file bodies. ``` The reference material below is what the delegate follows — and what the lead applies directly when the target is a single already-open file of roughly 20 lines or fewer (Self-Handle List item 2). ### 1. Analyze Target Code - Read the file(s) to understand current structure - Identify complexity hotspots (deep nesting, long functions) - List functions/classes to simplify ### 2. Check Library Constraints - Identify libraries used in target code - Check constraints in `.claude/docs/libraries/` - Web search for unclear library behaviors ### 3. Plan Refactoring For each complexity issue: - What change to make - Why it improves readability - Verify it doesn't break library usage ### 4. Execute Refactoring Apply changes following these patterns: **Early Return:** ```python # Before def process(value): if value is not None: if value > 0: return do_something(value) return None # After def process(value): if value is None: return None if value <= 0: return None return do_something(value) ``` **Extract Function:** ```python # Before def main(): # 50 lines of mixed concerns ... # After def main(): data = load_data() result = process_data(data) save_result(result) ``` ### 5. Verify Against the Baseline ```bash python3 .claude/skills/simplify/simplify_gate.py --phase after ``` The scope and base ref are read back from the baseline, so they cannot drift between the two phases; `--scope` may be repeated here to narrow them further. It re-runs the gates, re-collects the changed files, and attributes every failure: - `regressions[]` — a gate that passed (or was skipped) before and fails now. **This is the only list your refactor is responsible for.** Fix it. - `pre_existing_failures[]` — red before, red after. Report, do not fix here. - `fixed[]` — red before, green now. - `gates` — `{tool: {before, after}}` for every gate; quote it rather than re-typing statuses, so `skipped` is never reported as `pass`. - `changed_files[]` / `in_scope_files[]` / `out_of_scope_files[]` — the diff this run produced. `out_of_scope_files` is non-empty only when a file outside `--scope` changed and was not already dirty at baseline. - `verify_log`, `diff_file` — full gate output and the full patch, for reading rather than for context. - `warnings[]` — includes "no file changed" and "HEAD moved between the two phases". Exit codes: `0` no regression and no scope creep · `1` no readable baseline (run `--phase before` first) · `2` a gate regressed, a file outside `--scope` changed, or no gate could run · `3` verify.sh / gather_diff.py failed. Then self-review `diff_file` yourself: the gate proves the tests still pass and the scope held, not that the result is *simpler*. That judgment is yours. ## Notes - Always preserve library features/constraints - Web search for unclear points - Don't change behavior (refactoring only) — `regressions[]` is the evidence - Run `--phase after` again after each significant change; it is idempotent - The "under 20 lines" and "depth ≤ 2" targets are guidance, not thresholds to enforce mechanically. No bundled script measures them, deliberately: a rule that split every 20-line function would produce worse code than it found. Judge each hotspot on whether the extraction has a name worth having.