code-analysis

Topics in the source

• Code analysis
• 1. Read the outside before the inside
• 2. Find the spine
• 3. Let the repository tell you where the risk is
• 4. Assess structure honestly
• 5. Report as a map with a recommendation
• Rules

The output is a map: what exists, how it fits together, and where the danger is. A map is judged by whether someone can navigate with it, not by how much of the territory it mentions. Analysis fails by exhaustiveness — describing every module at equal depth produces a document with the same information density as the source, and no reason to read it. Depth must be unequal, concentrated where the risk and the change is. Before opening source files, read what the project says about itself and what it demonstrably does: README, entry points, public API or route definitions, configuration, CI pipeline, dependency manifest, and the shape of the test suite. This gives you the intended architecture. The gap between it and the real one is a finding. Done when: you can state what the system does, who calls it, and what it calls. Every codebase has a small number of paths that carry most of the value. Trace one all the way through — a request from entry to response, a job from trigger to side effect. Follow it end to end before branching. The spine teaches you the project's real conventions, its layering, and where its abstractions leak, far faster than reading modules in isolation. Done whe

This is an excerpt. Refer to the complete source and its current requirements.