1. Read the actual code and understand what it does
2. Identify existing tests that cover the code
3. Run existing tests to establish a passing baseline
4. Confirm the scope of simplification with the user
5. Never change what the code does — only how it is written

Simplifying without understanding = broken behavior, lost functionality, introduced bugs

This is not optional. Every simplification requires disciplined verification. </EXTREMELY-IMPORTANT>

Code Simplify

MANDATORY FIRST RESPONSE PROTOCOL

Before simplifying ANY code, you MUST complete this checklist:

1. ☐ Read the target code thoroughly (not just skim)
2. ☐ Identify what the code does (inputs, outputs, side effects)
3. ☐ Check for existing tests covering the target code
4. ☐ Run existing tests to establish a passing baseline
5. ☐ Read CLAUDE.md for project-specific standards (if it exists)
6. ☐ Identify simplification opportunities (list them)
7. ☐ Classify each opportunity by type (extract, flatten, rename, consolidate, eliminate)
8. ☐ Announce: "Simplifying [scope]: [N] opportunities identified across [M] files"

Simplifying code WITHOUT completing this checklist = regressions and lost functionality.

Overview

Analyze code for unnecessary complexity and apply targeted simplifications that improve clarity, consistency, and maintainability — without changing behavior. The skill is language-agnostic: it works for any language and follows project-specific standards from CLAUDE.md when available.

What this skill does:

• Reduces nesting depth (flatten conditionals, extract early returns)
• Eliminates redundant code (dead imports, unreachable branches, unused variables)
• Improves naming (unclear abbreviations → descriptive names)
• Consolidates duplicate logic (repeated patterns → shared functions)
• Simplifies boolean and conditional expressions
• Replaces clever code with readable code

What this skill does NOT do:

• Change functionality or behavior
• Add new features or capabilities
• Refactor architecture (use a dedicated refactoring approach for that)
• Optimize performance (simplification may happen to improve performance, but that is not the goal)
• Add comments, documentation, or type annotations to unchanged code

When to Use

• User says "simplify", "clean up", "make this simpler", "reduce complexity", "/code-simplify"
• User asks to improve code clarity or readability
• User points to specific code and asks to make it easier to understand
• $ARGUMENTS provided as simplification guidance (e.g., /code-simplify flatten the nested ifs in auth.ts)

Never simplify proactively. Only when explicitly requested.

When NOT to Use

• Code is already clear — don't simplify code that is already readable and well-structured
• Changes require architectural decisions — if simplification requires rethinking the design, discuss with the user first
• Test code — don't simplify test code unless the user explicitly asks; test verbosity often aids debugging
• Generated code — don't simplify auto-generated files (protobuf, GraphQL codegen, etc.)
• Performance-critical paths — if code is complex for performance reasons, simplification may degrade performance

Step 1: Gather Context

Gate: Code read and understood before proceeding to Step 2.

Read the target code and understand its purpose:

1. Read the files the user wants simplified
2. Read CLAUDE.md (if it exists) for project standards and conventions
3. Check for existing tests covering the target code
4. Run existing tests to confirm they pass:

# Run project test suite (adapt command to project)
# npm test / pytest / cargo test / go test ./...

5. Check recent git history for the files to understand recent changes:

git log --oneline -10 -- <file paths>

Read the actual code. Skimming file names is not enough. You must understand what every function does before deciding what to simplify.

Step 2: Identify Simplification Targets

Gate: All targets identified and classified before proceeding to Step 3.

Scan the code for simplification opportunities. Look for these signals:

For each opportunity found, note:

• Location (file:line)
• Type (flatten, extract, rename, consolidate, eliminate, simplify)
• Risk (low: cosmetic, medium: structural, high: logic-adjacent)

Step 3: Classify Each Simplification

Gate: Each simplification classified with risk level before proceeding to Step 4.

Categorize every identified target:

High-risk simplifications (any that touch logic flow) require explicit user confirmation before applying.

Step 4: Plan Changes

Gate: User has reviewed and approved the plan before proceeding to Step 5.

Present the simplification plan to the user. For each change, show:

