Nav Simplify

---
name: nav-simplify
description: Simplify and refine code for clarity, consistency, and maintainability while preserving all functionality. Focuses on recently modified code. Auto-invoke after implementation skills or on-demand.
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
version: 1.0.0
model: opus
---

# Navigator Code Simplification Skill

Simplify recently modified code for clarity, consistency, and maintainability while preserving exact functionality. Based on Anthropic's internal code-simplifier pattern.

## Core Principle

**Clarity over brevity. Functionality preserved absolutely.**

You are an expert code simplification specialist. Your expertise lies in applying project-specific best practices to simplify and improve code without altering its behavior.

## When to Invoke

**Auto-invoke after**:
- `backend-endpoint` skill completes
- `frontend-component` skill completes
- `database-migration` skill completes
- Any implementation task with code changes

**Manual invoke when user says**:
- "simplify this code"
- "review for clarity"
- "clean up recent changes"
- "refactor for readability"
- "simplify modified files"

**DO NOT invoke if**:
- No code was modified (docs-only changes)
- User explicitly says "skip simplification"
- Files are configuration only (JSON, YAML)

## Execution Steps

### Step 1: Identify Modified Code

**Option A: Git-based detection (preferred)**

```bash
# Get files modified in current session/commits
git diff --name-only HEAD~3 -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.py' '*.go' '*.rs' 2>/dev/null || \
git diff --name-only --cached -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.py' '*.go' '*.rs' 2>/dev/null || \
git diff --name-only -- '*.ts' '*.tsx' '*.js' '*.jsx' '*.py' '*.go' '*.rs'
```

**Option B: User-specified scope**

If user mentions specific files or directories, use those instead.

**Option C: Recent conversation context**

Analyze conversation for files that were written/edited in this session.

### Step 2: Load Simplification Configuration

Check for project-specific configuration:

```bash
if [ -f ".agent/.nav-config.json" ]; then
  python3 -c "import json; c=json.load(open('.agent/.nav-config.json')); s=c.get('simplification',{}); print('auto_apply=' + str(s.get('auto_apply', False)).lower()); print('enabled=' + str(s.get('enabled', True)).lower())"
fi
```

Default configuration:
```json
{
  "simplification": {
    "enabled": true,
    "trigger": "post-implementation",
    "scope": "modified",
    "model": "opus",
    "skip_patterns": ["*.test.*", "*.spec.*", "*.md", "*.json", "*.yaml"],
    "max_file_size": 50000,
    "auto_apply": false,
    "preserve_comments": true
  }
}
```

#### Autonomous context check (CRITICAL)

After loading config, determine the invocation mode:

**Autonomous** (no human in the loop):
- Invoked from `nav-loop` VERIFY or COMPLETE phase
- Invoked from `nav-workflow` COMPLETE phase
- `NAV_AUTONOMOUS=1` env var set
- Triggered by autonomous-completion protocol

**Interactive** (human reviewing):
- Direct user request ("simplify this code")
- Mid-implementation manual invocation

**Decision matrix**:

| `auto_apply` | Context | Action |
|---|---|---|
| `true` | autonomous | Apply directly (Step 7 silent) |
| `true` | interactive | Apply directly, show summary |
| `false` | autonomous | **SKIP simplification entirely** — emit warning, return to caller. Never pause an autonomous flow waiting for approval. |
| `false` | interactive | Show diff per file, prompt for approval |

When skipping in autonomous-mode-with-false, emit:
```
⚠️  nav-simplify skipped: auto_apply=false but invoked autonomously.
   To enable: set simplification.auto_apply=true in .agent/.nav-config.json
   To disable cleanly: set simplification.enabled=false
```

### Step 3: Read Project Standards

**Load from CLAUDE.md** (required):

```
Read(file_path: "CLAUDE.md")
```

Extract coding standards:
- Preferred patterns (function vs arrow, explicit returns)
- Naming conventions
- Import ordering
- Error handling patterns
- Framework-specific guidelines

### Step 4: Analyze Each File

For each modified file, analyze for simplification opportunities:

**Complexity Indicators** (look for):
- Deep nesting (> 3 levels)
- Long functions (> 50 lines)
- Redundant code patterns
- Unclear variable names
- Nested ternary operators
- Over-abstraction
- Dead code
- Inconsistent patterns

**Run analysis**:
```bash
PLUGIN_DIR="${CLAUDE_PLUGIN_ROOT:-$(cat "${NAVIGATOR_CONFIG_HOME:-${XDG_CONFIG_HOME:-$HOME/.config}/navigator}/plugin-root" 2>/dev/null)}"
[ -d "$PLUGIN_DIR/skills" ] || PLUGIN_DIR="$HOME/.claude/plugins/marketplaces/navigator-marketplace"
# Pass --scoring roi to enable cost/benefit gating (default: complexity,
# legacy behavior).
python3 "$PLUGIN_DIR/skills/nav-simplify/scripts/code_analyzer.py" --file "$file" --scoring roi
```

### Step 4.5: ROI Gate (when scoring.mode = "roi")

