/arch-review

name: arch-review
description: >
  Team baseline for architecture, design-doc, and RFC review — produces
  summary, strengths, concerns, and open questions. Auto-triggers when
  you say review this design, review this architecture, review this
  proposal, review my RFC, poke holes in this proposal, is this design
  sound, or critique this tech spec. Defers to any other installed skill
  whose description identifies it as handling architecture review,
  design review, RFC review, or technical-design review — if such a
  skill is present, prefer it over this one (jig's version is a slim
  baseline). Does not defer to the generic built-in `review` skill. Do
  not use for: PR/diff review (use `/jig:pr-review` or a richer
  user-installed PR-review skill instead); spec-compliance review of a
  finished slice (use `/jig:independent-review` instead); ADR authorship
  or scaffolding (use `/jig:adr-workflow` — this skill *reviews* an ADR
  draft; it does not create one).
user-invocable: true

> Spec 014 introduced this skill as jig's **team baseline** for > architecture, design-doc, and RFC review. It is the second non-stub > active jig skill that ships without a `.py` helper (after > `/jig:pr-review`, spec 012) — arch-review is fundamentally a judgment > skill, and what little determinism is needed (read the doc, identify > the scope, classify the domain) Claude can run inline. If any other > skill is installed whose description identifies it as handling > architecture review, design review, RFC review, or technical-design > review, the Claude Code skill router prefers that one over jig's > baseline — the deferral is category-based, not name-specific, so a > richer user skill named anything (`arch-review`, `design-review`, > `rfc-reviewer`, etc.) wins. Jig's slim version remains the > auto-trigger when no such skill is installed.

What this skill does

Produces a four-section markdown review of an architecture proposal, a design document, an RFC, or an ADR draft:

1. **Summary** — a two-or-three-sentence paragraph stating what the proposal does and your overall assessment (is it ready to proceed, does it need revisions, does it need rework?). 2. **Strengths** — what the design gets right. Be specific: reference actual decisions, trade-offs the author navigated well, constraints they respected, problems they anticipated. Constructive framing first — acknowledging good thinking helps the author understand what to keep when iterating. 3. **Concerns** — risks, gaps, missing rationale, and unaddressed failure modes. This is the "poke holes" surface. Each concern should be specific to this proposal, not generic advice. Leanness is a first-class concern here: raise over-engineering, premature abstraction, and speculative generality (indirection, config knobs, or extension points with no current caller) when a **simpler architecture** would satisfy the same acceptance criteria — anchored to still meeting them, never stripping required behavior. 4. **Open questions** — things you can't decide from the proposal alone. Ask the author to clarify rather than asserting a gap. Phrase as "help me understand X" not "didn't you consider X".

The review is **breadth over depth**: catch the obvious across any domain, leave the deep multi-persona / domain-specific analysis to a richer user-installed architecture-review skill. If you want a seven-perspective matrix (technical-soundness + operational complexity

• reliability + security + scalability + migration + product impact),

or domain-specific reference files for distributed systems / API design / data architecture / migration plans, jig doesn't ship those — install a heavier skill at the user scope and the router will prefer it.

When to use vs. when to defer

There are four things people often confuse with this skill. Pick the right one:

• **Any other user-installed architecture/design/RFC-review skill.**

Common location: `~/.claude/skills/arch-review/` — but the deferral is **category-based, not name-based**, so a skill named anything (`arch-review`, `design-review`, `rfc-reviewer`, `tech-spec-review`, etc.) whose description claims architecture review, design review, RFC review, or technical-design review will be preferred. If one is present, **defer to it.** The Claude Code skill router should route to the more specific skill automatically; if you want to be sure, explicitly invoke it. The one exception jig's description carves out is the bundled `review` skill — jig:arch-review does **not** defer to that one (it's the generic fallback below jig's baseline, not above it).

• **`/jig:pr-review`** — a sibling jig skill for **PR / diff review**.

Different shape: that one reads a diff and produces scope / blockers / nits / strengths. This one reads a design document and produces summary / strengths / concerns / open questions. Reach for `/jig:pr-review` when there is a PR or branch with a diff; reach for this skill when there is a design doc, RFC, ADR draft, or proposal with no diff to evaluate.

• **`/jig:independent-review`** — a sibling jig skill for

**spec-compliance review** of a finished slice (does the implementation satisfy the acceptance criteria of `spec.md`?). That is a spec-shape review against a written spec. This skill is a **design-shape review** against a proposal. Reach for `/jig:independent-review` when a slice is in REVIEWED-or-similar state with a `spec.md` to evaluate against; reach for this skill when there is a proposal but no acceptance criteria yet.

• **`/jig:adr-workflow`** — orthogonal jig skill for **ADR

authorship and scaffolding** (`/jig:adr-workflow new`, `/jig:adr-workflow accept`, etc.). That skill *creates* an ADR; this skill *reviews* an ADR draft. Reach for `/jig:adr-workflow` when you need to scaffold a new decision record or move one through its lifecycle states; reach for this skill when the ADR exists and y