luochang212/adr-kit/adrkit-review

ADR Kit Review

Review closes the loop between decisions and code: it catches the moment a change quietly stops obeying the record set, before the drift becomes a bug.

Review decision-record coherence for a change, not general code quality. Run adrkit list first, then:

• Compare each changed or newly shipped record with the changed code and tests: claimed paths, names, defaults, mechanisms, and verification evidence must match what actually shipped.
• For actual changes, run adrkit relevant --base <review-base> with the intended exact comparison commit, or adrkit relevant --staged for index-only review; without Git, pass known changed paths explicitly. Git modes preserve deletions and rename origins. Use adrkit show <name> to read matching records in full, supplement scope matches with inventory reading for unscoped decisions, and recheck decisions newly relevant beyond the planned scope. Resolve incomplete-search diagnostics rather than treating partial or zero matches as no constraints.
• Search active implemented records for realization facts the change invalidated — moved files, renamed options, altered defaults, changed behavior — and report each stale record for a factual update in the same change. A decision reversal is a new record with an explicit relationship, never a rewrite of old rationale.
• Check whether a new or maintained record preserves important, otherwise hidden context; weigh importance, impact breadth, longevity, and resistance to becoming stale. Routine upgrade events or visual adjustments are not automatically decisions. An existing record is not precedent for similar records. If repeated synchronization comes only from volatile details, name the burden and their existing owner; suggest trimming details or authorized archival, without silently rewriting constraints or retiring records. Changes within a decision's implementation freedom need no update unless an actual claim becomes false.
• Look for unresolved supersession: a new record that fully replaces an active one without adrkit supersede --by, or a partial overlap that should be linked in prose while both stay active.

Keep a finding's observation and interpretation separate. Cite inspected code (file:line or a symbol), a test you actually ran, or an attributed source. Reproduce before calling a finding confirmed, and leave the failing scenario as an assertion under test/; label what you did not run, and treat a failed reproduction as a narrowed claim, not proof of absence. Record unknowns instead of inventing historical rationale. A confirmed defect is not yet a fix: weigh trigger probability, blast radius, fix cost, and the cost of leaving it, and state plainly any true finding you chose not to fix. adrkit validate checks record validity, not code compliance; scope matching proves neither reading nor compliance.

Report evidence-backed findings that name the record and the code evidence. Finding no issue is a valid result; do not demand a record for a mechanical edit. A disagreement with the decision itself is a design question to raise, not a license to rewrite a historical record. Archived records are lowest-value history that is not read by default: report changes to them rather than editing them silently.