complexity-mitigator_skill

Overview

This skill mitigates incidental code complexity so readers can reason about domain intent without heavy mental simulation. It provides an analysis-first refactor plan: heat read hotspots, separate essential vs incidental concerns, ranked simplification options, a small structural sketch, and a TRACE assessment. The output is analysis-only; no edits are made.

How this skill works

It inspects control flow, nesting, boolean gates, cross-file dependencies, and mutable state to measure 'understanding cost.' It produces a concise heat read listing hotspots, traces key behaviors (happy and failure paths), separates essential domain logic from incidental implementation noise, and recommends flatten/rename/extract steps ranked by effort vs impact. Finally it sketches an improved structure and reports which TRACE letters are satisfied or violated.

When to use it

• A review stalls because the flow is hard to follow
• You need an analysis-first refactor plan before making edits
• Deep nesting (>3) or long if/else chains exist
• Multiple cross-file hops are required to understand behavior
• You want a minimal, high-impact simplification ranked by effort vs impact

Best practices

• Pick a clear slice: entrypoint, inputs, outputs, and state before analysis
• Start with a heat read: list hotspots with one-line rationale and a tag (essential/incidental/mixed)
• Apply flatten -> rename -> extract in that order unless a justified exception exists
• Prefer local, checkable evidence (nesting, flags, hops) over grand claims
• Rank options by effort vs impact and state the smallest viable cut

Example use cases

• A long function with nested conditionals where reviewers get lost
• Code that uses multiple boolean flags and implicit ordering, causing many mental states
• Cross-module logic where readers must jump files to follow invariants
• Pull request that needs a readable analysis before any edits are allowed
• When you need an explicit TRACE assessment to show what simplifications actually improve understanding