architect

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:

Option A: <approach>
  Trade-off: <what A buys, at the cost of what>
Option B: <alternative>
  Trade-off: <what B buys, at the cost of what>
Recommendation: <A or B>, because <the constraint that breaks the tie>.

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.sh 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."

# 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

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 specs/0005-retroactive-routing-engine.md R2 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 → Class tagging discipline). Do not default to tech when the class is ambiguous — escalate upstream per ADR-0010 → Finding classification taxonomy.

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.