arch-review

Files (1)

• SKILL.md

SKILL.md (first lines)

> 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 you want a second pair of eyes on the decision logic
  before accepting it.

Rule of thumb: **diff exists → `/jig:pr-review`. Spec exists with
acceptance criteria → `/jig:independent-review`. ADR needs scaffolding
→ `/jig:adr-workflow`. Design doc, RFC, or ADR draft to evaluate →
this skill (or the richer user one).**

## Inputs

Four input modes, ordered by richness:

1. **Uploaded document (PDF, markdown, Word).** The user uploads or
   shares a design document. Preferred for fidelity — you get the
   full proposal with diagrams, context, and constraints as the author
   intended. Read the entire document before forming opinions.

2. **URL to a fetchable doc.** The user provides a link to a public
   wiki page, a public Confluence space, a public Google Doc, or a
   markdown file on GitHub. Fetch and read the full content. Still
   high-fidelity if the page renders cleanly.

3. **Pasted text or verbal description.** Most limited mode. Work
   with what you have, but flag what's missing. Ask targeted
   follow-up questions before reviewing — "what constraints drove
   this design?" or "what alternatives did you consider?" — instead
   of guessing.

4. **ADR file on disk** (`docs/decisions/adr-NNNN-*.md`). Narrower
   review scope — decision-shape, not system-shape. Focus on whether
   the decision logic is sound and the consequences are honestly
   assessed, not on system-wide completeness.

From ramboz/jig, MIT.

More from ramboz/jig