code-simplify

---
name: code-simplify
description: "Code simplification and refactoring for clarity, consistency, and maintainability. This skill should be used when the user asks to 'simplify this code', 'refactor for clarity', 'clean up code', 'reduce complexity', 'make this more readable', 'simplify recent changes', or mentions improving code elegance without changing functionality."
mode: [coding, engineering]
effort: low
---

# Code Simplification

Refactor code for clarity, consistency, and maintainability while preserving exact functionality.
Focus on recently modified code unless explicitly instructed to review broader scope.

## Core Principles

1. **Preserve Functionality** — Never change what code does, only how it does it. All outputs, behaviors, and side effects remain identical.
2. **Apply Project Standards** — Follow CLAUDE.md and .claude/rules/ conventions (naming, patterns, imports, types).
3. **Clarity Over Brevity** — Explicit readable code beats clever one-liners. NEVER use nested ternaries. Prefer switch/if-else for multiple conditions.
4. **Balance** — Avoid over-simplification that reduces debuggability, removes helpful abstractions, or combines too many concerns.

## Workflow

### 1. Identify Scope
- Default: recently modified files (`git diff --name-only` + `git diff --cached --name-only`)
- If user specifies files/directories: use those
- If user says "everything": scan full codebase (confirm scope via AskUserQuestion first)

### 2. Analyze Opportunities
For each file in scope, look for:
- **Unnecessary complexity**: deep nesting, convoluted control flow
- **Redundant code**: duplicated logic, unused variables/imports, dead code
- **Naming improvements**: unclear variable/function names
- **Consolidation**: related logic spread across multiple places
- **Pattern alignment**: code that doesn't follow project patterns (check PATTERNS.md)
- **Type improvements**: `string` params that should be union types, missing return types
- **Comment cleanup**: remove comments that describe obvious code

### 3. Propose Changes
Present changes grouped by file. For each:
- **What**: brief description of the change
- **Why**: which principle it serves
- **Before/After**: code comparison (keep minimal)

Use AskUserQuestion to confirm before applying changes.

### 4. Apply Refinements
- Apply approved changes using Edit tool
- Run type-check after changes: `bun run type-check` or `tsc --noEmit`
- Run tests if available
- Verify no functionality changed

### 5. Summary
Report:
- Files modified (count + list)
- Types of simplifications applied
- Any issues found but not addressed (with reasons)

## What to Simplify

| Pattern | Action |
|---------|--------|
| Deep nesting (3+ levels) | Extract to named functions |
| Repeated code blocks | Extract to shared util/hook |
| Unclear names | Rename to descriptive names |
| `any` types | Add proper TypeScript types |
| Long functions (50+ lines) | Split into focused functions |
| Inline logic in JSX | Extract to named variables |
| Magic numbers/strings | Extract to named constants |
| Nested ternaries | Convert to switch/if-else |

## What NOT to Change

- Working functionality (even if imperfect)
- External API contracts
- Code outside the specified scope
- Performance-critical code (without profiling)
- Patterns mandated by CLAUDE.md or PATTERNS.md
- Test files (unless specifically asked)

## HITL Gates

- Before applying changes → present summary and get approval via AskUserQuestion
- If changes affect >5 files → break into batches, approve each
- If uncertain about a change → skip it and note it in summary

---

## SOTA 2026 Enhancements (invoked via /atlas-simplify)

The sections below activate when the `/atlas-simplify` slash command is used.
They extend the core workflow above — they do NOT replace it.

### Polyglot AST (ast-grep)

