batteryshark Architecture for comprehension
Assess whether a motivated engineer can build an accurate mental model of the system without holding unnecessary detail in their head.
Workflow
- Define the review boundary and the engineer persona whose comprehension matters.
- Inventory the repository, manifests, entry points, source roots, tests, and architecture documents. Run
bin/architecture-for-comprehension <repo>for a deterministic first map. - Build a factual system map of major responsibilities, ownership boundaries, entry points, stores, external services, and generated or operational surfaces. Mark ambiguous ownership rather than guessing.
- Trace the smallest complete execution path that explains the system: entry point, control flow, data transformations, state, side effects, and output.
- When onboarding matters, run a bounded newcomer probe with
references/onboarding-probe.md. Observe where setup, execution, navigation, and safe-change reasoning break down. - Check whether structure, names, documentation, configuration, tests, and runtime behavior describe the same system.
- Evaluate the dimensions and finding taxonomy in
references/review-rubric.md. Keep an uncertainty register for conclusions whose rationale, ownership, or hazard cannot be established locally. - Recommend the smallest changes that reduce global cognitive load. Keep local style findings out unless they damage the system model.
Evidence rules
- Separate observed facts from inference.
- Attach each finding to files, symbols, execution paths, or missing links between them.
- Treat unclear rationale as uncertainty, not proof of poor design.
- Describe tradeoffs under their likely constraints; do not declare an architecture correct from aesthetics alone.
- Raise a question when an important conclusion depends on author intent that the repository cannot reveal.
Output
Report:
- A short system model and the path used to derive it.
- What currently helps comprehension.
- Findings ordered by cognitive cost, with evidence and confidence.
- Coherence gaps and observed onboarding friction.
- Important unknowns, the evidence needed, and exact owner questions.
- A minimal sequence of improvements, including what not to change casually.
For an independent review, pass agents/reviewer.md to a subagent with the repository path and review boundary. Use agents/onboarding-tester.md for a fresh newcomer probe.