learn-codebase

Get productive in an unfamiliar codebase with a structured, disk-backed workflow — not a one-off "draw me a map" prompt. Orientation only: for an honest feature inventory and test pass on a shipped product, use quality-loop.

Setup

Leave the app repo; create a sibling workspace for learning notes. If you're already inside the app repo with a map-only prompt, stop — relocate. A directory map is not understanding.
Declare an honest experience level at the top of MISSION.md — newcomer, practitioner, or expert. Under/overclaiming breaks the depth calibration below.
Work the repo in leveled passes; advance a level only when you can predict behavior (see prove-it):
- Newcomer: entry points, README, one end-to-end trace (request → data → UI).
- Practitioner: data flow, test suite, team conventions.
- Expert: edge cases, failure modes, the why-nots in the design.
Keep state on disk (so clearing the session is safe):
- MISSION.md — learning goal + success criteria (re-read when lost)
- NOTES.md — what you know / don't
- RESOURCES.md — primary sources (official docs, links) found so far
- lessons/ — leveled lessons + shared exercise assets
- reference/glossary.html — return doc
- learning-records/ — progress state across clears
Do the leveled passes above. Then prove it (reading ≠ learning): edit, run, and predict outcomes — e.g. add a console.log("LOADER RAN") in a loader and console.log("COMPONENT RAN") in a component; predict terminal vs browser; run and notice surprises. Do the edit when the pass calls for it.