Treat avoidable confusion encountered during real work as evidence of a codebase smell. Before leaving the area, remove a small part of the friction that made it difficult to understand.
The healed codebase is the breadcrumb. Do not create a trail, registry, entry format, freshness stamp, or read-before-investigating ritual. Improve the place where understanding failed so the next developer benefits without knowing this skill exists.
Close every non-trivial trace with one question: what specific feature of the codebase made this harder to grasp than the behavior warranted? If the answer identifies a repeatable expectation failure, run the loop. If it identifies only unfamiliarity or genuine domain complexity, make no incidental change.
- Notice the expectation failure. Catch moments such as "that name sent me the wrong way," "I had to inspect every caller," or "that should have been documented."
- Finish the trace. Distinguish a repeatable codebase problem from temporary unfamiliarity or inherently difficult domain knowledge.
- Name the smell. Identify what caused the friction: misleading information scent, hostile navigation topology, an implicit contract, hidden rationale, fragmented ownership, diagnostic opacity, stale guidance, or accidental complexity. Use the smell catalog when the cause is ambiguous.
- Choose one coherent repair. Prefer removing confusion, then clearer code, executable constraints, better diagnostics, a local why, and finally an existing documentation surface. One repair may touch code, tests, and existing docs when they close the same expectation gap. Use the repair patterns for concrete transformations and placement guidance.
- Check scope. Keep the repair close to the traced area, useful beyond this session, and small enough to verify. Use the scope rails when the repair changes behavior, public contracts, architecture, or files outside the task.
- Heal and verify. Apply the repair while the evidence is fresh. Run the narrowest relevant test, type check, documentation check, or reference search.
- Continue the task. Mention the incidental repair in the normal handoff. Do not maintain a ledger.
Choose the highest useful rung that fits safely:
- Delete obsolete or misleading material.
- Rename, relocate, simplify, or expose the right entry point.
- Encode the contract in types, schemas, validation, assertions, or tests.
- Improve errors and diagnostic context.
- Explain a reason that code cannot express in a short adjacent comment.
- Update the existing documentation surface readers already use.
Prefer executable clarity over prose. A comment is for a reason or constraint, not a narration of visible code. Documentation is for setup, navigation, cross-cutting concepts, and operational knowledge that does not belong in one symbol.
Before editing, ask:
- Repeatability: could another competent developer reasonably hit the same confusion?
- Payoff: would this repair have shortened the trace without requiring knowledge of this skill?
If either answer is no, continue the original task without manufacturing cleanup.
Zero repairs is a successful outcome when the trace exposed no real smell. The skill rewards reduced future friction, not visible activity.
Do not widen a focused task into an architectural rewrite, add comments everywhere, duplicate facts across documents, preserve temporary task state, create speculative TODOs, or comprehensively document the system. Do not hide behavior changes inside a clarity cleanup.
When the proper repair is too large, risky, or uncertain, do not create a breadcrumb file. State the concrete smell, evidence, and likely repair in the normal handoff so the owner can choose whether to expand scope.
Start at the reference index, or open only the concept needed:
- Knowledge smell catalog. Diagnose the expectation failure and reject false positives.
- Repair patterns. Select the strongest local repair and place knowledge where it naturally belongs.
- Scope and autonomy rails. Decide whether to repair now, verify more, or surface the issue.
- Worked healing examples. Compare weak breadcrumb-like notes with repairs that change the next trace.
- Research basis. Consult the primary evidence behind information scent, explicit contracts, comments, diagnostics, documentation placement, and decision records.
