134 lines
5.1 KiB
Markdown
134 lines
5.1 KiB
Markdown
# 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.
|