trace
TRACE (Type/Readability/Atomic/Cognitive/Essential) lens for explaining code and proposing improvements (no edits applied).
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.
| name | trace |
|---|---|
| description | TRACE (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
- Choose the slice: entrypoint, inputs, outputs, and state.
- Build a cognitive heat map (hotspots + surprises).
- Trace behavior: happy path + key failure paths; call out mutations/IO.
- Apply the TRACE checklist (below) to each hotspot.
- Propose suggested edits:
- 1–3 smallest improvements per hotspot.
- Include file:line targets.
- Use short pseudo-diffs or code sketches.
- 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"