1. File and location — where the change will be made
2. Category — what type of simplification (from Step 3)
3. Before — the current code (abbreviated if long)
4. After — what the simplified code will look like
5. Why — one sentence explaining why this is simpler

Use AskUserQuestion if the user needs to choose between alternatives or approve scope.

Do NOT proceed to Step 5 without user confirmation. The user must see and approve the plan.

Step 5: Apply Simplifications

Gate: All edits applied cleanly before proceeding to Step 6.

Apply the approved simplifications:

1. Make edits one file at a time using the Edit tool
2. Apply changes in order from lowest-risk to highest-risk
3. After each file, verify the edits are syntactically valid
4. If a simplification creates an unexpected cascade (other code depends on renamed function, etc.), stop and inform the user

Rules during application:

• Never change function signatures visible to external callers without user approval
• Never change return values or side effects
• Never remove error handling
• Preserve all existing comments unless they describe removed code
• Follow the project's existing code style (indentation, quotes, semicolons)

Step 6: Verify Behavior Preserved

Gate: All tests pass and no type errors before proceeding to Step 7.

After applying simplifications, verify nothing broke:

1. Run the project's test suite:

# Run tests (adapt to project)
# npm test / pytest / cargo test / go test ./...

2. Run type checking (if applicable):

# TypeScript: npx tsc --noEmit
# Python: mypy / pyright
# Go: go vet ./...

3. Compare test results against the baseline from Step 1
4. If any test fails, revert the change that caused it and report to the user

If tests fail after simplification, the simplification was wrong. Do not adjust tests to match simplified code — the original behavior is correct.

Step 7: Report Results

Gate: Summary complete before marking skill done.

Present a summary of what was simplified:

For each change made:

• File:line — location
• Category — type of simplification
• Before → After — brief description of the change
• Lines — net change in line count (if relevant)

Include overall metrics:

• Total simplifications applied
• Total files modified
• Test results (all passing / any failures)
• Net complexity change (qualitative assessment)

Simplification Patterns Reference

Concrete patterns with before/after examples. Use these as a catalog when identifying targets.

Pattern 1: Flatten Nested Conditionals

Before:

if (user) {
  if (user.isActive) {
    if (user.hasPermission('admin')) {
      return doAdminAction(user);
    }
  }
}
return null;

After:

if (!user) return null;
if (!user.isActive) return null;
if (!user.hasPermission('admin')) return null;
return doAdminAction(user);

Pattern 2: Extract Complex Expressions

Before:

if (items.length > 0 && items.every(i => i.status === 'ready') && !isProcessing && currentUser.role !== 'viewer') {
  startBatch(items);
}

After:

const hasReadyItems = items.length > 0 && items.every(i => i.status === 'ready');
const canProcess = !isProcessing && currentUser.role !== 'viewer';

if (hasReadyItems && canProcess) {
  startBatch(items);
}

Pattern 3: Replace Nested Ternaries

Before:

const label = status === 'active' ? 'Active' : status === 'pending' ? 'Pending' : status === 'disabled' ? 'Disabled' : 'Unknown';

After:

function getStatusLabel(status) {
  switch (status) {
    case 'active': return 'Active';
    case 'pending': return 'Pending';
    case 'disabled': return 'Disabled';
    default: return 'Unknown';
  }
}
const label = getStatusLabel(status);

Pattern 4: Consolidate Duplicate Logic

Before:

function createUser(data) {
  validateName(data.name);
  validateEmail(data.email);
  validateAge(data.age);
  return db.users.insert(data);
}

function updateUser(id, data) {
  validateName(data.name);
  validateEmail(data.email);
  validateAge(data.age);
  return db.users.update(id, data);
}

After:

function validateUserData(data) {
  validateName(data.name);
  validateEmail(data.email);
  validateAge(data.age);
}

function createUser(data) {
  validateUserData(data);
  return db.users.insert(data);
}

function updateUser(id, data) {
  validateUserData(data);
  return db.users.update(id, data);
}

Pattern 5: Eliminate Dead Code

Before:

import { format, parse, isValid, addDays } from 'date-fns';  // parse and addDays unused

