trace

tkersey's avatarfrom tkersey

TRACE (Type/Readability/Atomic/Cognitive/Essential) lens for explaining code and proposing improvements (no edits applied).

⭐32stars🔀0forks📁View on GitHub🕐Updated Jan 11, 2026⬇️7downloads

When & Why to Use This Skill

The TRACE skill is a structured code analysis framework designed to explain complex logic and identify technical friction using the Type, Readability, Atomic, Cognitive, and Essential (TRACE) lens. It helps developers understand intricate control flows and provides actionable refactoring suggestions through cognitive heat mapping and behavior tracing without modifying the source code.

Use Cases

  • Legacy Code Analysis: Walk through and explain confusing control flows or hidden side effects in inherited or poorly documented codebases.
  • Refactor Planning: Identify 'cognitive hotspots' and generate a detailed plan with pseudo-diffs to improve code maintainability before starting implementation.
  • Code Quality Auditing: Systematically evaluate specific code blocks against the TRACE checklist to ensure type safety, atomicity, and minimal incidental complexity.
  • Developer Onboarding: Create a step-by-step trace of 'happy paths' and failure modes to help team members quickly grasp the behavior of complex modules.
nametrace
descriptionTRACE (Type/Readability/Atomic/Cognitive/Essential) lens for explaining code and proposing improvements (no edits applied).

Trace

Intent

Explain code by tracing what it does and scoring friction through TRACE.

Deliver actionable suggestions (file/line targets + minimal patch sketches) but do not modify files.

When to use

  • “trace it” / “what is this doing?”
  • Explain confusing control flow or hidden side effects.
  • Readability/cognitive-load feedback when you want analysis-only.
  • Refactor planning (“what would you change?”) without implementation.

Workflow

  1. Choose the slice: entrypoint, inputs, outputs, and state.
  2. Build a cognitive heat map (hotspots + surprises).
  3. Trace behavior: happy path + key failure paths; call out mutations/IO.
  4. Apply the TRACE checklist (below) to each hotspot.
  5. Propose suggested edits:
    • 1–3 smallest improvements per hotspot.
    • Include file:line targets.
    • Use short pseudo-diffs or code sketches.
  6. Stop before editing; if changes are desired, escalate to $fix.

Guardrails

  • No file edits, no commits.
  • No running commands unless explicitly requested.
  • If expected behavior is unclear/product-sensitive, stop and ask.
  • If you suspect crash/corruption risk, recommend $fix.

TRACE checklist

  • Type: make invalid states unrepresentable; eliminate “maybe” states where possible.
  • Readability: understandable in 30 seconds; names match behavior.
  • Atomic: one responsibility per unit; explicit side effects.
  • Cognitive: minimize branching, hidden dependencies, and cross-file hops.
  • Essential: keep only domain-required complexity; delete incidental ceremony.

Activation cues

  • "trace" / "walk me through" / "explain"
  • "what is this doing" / "why is this complex"
  • "readability" / "cognitive load" (analysis-only)
  • "suggest improvements" / "refactor plan"