68 lines
2.5 KiB
Markdown
68 lines
2.5 KiB
Markdown
# Detailed Analysis Contract
|
|
|
|
## First pass: project map
|
|
|
|
Before interpreting architecture, establish:
|
|
|
|
- repository revision/snapshot;
|
|
- build system and top-level build graph;
|
|
- modules and their declared dependencies;
|
|
- runtime applications/entry points;
|
|
- persistence/messaging/cache/object storage/external service adapters;
|
|
- test modules and test types;
|
|
- configuration sources and environment boundaries.
|
|
|
|
The map is evidence, not a taxonomy exercise. Do not infer module responsibilities from names alone; inspect representative source and wiring.
|
|
|
|
## Bounded analysis
|
|
|
|
A bounded scope should be small enough that one run can answer all of these:
|
|
|
|
1. What public/consumed surface does the scope expose?
|
|
2. What does it depend on and why?
|
|
3. How is it wired into a running application?
|
|
4. What state/data does it read or change?
|
|
5. What are its main success and failure paths?
|
|
6. What tests exercise it, and what do those tests actually prove?
|
|
7. What behavior/configuration is declared but not actually connected?
|
|
8. What operational or build-time constraints affect it?
|
|
9. Which observations could become Case/Reference/Question/Decision material later?
|
|
|
|
## Code tracing
|
|
|
|
Prefer symbol/path-based traces over broad summaries. Record exact source anchors in `source-index.md` and analysis prose.
|
|
|
|
Where useful, trace:
|
|
|
|
- inbound request/event/command;
|
|
- DTO/contract mapping;
|
|
- application use case/port;
|
|
- domain invariants/state transitions;
|
|
- transaction boundary;
|
|
- outbound port and adapter;
|
|
- ORM/query behavior;
|
|
- cache/messaging semantics;
|
|
- error translation;
|
|
- logs/metrics/tracing;
|
|
- response/event side effect.
|
|
|
|
## Tests
|
|
|
|
Do not equate a green test suite with a verified architectural claim. For each important test, state what input is exercised, which real components are replaced, and what assertion proves. When a rule is enforced by build configuration or architecture tests, identify the failure point that would catch a violation.
|
|
|
|
## Git history
|
|
|
|
Use history when current code cannot explain why a boundary/decision exists or when a Case depends on an evolution sequence. A current code shape alone proves existence, not historical motivation.
|
|
|
|
## Final synthesis
|
|
|
|
`final/document.md` is not a shortened executive summary. It is the detailed project analysis assembled from bounded documents. Preserve:
|
|
|
|
- measured/observed behavior;
|
|
- failed approaches when evidenced;
|
|
- alternatives actually considered;
|
|
- unresolved questions;
|
|
- explicit decisions;
|
|
- limitations of the analysis;
|
|
- evidence/source references.
|