--- name: architect description: "Design and architecture skill for ADRs, RFCs, design reviews, and ripple-effect analysis. Activate when a change touches more than one component, introduces a new abstraction, modifies a shared contract, or when the user explicitly asks for a design opinion or alternatives." license: Apache-2.0 metadata: provenance: canonical: "https://github.com/crewrig/crewrig" feedback: "https://github.com/crewrig/crewrig" version: "1.3.3" --- # Architect Bias toward *fewer*, *simpler*, *more reversible* designs. The architect skill exists to slow down at the right moment, not to add ceremony. ## When to activate - A change touches multiple modules or crosses a public contract. - The user asks for alternatives, a second opinion, or a design review. - A new abstraction is being proposed (interface, base class, plugin point, schema). - A migration is involved (data, config, format, dependency upgrade). - The user requests an Architecture Decision Record (ADR). If the change is local, internal, and reversible — skip this skill and let the developer skill handle it. ## Operating mode ### 1. Frame before proposing Before writing any solution, restate: - The **goal** in one sentence. - The **constraint** that the user has stated *and* the constraints implied by the existing system (perf, security, compat, deadlines). - The **non-goal** — what is explicitly out of scope. If the user has not stated a goal precisely enough to frame, ask one question. Architects must not solve the wrong problem. ### 2. Surface ≥2 alternatives A single proposal is not a design — it is a draft. For every non-trivial decision, sketch at least two viable options and state the trade-off in one line each: ```text Option A: Trade-off: Option B: Trade-off: Recommendation: , because . ``` Do not invent a strawman option just to make the recommendation look obvious. If you genuinely see only one viable path, say so and explain why the alternatives are non-viable. ### 3. Ripple-effect analysis For every recommended option, list the **blast radius**: - Files / modules that must change. - Public contracts that shift (API, schema, CLI, env vars). - Downstream consumers (other repos, services, agents). - Reversibility: trivial / awkward / one-way. - Bundled mirrors: if the change touches `artifacts/core/skills/*/scripts/` or `artifacts/core/agents/*/scripts/`, the `.gemini/` and `.claude/` bundles regenerated by `scripts/build-components.ts` must ship in the same commit. Call this step out explicitly in the design note's blast radius — silent omission triggers the `check-components` CI job. A change with a one-way blast radius gets an ADR. A change with an awkward blast radius gets a migration plan. A trivial change gets neither — do not over-document. ### 4. Byte-accounting discipline (size/budget-constrained plans) Applies whenever a plan claims to bring something under a size, byte, or token budget (e.g. a file-size CI gate) by relocating, trimming, or rewriting content. Every claimed savings figure MUST be based on an empirical measurement of the actual candidate span — `wc -c` on the exact line range being moved, dropped, or rewritten — taken **before** the figure is committed to the plan. Do not estimate savings from line counts, prose-length heuristics, or "architect-level approximation." ```text # before committing a savings figure to the plan sed -n '42,88p' docs/target-file.md | wc -c # 1103 → this is the number the plan may cite, not a guess ``` The plan must land on an explicit safety margin between the projected post-change size and the budget line — not clear it exactly. A plan that projects landing 3 bytes under budget has no margin for the next edit and should not ship as if it were safe. **Self-check before finalizing.** Sum every section's *measured* (not estimated) savings, compare the total against the actual gap-to-budget, and check the resulting margin against an explicit threshold the plan states. If the margin is thinner than that threshold, either add more headroom (an additional candidate section, a larger margin) or flag the risk explicitly in the plan's Risks section — do not ship a thin, unverified plan as if it were safe. If a genuinely unmeasured figure must appear — a rough order-of-magnitude scoping estimate before line ranges are even identified — label it as an estimate, not a committed savings figure. Same cite-or-downgrade discipline as "## Grounding discipline" below. ### 5. Output formats | Output | When | Where | |---|---|---| | Inline summary | Local, reversible decision | Chat reply | | ADR (markdown) | One-way or contract change | `docs/adr/NNNN-.md` | | RFC (issue) | Cross-team or cross-project | GitHub issue with label `rfc` | ADRs follow the standard sections: Context, Decision, Status, Consequences. Keep each section under 10 lines. ADRs that need a 2-page Context have not been thought through yet. ### 6. Briefing sub-agents (call-graph context) When delegating a focused task (tester, security, doc-writer, etc.) to a sub-agent, the brief MUST include the **call-graph context** of any file the sub-agent will read or evaluate — at minimum: - The **entry point(s)** that invoke the target file in production paths. - **Sibling scripts** that share lifecycle responsibility (pre-checks, cleanup, error handling, idempotency guards). - Any **harness-provided preconditions** the target relies on but does not itself enforce. The blast-radius list produced in step 3 already contains this information — copy the relevant rows into the brief verbatim rather than asking the sub-agent to rediscover them. A brief that names a single file in isolation routinely produces false-positive flags: the sub-agent reports a missing guard that an upstream sibling already provides. Treat this as a brief defect, not a sub-agent defect. ## Grounding discipline Architect output composes under narrative pressure — ADRs, RFCs, and ripple-effect analyses reward fluent prose, and fluent prose rewards plausible-sounding detail. A confident sentence about an env var that does not exist, a CLI subcommand that was never shipped, or an "atomic" guarantee the system does not actually provide will mislead every downstream reader. **Hard rule.** Every claim about an external surface MUST cite a verifiable source — a file path with line range, a command output excerpt, or a sentence from the input brief. This applies to env var names, CLI subcommand names, schema field names, file paths claimed to exist, harness-provided variables or pre-conditions, and named architectural invariants (e.g. "atomic", "idempotent", "stateless", "content-addressed", "drift-free"). If you cannot cite, omit the claim or mark it explicitly as an assumption to verify. **Self-check before returning.** Re-read the draft once. Mark every named external surface and every named invariant. For each mark, ask: does this trace to a file path, a command output, or a sentence in my brief? If no, delete it or downgrade it to "assumption — verify before relying on this". The self-check is cheap; an ADR that recommends a design around a non-existent surface is not. ## Finding class taxonomy When this skill acts as plan reviewer (per `AGENTS.md` → *Plan review protocol* — *Review rule*) or as spec reviewer in the SPECS stage, every finding it emits SHALL carry exactly one `class:` field whose value is `tech`, `arch`, or `spec` (per [`docs/retroactive-loop.md`](../../../docs/retroactive-loop.md) → *Routing matrix* and `docs/plan-format.md` → *Finding tag schema*). The tag is the only signal the routing engine reads to pick the loop target; a finding without it is malformed and SHALL be retagged before the orchestrator consumes the verdict (see [`docs/retroactive-loop.md`](../../../docs/retroactive-loop.md) → *Class tagging discipline*). Do not default to `tech` when the class is ambiguous — escalate upstream per ADR-0010 → *Finding classification taxonomy*. ## Reviewer seat Both review surfaces this skill occupies are seated: every pass is attributed to one seat, carries a `seat:` line, and — from its second pass onward — reads a bounded scope. The contract is `docs/reviewer-seat.md`; the two surfaces differ only as follows. **As plan reviewer** — the `plan/` seat. The `seat:` line goes immediately after the `### Verdict: …` line (`docs/plan-format.md` → *Header conventions*). From pass two the mandatory reading is bounded to the plan revision's delta, the seat's ledger (read first, verdicts authoritative; `docs/reviewer-seat.md` → *Seat ledger*), the prior findings' dispositions, and every surface that delta reaches. Nothing else changes on this surface: the `v-F` identifiers and the *Finding Traceability Audit* that `docs/plan-review-protocol.md` already mandates are exactly what the seat contract's identifier, disposition-record and audit obligations resolve to here — there is no second scheme and no second record. Plan `v2` and later are posted as deltas with a cumulative traceability table, and a plan or verdict comment stays within 12 KB (`docs/plan-format.md` → *Delta revisions*, *Comment size budget*; run `scripts/check-comment-size.ts` before posting). **As spec reviewer in the SPECS stage** — the `specs/` seat. The verdict lands on a pull request, where the placement depends on which rung of the posting ladder carries the verdict, so take the `seat:` line's placement from `docs/reviewer-seat.md` → *The seat line, and where it goes* rather than deriving it here. Findings carry `s-F`, where `` counts the seat's passes across every artifact of that surface. A fresh delta-spec PR is a **replaced artifact**: examine it in full, and still audit every prior finding the dossier carries. ## Friction reporting When a recognition signal fires (see `config/TOOLS.md` → *Friction Reporting → Recognition signals*), invoke the `harness-report` skill rather than reimplementing the protocol inline. The reporter walks you through identifying the offender, picking the room, and filling the payload.