If `simplification.scoring.mode` is `"roi"` in `.agent/.nav-config.json` (or `--scoring roi` was passed), the analyzer emits `benefit_score`, `cost_score`, `roi_score`, and a `gate_action` field. Honor the gate:

| `gate_action` | Behavior |
|---|---|
| `skip` | Skip this file. Emit a one-line reason with ROI math. Continue to next file. |
| `suggest` | Force interactive mode for this file regardless of `auto_apply`. Show diff + reason. |
| `apply` | Proceed with Step 5+ as normal (honor `auto_apply`). |

**Skip emission format**:
```
⏭️  {file} — low ROI (B={B}/10, C={C}/10, ROI={R}). Skipping.
   {reason}
```

`{reason}` summarizes the dominant cost factor (e.g., "stable file (412 days), 8 import references" or "below skip_below threshold").

**Mode is opt-in.** When `scoring.mode == "complexity"` (default), Step 4.5 is a no-op and behavior is unchanged from prior versions.

### Step 5: Apply Simplification Rules

**Anthropic Simplification Rules**:

1. **Preserve Functionality**: Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.

2. **Apply Project Standards**: Follow CLAUDE.md coding standards:
   - Use ES modules with proper import sorting
   - Prefer `function` keyword over arrow functions (if project standard)
   - Use explicit return type annotations
   - Follow proper React/Vue component patterns
   - Use proper error handling patterns
   - Maintain consistent naming conventions

3. **Enhance Clarity**:
   - Reduce unnecessary complexity and nesting
   - Eliminate redundant code and abstractions
   - Improve readability through clear names
   - Consolidate related logic
   - Remove unnecessary comments that describe obvious code
   - **AVOID nested ternary operators** - use switch/if-else
   - **Choose clarity over brevity** - explicit > compact

4. **Maintain Balance** - Avoid over-simplification that could:
   - Reduce code clarity or maintainability
   - Create overly clever solutions
   - Combine too many concerns
   - Remove helpful abstractions
   - Prioritize "fewer lines" over readability
   - Make code harder to debug or extend

### Step 6: Generate Simplified Code

For each file with improvements:

1. Read current file content
2. Apply simplification rules
3. Verify functionality unchanged (logic review)
4. Generate diff or replacement

**Output format**:
```
📝 Simplifying: {filename}

Changes:
- [Line X] Flattened nested ternary to switch statement
- [Line Y] Extracted repeated logic to helper function
- [Line Z] Renamed `x` to `userCount` for clarity

Diff:
```diff
- const result = a ? (b ? c : d) : e;
+ let result;
+ if (a && b) {
+   result = c;
+ } else if (a) {
+   result = d;
+ } else {
+   result = e;
+ }
```
```

### Step 7: Apply Changes

Branch on the decision matrix from Step 2:

**Autonomous + `auto_apply: false`**: skip entirely, emit the warning, return.

**Autonomous + `auto_apply: true`**: apply each change directly with `Edit()`. Do not prompt.

**Interactive + `auto_apply: true`**: apply directly, show summary at end.

**Interactive + `auto_apply: false`**: show diff per file, prompt `Apply this change? [y/N]`, apply only on yes.

When applying:
```
Edit(
  file_path: "{file}",
  old_string: "{original}",
  new_string: "{simplified}"
)
```

### Step 8: Generate Summary

