5.1 KiB
Deep Analysis Standard
This is the completion standard for one bounded module/subsystem. A run may stop mid-scope, but it may not mark the scope complete until every gate below is satisfied.
1. Quantified scope map
Measure before interpreting. Record at least when applicable:
- module/leaf path and declared dependencies;
- production file count and approximate LOC;
- package/directory count and top-level children;
- public interfaces/ports;
- entities/tables/repositories;
- migrations and independent migration streams;
- unit/integration/contract/performance/architecture test counts;
- runtime memberships/entry applications;
- major feature flags/config namespaces.
Do not claim "fully read" without a countable denominator.
2. Coverage ledger
Create a ledger for the selected scope. Every materially relevant file or coherent file group receives one disposition:
FULL_READ— contents read and incorporated into analysis;STRUCTURAL_ONLY— structure/signature inspected because internals add no further information;EXCLUDED— intentionally outside this document, with concrete dependency/ownership evidence explaining why.
Record counts by disposition. A scope cannot be COMPLETE while relevant files are UNCLASSIFIED.
3. Architecture reconstruction
Reconstruct from code rather than names:
- why the module exists and what it explicitly is not;
- package/component ownership;
- allowed and observed dependency edges;
- source dependency versus runtime call flow;
- composition-root wiring and conditional activation;
- build/ArchUnit/registry gates and the exact failure point;
- optional/experimental/stable boundaries.
If a design document says one thing and the current code says another, record the drift; do not silently reconcile it.
4. Contract and invariant extraction
For important types/functions/configuration, identify:
- constructor/type invariants;
- bounds, allowlists, fail-closed behavior;
- state machines and legal transitions;
- transaction/retry/idempotency semantics;
- concurrency and lifecycle assumptions;
- security/privacy/redaction constraints;
- database/provider-specific behavior.
Prefer the exact enforcing code path over a generic explanation.
5. Success and failure mechanics
For each major capability, cover both:
- normal execution path;
- material failure paths and their translation/recovery behavior.
Look for silent failure modes: configuration that looks enabled but is not wired, green tests that replace the real failing component, unused beans/classes, fallback behavior that hides typos, provider differences, partial migration states, cache coherence assumptions, or retry paths that production never calls.
6. Tests as evidence
Inventory test lanes and explain what they prove. For important claims, identify:
- test class/path;
- real versus replaced components;
- input/fixture;
- decisive assertion;
- what remains unproved.
Run safe tests or focused probes when needed. Do not infer production behavior solely from test names.
7. History and rationale
Use comments/docs/Git history when needed to distinguish:
- current fact;
- explicit historical rationale;
- inferred rationale;
- old behavior/bug;
- fix and regression guard.
Preserve useful failure history. A bug fix is more valuable when the document explains why the bug was possible and what now prevents recurrence.
8. Static reachability and wiring checks
For major abstractions and registered components, check whether production code actually consumes them. Search injection sites, references, registration, conditional imports, and runtime membership. Record:
- active path;
- duplicate path;
- dead/unwired path;
- configuration mismatch;
- declared capability with insufficient evidence.
9. Runtime / database evidence
When safe and useful, verify claims with the real engine/runtime rather than an in-memory substitute. Preserve command/output in raw evidence and render terminal UI only from that captured output. State the environment and what the result does not generalize to.
10. Improvement backlog
End each completed bounded analysis with findings discovered while reading. Prioritize P0/P1/P2/P3 (or justify another scheme). Each item should contain:
- fact/evidence;
- why it matters;
- exact verification command/test;
- candidate options when supported;
- whether it belongs to Case, Reference, Open Question, or Decision later.
Do not invent a defect merely to fill this section. An empty backlog is allowed if the evidence supports it.
11. Completion gate
A bounded scope is complete only when:
- quantified scope denominator exists;
- coverage ledger has no unclassified relevant items;
- top-level package/component map is accounted for;
- build/runtime wiring is traced;
- important invariants and failure paths are documented;
- tests and evidence are mapped to claims;
- explicit rationale is separated from inference;
- dead/unwired/duplicate paths were checked;
- limitations and excluded areas are stated;
- improvement backlog was considered.
If this cannot fit reliably in one run, keep the scope IN_PROGRESS and continue it on the next scheduled run. Never lower the depth standard to finish on schedule.