skills/repo-scout/references/architecture.md

# Architecture and cross-layer behavior

Draw a textual map from observed entry points to modules, services, persistence and
external systems. Read relevant ADRs before judging a design. Check dependency
boundaries, circular coupling, shared mutable state, lifecycle ownership, contract
versioning, transaction boundaries, cancellation and failure propagation.

Trace at least one important user journey across layers: for example UI action →
API/request → authorization → storage transaction → returned state → UI recovery.
Exercise the reasoning at retry, timeout, cancellation, duplicate submission,
partial success, offline operation and process restart boundaries. Check whether
frontend assumptions match backend guarantees and whether platform clients agree
with the same protocol. Do not infer cross-layer coverage from isolated unit tests.

Useful findings have consequences: inaccessible recovery, data-loss paths, incompatible
schema changes, confusing ownership that causes repeated bugs, or a demonstrated
hot-path cost. Folder layout preferences, repository size and the mere absence of
DDD/Clean Architecture are not findings. A monolith is not automatically wrong.

For a refactor proposal, name the current pain, affected change workflow, smaller
alternative, migration plan and rollback, and explain why benefit exceeds churn.
Large architecture changes belong in a decision proposal, not an automatic repair.