```
╔══════════════════════════════════════════════════════╗
║                                                      ║
║  🧹 Code Simplification Complete                     ║
║                                                      ║
╚══════════════════════════════════════════════════════╝

📊 Summary:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Files analyzed:    {N}
Files simplified:  {M}
Changes applied:   {X}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📝 Changes by category:
• Clarity improvements:     {count}
• Nesting reduction:        {count}
• Naming improvements:      {count}
• Pattern consolidation:    {count}

✅ Functionality: Preserved (no behavior changes)
✅ Standards: Applied from CLAUDE.md

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## Predefined Functions

### scripts/code_analyzer.py

**Purpose**: Analyze code file for simplification opportunities

**Arguments**:
- `--file`: Path to file to analyze
- `--standards`: Path to CLAUDE.md (optional)
- `--output`: Output format (json, text)

**Returns**:
```json
{
  "file": "src/utils/auth.ts",
  "issues": [
    {
      "line": 45,
      "type": "nested_ternary",
      "severity": "medium",
      "suggestion": "Convert to switch or if-else"
    },
    {
      "line": 78,
      "type": "deep_nesting",
      "severity": "high",
      "depth": 5,
      "suggestion": "Extract to helper function"
    }
  ],
  "complexity_score": 7.2,
  "recommended_actions": 3
}
```

When invoked with `--scoring roi` (or `simplification.scoring.mode == "roi"`), the output additionally contains:

```json
{
  "benefit_score": 6.1,
  "cost_score": 4.3,
  "roi_score": 1.4,
  "gate_action": "suggest",
  "scoring_explanation": {
    "benefit": {"issue_density": 0.4, "severity_impact": 5.2, "in_active_diff": true},
    "cost": {"estimated_touch_lines": 32, "file_loc": 287, "days_since_modified": 12, "import_references": 3},
    "thresholds": {"skip_below": 0.5, "suggest_below": 1.5, "auto_apply_at": 1.5},
    "cost_floor": 0.5
  }
}
```

### scripts/simplification_rules.py

**Purpose**: Apply project-specific simplification rules

**Arguments**:
- `--file`: Path to file
- `--claude-md`: Path to CLAUDE.md for project standards
- `--dry-run`: Preview changes without applying

**Returns**: Simplified code with change annotations

### scripts/change_reporter.py

**Purpose**: Generate human-readable change summary

**Arguments**:
- `--changes`: JSON array of changes made
- `--format`: Output format (markdown, text, json)

**Returns**: Formatted change report

## Configuration Options

Add to `.agent/.nav-config.json`:

```json
{
  "simplification": {
    "enabled": true,
    "trigger": "post-implementation",
    "scope": "modified",
    "model": "opus",
    "skip_patterns": ["*.test.*", "*.spec.*"],
    "max_file_size": 50000,
    "auto_apply": false,
    "preserve_comments": true,
    "rules": {
      "avoid_nested_ternary": true,
      "max_nesting_depth": 3,
      "max_function_length": 50,
      "prefer_explicit_returns": true,
      "consolidate_imports": true
    },
    "scoring": {
      "mode": "complexity",
      "skip_below": 0.5,
      "suggest_below": 1.5,
      "auto_apply_at": 1.5,
      "cost_floor": 0.5
    }
  }
}
```

**Options**:
- `enabled`: Enable/disable simplification
- `trigger`: "manual" | "post-implementation" | "pre-commit"
- `scope`: "modified" | "staged" | "all"
- `model`: Preferred model for simplification (opus recommended)
- `skip_patterns`: Glob patterns to skip
- `max_file_size`: Skip files larger than this (bytes)
- `auto_apply`: Apply changes without confirmation
- `preserve_comments`: Keep meaningful comments
- `rules`: Specific simplification rules
- `scoring.mode`: `"complexity"` (legacy, default) or `"roi"` (opt-in cost/benefit gating)
- `scoring.skip_below`: ROI threshold below which files are skipped entirely
- `scoring.auto_apply_at`: ROI threshold at and above which auto-apply is honored
- `scoring.cost_floor`: Minimum cost denominator to prevent ROI explosions

## Integration Points

### Autonomous Completion

When integrated with autonomous completion protocol:

```
Implement → Verify → **Simplify** → Commit → Archive
```

Simplification runs automatically after verification passes, before commit.

### Loop Mode

Added to VERIFY phase completion indicators:
```
Completion Indicators:
  [x] Tests passing
  [x] Code simplified  ← Added
  [ ] Documentation updated
```

## Examples

### Example 1: Nested Ternary Simplification

**Before**:
```typescript
const status = isLoading ? 'loading' : hasError ? 'error' : isSuccess ? 'success' : 'idle';
```

**After**:
```typescript
function getStatus(isLoading: boolean, hasError: boolean, isSuccess: boolean): string {
  if (isLoading) return 'loading';
  if (hasError) return 'error';
  if (isSuccess) return 'success';
  return 'idle';
}

const status = getStatus(isLoading, hasError, isSuccess);
```

### Example 2: Deep Nesting Reduction

**Before**:
```typescript
function processUser(user: User) {
  if (user) {
    if (user.isActive) {
      if (user.hasPermission) {
        if (user.email) {
          sendEmail(user.email);
        }
      }
    }
  }
}
```

**After**:
```typescript
function processUser(user: User) {
  if (!user?.isActive) return;
  if (!user.hasPermission) return;
  if (!user.email) return;

  sendEmail(user.email);
}
```

### Example 3: Unclear Naming

**Before**:
```typescript
const x = users.filter(u => u.a && !u.d).map(u => u.n);
```

**After**:
```typescript
const activeUserNames = users
  .filter(user => user.isActive && !user.isDeleted)
  .map(user => user.name);
```

## Error Handling

**File too large**:
```
⚠️  Skipping {filename} ({size} bytes)
    Exceeds max_file_size limit ({limit} bytes)

    Override with: "simplify {filename} --force"
```

**No changes needed**:
```
✅ {filename} - Already follows best practices
   No simplification opportunities found.
```

**Functionality risk detected**:
```
⚠️  Potential behavior change detected in {filename}

    Line {N}: Changing conditional logic

    Review required before applying:
    [Show diff]

    Apply this change? [y/N]:
```

## Success Criteria

Simplification is successful when:
- [ ] All modified files analyzed
- [ ] Functionality preserved (verified)
- [ ] Project standards applied (from CLAUDE.md)
- [ ] No nested ternaries remain
- [ ] Nesting depth ≤ 3 levels
- [ ] Clear variable/function names
- [ ] Change summary generated

## Notes

- **Model preference**: Opus recommended for quality judgment
- **Scope default**: Only recently modified files (avoid churn)
- **Skip tests**: Test files usually follow different patterns
- **Preserve intent**: Comments explaining "why" should be kept
- **No over-optimization**: Clarity > minimal lines

This skill integrates Anthropic's internal code-simplifier pattern into Navigator's workflow, ensuring code quality before commit.