function processDate(input) {
  // Old implementation (kept for reference)
  // const parsed = parse(input, 'yyyy-MM-dd', new Date());

  if (isValid(new Date(input))) {
    return format(new Date(input), 'MMM d, yyyy');
  }
  return 'Invalid date';
}

After:

import { format, isValid } from 'date-fns';

function processDate(input) {
  if (isValid(new Date(input))) {
    return format(new Date(input), 'MMM d, yyyy');
  }
  return 'Invalid date';
}

Pattern 6: Simplify Boolean Expressions

Before:

if (isEnabled === true) { ... }
if (items.length === 0 ? true : false) { ... }
if (!!value) { ... }
return condition ? true : false;

After:

if (isEnabled) { ... }
if (items.length === 0) { ... }
if (value) { ... }
return condition;

Pattern 7: Reduce Function Parameters

Before:

function sendEmail(to, from, subject, body, cc, bcc, replyTo, isHtml) {
  // ...
}
sendEmail('a@b.com', 'c@d.com', 'Hello', '<p>Hi</p>', null, null, null, true);

After:

function sendEmail({ to, from, subject, body, cc, bcc, replyTo, isHtml = false }) {
  // ...
}
sendEmail({ to: 'a@b.com', from: 'c@d.com', subject: 'Hello', body: '<p>Hi</p>', isHtml: true });

Pattern 8: Flatten Callback Pyramids

Before:

getUser(id, function(err, user) {
  if (err) return handleError(err);
  getOrders(user.id, function(err, orders) {
    if (err) return handleError(err);
    getInvoices(orders, function(err, invoices) {
      if (err) return handleError(err);
      sendReport(user, invoices);
    });
  });
});

After:

try {
  const user = await getUser(id);
  const orders = await getOrders(user.id);
  const invoices = await getInvoices(orders);
  await sendReport(user, invoices);
} catch (err) {
  handleError(err);
}

Safety Rules

Quick Reference: Simplification Decision

Is the code hard to understand?
├── YES → Is it because of deep nesting?
│          ├── YES → Flatten (early returns, guard clauses)
│          └── NO → Is it because of complex expressions?
│                    ├── YES → Extract (named variables/functions)
│                    └── NO → Is it because of unclear names?
│                              ├── YES → Rename
│                              └── NO → Is it duplicated?
│                                        ├── YES → Consolidate
│                                        └── NO → Is there dead code?
│                                                  ├── YES → Eliminate
│                                                  └── NO → Leave it alone
└── NO → Don't simplify it

Step 8: Verification (MANDATORY)

After simplifying, verify complete workflow:

Check 1: Behavior Preserved

• All existing tests pass (same results as baseline)
• No type errors introduced

Check 2: Scope Respected

• Only approved simplifications were applied
• No changes outside the agreed scope

Check 3: Code Quality

• Simplified code is genuinely clearer than the original
• No clever or obscure patterns introduced

Check 4: Project Standards

• Changes follow CLAUDE.md conventions (if applicable)
• No style inconsistencies with surrounding code

Check 5: Clean State

• All files are saved
• No partial edits or leftover debugging code

Gate: Do NOT mark simplification complete until all 5 checks pass.

Quality Checklist (Must Score 8/10)

Score yourself honestly before marking simplification complete:

Context Gathering (0-2 points)

• 0 points: Simplified without reading the code first
• 1 point: Read the code but skipped tests/standards check
• 2 points: Read code, ran tests, checked CLAUDE.md for conventions

Target Identification (0-2 points)

• 0 points: Applied random changes without systematic analysis
• 1 point: Found some opportunities but missed obvious ones
• 2 points: Systematically identified and classified all targets

User Communication (0-2 points)

• 0 points: Applied changes without showing the user
• 1 point: Showed partial plan, skipped some changes
• 2 points: Full plan shown with before/after for each change, user approved

Behavior Preservation (0-2 points)

• 0 points: Tests fail after simplification
• 1 point: Tests pass but didn't verify edge cases
• 2 points: All tests pass, type checks pass, behavior verified identical

Result Quality (0-2 points)

• 0 points: Code is not meaningfully clearer
• 1 point: Some improvements but inconsistent
• 2 points: Every change genuinely improves clarity without sacrificing readability

