alekspetrov/navigator/nav-simplify

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)

# 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:

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:

{
  "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:

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:

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:

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.

1. 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

1. 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

1. 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:

• 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:

{
  "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:

{
  "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:

{
  "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