[ast-grep](https://ast-grep.github.io) enables **structural** pattern matching and rewriting across
Python, TypeScript, and JavaScript using tree-sitter grammars. Unlike regex, it understands code
structure (function bodies, argument lists, import statements) and avoids false positives.

When to run: on every `/atlas-simplify` pass, AFTER the standard readability analysis.

```bash
# Structural scan (suggest only — user approves each rewrite)
sg scan --config .sg-rules/ .          # project-specific rules if present
sg run -p 'console.log($MSG)' --rewrite 'logger.debug($MSG)' .  # ad-hoc pattern
```

Reference recipes (5-8 patterns for Python/TS/JS): `references/ast-grep-recipes.md`

**Key constraint**: ast-grep is OPTIONAL. If not installed, skip this step and note it in summary.
Never auto-install; suggest `mise use ast-grep` or `brew install ast-grep` for user.

### Plummer 8-Pattern Lift

Before finalizing simplification changes, run the Plummer 8-pattern heuristics
(cross-reference only — do NOT copy patterns here):

→ `skills/performance-discipline/references/anti-patterns-from-plummer.md`

Quick scan (run on every `/atlas-simplify` pass):

```bash
# Pattern 1: base64 over byte-friendly transport
rg -n 'b64encode|btoa\(' --type py --type ts -A 3 | grep -E 'send|write|publish|emit'

# Pattern 4: N+1 queries
rg -n -B 2 -A 4 'await\s+\w+\.(fetch|execute|query)' --type py | grep -E 'for|while' -B 4

# Pattern 7: idle background work without back-off
rg -n 'setInterval\(' --type ts --type js -A 3 | grep -v 'clearInterval'
```

Report any hits as `⚡ [plummer-N]` findings in the summary. Severity follows anti-patterns-from-plummer.md
(🔴 HIGH = block, 🟡 MED = PR comment, 🟢 LOW = note).

### HITL ≥5 Files Gate

When the combined scope (standard + ast-grep + Plummer + dead-code) touches **≥5 files**:

1. **STOP** — do not apply any changes yet
2. Present full change manifest: `file | type_of_change | risk (low/med/high) | lines_affected`
3. Use AskUserQuestion: "N files will be modified. Approve all / approve-by-batch / cancel?"
4. If approve-by-batch: present groups of ≤3 files, one AskUserQuestion per group
5. Apply only after explicit confirmation

This gate is NON-NEGOTIABLE. It prevents batch surprises and ensures audit traceability.
Log gate invocation in `~/.atlas/simplify.jsonl` with `hitl_gate: true`.

### Idempotency Re-run

After applying all approved changes:

1. Re-run the full analysis (steps 2-4 of the workflow above)
2. **Expected result**: zero new findings from readability, ast-grep, Plummer, and dead-code passes
3. If new findings appear: they indicate the first pass introduced complexity — fix before marking done
4. Log result in `~/.atlas/simplify.jsonl` with `idempotent: true/false`

The idempotency check is the final quality gate. A simplification run that introduces new issues
is worse than no run at all.

## Dead-Code Detection (optional tooling)

Before finalizing the scope analysis, check for dead code if tooling is available:

| Language | Tool | Command |
|----------|------|---------|
| TypeScript / JS | Knip | `bunx knip` — see `references/knip-config.md` |
| Python | ruff | `ruff check --select F401 .` (unused imports) |
| Python | vulture | `vulture . --min-confidence 80` |

Report dead-code findings as `💀 [dead-code]` items in the summary. Removing dead code is
always safe, but confirm with AskUserQuestion if the dead code is inside a public API surface.

## Cross-References

- **Performance discipline**: `skills/performance-discipline/SKILL.md` (doctrine + 3-question framework)
- **Plummer 8 patterns**: `skills/performance-discipline/references/anti-patterns-from-plummer.md`
- **Code hygiene rules**: `skills/code-hygiene-rules/SKILL.md` (style + consistency rules)
- **Senior review checklist**: `skills/senior-review-checklist/SKILL.md` (dim 8 AI-perf patterns)
- **ast-grep recipes**: `references/ast-grep-recipes.md` (5-8 structural rewrite patterns)
- **Biome v2.3 config**: `references/biome-v2.3-config.md` (typed lint 423 rules, 60× faster)
- **Knip config**: `references/knip-config.md` (TS/JS dead-code detection setup)
- **Slash command**: `/atlas-simplify` — thin invoker with augmentation story