document-haness/.agents/skills/analyzing-codebase-for-tech-log/references/analysis-contract.md

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.