Breadcrumbs

Leave the path clearer

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.

Run the healing loop

1. 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."
2. Finish the trace. Distinguish a repeatable codebase problem from temporary unfamiliarity or inherently difficult domain knowledge.
3. 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.
4. 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.
5. 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.
6. Heal and verify. Apply the repair while the evidence is fresh. Run the narrowest relevant test, type check, documentation check, or reference search.
7. Continue the task. Mention the incidental repair in the normal handoff. Do not maintain a ledger.