§ reference · skill

architecture-review

Conducts a top-down, layer-by-layer architecture review of a module and produces a phased polish plan in `.rpiv/artifacts/architecture-reviews/` that starts the polish pipeline.

arguments [target path: file, directory, or module]

§ 01 · purpose

Purpose

Audits a whole module *structurally*: every file read fully, a uniform ten-dimension sweep per layer, every candidate finding triaged with the developer. It consolidates the accepted findings into a phased polish plan sized by agent-relevant signals. Language-agnostic: TypeScript, Java, .NET, Rust, Python, Go, or any other typed module.

§ 02 · when to use

When to use it

Before a 1.0 release, after a major refactor, or when a module has grown enough to warrant a structural audit.
You want a durable, phase-by-phase polish plan that blueprint can consume one phase at a time.
Re-invoke for a fresh artifact when the target has materially changed (new files, restructured layers). Follow-ups only append.
Prefer blueprint directly when you already know the one change to make. The review earns its cost by surfacing findings across a whole module.

§ 03 · inputs

Inputs

Name	Required	Source
`target path`	no	Free-text (a file, directory, or module)

target path: Empty input triggers a developer question to identify the target (module, subdirectory, single file). The target's manifest and README seed the context.

§ 04 · outputs

Outputs

Artifact	Path	Format
Architecture review with consolidated polish plan	`.rpiv/artifacts/architecture-reviews/`	markdown with machine-readable `phases:` frontmatter (`n`, `title`, `depends_on`, `blast_radius`, `effort`), per-layer findings, tallies, methodology principles, and cross-cutting themes

§ 05 · key steps

Key steps

Capture the target's real shape first Why: Layers must mirror actual dependency direction. Manifest, import graph, and a full file enumeration reveal it; guessed role buckets would bias the whole walk.
Propose the layer split and get it approved before anything is written Why: The entire review walks the approved layers top-down (facade at Layer 0, persistence last), so a wrong split poisons every subsequent finding. The developer approves it before the skeleton artifact exists.
Write the skeleton once, then edit progressively Why: The artifact is the durable record between sessions. Each triaged finding is persisted the instant the developer decides, so an interruption never loses triage work to a deferred batch write.
Per layer, read fully, sweep ten dimensions, triage every candidate Why: Selective reads bias findings toward what happened to load, and a candidate that cannot cite file:line plus a quote is not a finding. The developer, never the skill, judges abstraction value, so a zero-consumer deletion is always offered a keep option too.
Capture emergent methodology principles and cross-cutting themes Why: Principles surface from triage itself (a reversed finding, a repeated choice), never from a pre-baked list. Naming them before theme synthesis is what lets the themes inherit the developer's actual reasoning.
Assemble the phased polish plan by agent-relevant signals Why: Phases are sized for blueprint (finding counts, files touched, blast-radius mix, coordination need), not human-day estimates. Findings are topo-sorted so a rename lands before the directory split that uses the new name.
Hand off one phase at a time Why: Per-phase blueprint invocations are the supported chaining pattern, and whole-artifact handoffs are explicitly not. The machine-readable phases: array is what drives the polish pipeline's per-phase iteration.

§ 06 · related skills

downstream blueprint plan