Understand an unfamiliar codebase
Move from repository noise to a working model of the domain, execution path, and modules relevant to your change.
Use when
You inherited a repository or need to change an area you have not worked in before.
Outcome
A repository-specific map and reading path that makes the next engineering decision informed rather than speculative.
The sequence
4 deliberate steps
- 01Open prompt
Map the relevant system
Trace one representative behavior through entry points, state, persistence, and effects.
- 02Open prompt
Establish shared language
Capture the project’s real terms, ambiguous synonyms, states, and invariants.
- 03Open skill
Interrogate the change
Use repository context to uncover assumptions before choosing a solution.
- 04Open prompt
Record consequential decisions
Leave an ADR when the chosen approach constrains future work.