Minimum passing score: 8/10

Common Rationalizations (All Wrong)

These are excuses. Don't fall for them:

• "It's obvious what this code does" → STILL read it thoroughly before simplifying
• "These tests are slow" → STILL run them before and after changes
• "The user wants it simpler, not tested" → STILL verify behavior is preserved
• "This is just renaming, it can't break anything" → STILL check for all references
• "I'll show the user after I'm done" → STILL present the plan before applying changes
• "The code style is bad everywhere" → STILL only change what was requested
• "Fewer lines is always better" → Clarity over brevity; explicit beats compact
• "This clever one-liner is equivalent" → Readable code beats clever code every time

Failure Modes

Failure Mode 1: Behavior Changed

Symptom: Tests fail after simplification, or code produces different outputs Fix: Revert the change immediately. Re-read the original code, understand the behavior you missed, and re-plan.

Failure Mode 2: Over-Simplification

Symptom: Code is shorter but harder to understand (dense one-liners, nested ternaries, clever tricks) Fix: Revert and apply the principle: clarity over brevity. Explicit code is simpler than compact code.

Failure Mode 3: Scope Creep

Symptom: Started simplifying one function, ended up refactoring the whole module Fix: Stop. Return to the approved scope. Only simplify what was agreed upon in Step 4.

Failure Mode 4: Broken References

Symptom: Renamed a function or variable but missed some call sites Fix: Use project-wide search (Grep) to find all references before renaming. Apply renames with replace_all.

Failure Mode 5: Style Inconsistency

Symptom: Simplified code follows different conventions than surrounding code Fix: Re-read CLAUDE.md and the surrounding code. Match the project's existing style, not your preferred style.

Quick Workflow Summary

STEP 1: GATHER CONTEXT
├── Read target code thoroughly
├── Run existing tests (baseline)
├── Read CLAUDE.md for standards
└── Gate: Code understood

STEP 2: IDENTIFY TARGETS
├── Scan for simplification signals
├── Note location, type, risk for each
└── Gate: All targets identified

STEP 3: CLASSIFY
├── Categorize: flatten, extract, rename, consolidate, eliminate, simplify
├── Assign risk levels
└── Gate: All targets classified

STEP 4: PLAN CHANGES
├── Show before/after for each change
├── Get user approval
└── Gate: User approved plan

STEP 5: APPLY SIMPLIFICATIONS
├── Edit files one at a time
├── Low-risk first, high-risk last
└── Gate: All edits applied cleanly

STEP 6: VERIFY BEHAVIOR
├── Run tests (compare to baseline)
├── Run type checks
└── Gate: All tests pass

STEP 7: REPORT RESULTS
├── Summarize changes made
├── Show metrics
└── Gate: Summary complete

STEP 8: VERIFICATION (MANDATORY)
├── Check 1: Behavior preserved
├── Check 2: Scope respected
├── Check 3: Code quality
├── Check 4: Project standards
├── Check 5: Clean state
└── Gate: All 5 checks pass

Completion Announcement

When simplification is complete, announce:

Simplification complete.

**Quality Score: X/10**
- Context Gathering: X/2
- Target Identification: X/2
- User Communication: X/2
- Behavior Preservation: X/2
- Result Quality: X/2

**Summary:**
- Files modified: [count]
- Simplifications applied: [count]
- Categories: [list of categories used]
- Net line change: [+/-N lines]

**Verification:**
- Tests pass: ✅
- Type checks pass: ✅
- Behavior preserved: ✅
- Scope respected: ✅

**Next steps:**
[Commit changes, review further files, or continue work]

Integration with Other Skills

The code-simplify skill integrates with:

• commit — After simplifying, invoke commit to commit the changes
• create-pr — After committing, invoke create-pr to submit for review
• plan-to-task-list-with-dag — For large-scale simplification spanning many files, use plan-to-task-list-with-dag first to design the approach

Workflow Chain:

User requests simplification
       │
       ▼
code-simplify skill (this skill)
       │
       ▼
commit skill (commit the changes)
       │
       ▼
create-pr skill (if submitting for review)