architecture-review

Architecture review

Code review at the line level is mostly noise once linters and type checkers are in place. The leverage is at the structure level — what was built and how the pieces fit.

When to apply

• End of a feature commit-set, before merging or requesting human review.
• When the diff touches multiple modules and the agent suspects the shape might be off.
• When the user asks for a "second pass" or "review."

Skip for single-file fixes, typo corrections, dependency bumps, and other diffs where structure isn't in question.

What to review

In order of priority:

1. Are responsibilities placed correctly? Did logic land in the layer that owns the concern, or did it leak into a layer that shouldn't know about it?
2. Does this fit the existing patterns? New code that diverges from the codebase's style for no reason creates drift. Either conform, or change the pattern intentionally and document why.
3. What's the public surface? New flags, exports, routes, config keys, log messages. Are any of them temporary scaffolding that should be private?
4. What got added that could be deleted? Premature abstractions, defensive checks for impossible scenarios, "future-proof" hooks with no caller. (See continuous-refactor.)
5. Are the tests testing behavior or implementation? Tests coupled to implementation make refactors expensive.

What not to review

• Formatting (the formatter handles it).
• Lint nits (the linter handles them).
• Type issues (the type checker handles them).
• Subjective style preferences with no reasoning.

If you find yourself writing "could maybe be cleaner if…" with no concrete why, delete it.

Output

A short structured report:

• Structural concerns — bullet list, with file:line references.
• Public surface notes — anything new that's user-visible.
• Suggested follow-ups — separately from blocking concerns.

Bias toward fewer, higher-signal items. A 30-bullet review gets skimmed; a 5-bullet review gets read.

Pairs with design-before-architecture-changes

That skill fires before implementation and names what should be built; this one fires after and checks whether what shipped matches that intent. If a design wasn't done up front (because the change didn't qualify), the review still happens — judge the structure on its own merits.

Exit condition

The structural review has been written. Concerns are either addressed in the same branch or captured as follow-ups for continuous-refactor.