architect

---
name: architect
description: >-
  Guides architecture decisions about service/module boundaries, system
  trade-offs, ADRs, data flow, rendering strategy, scaling strategy, API
  protocols, persistence choices, and code organization. Use when the user asks
  "how should I structure this", "what's the right approach", or needs a
  decision that affects multiple modules, teams, deployment boundaries, or future
  reversibility. Do not use for routine React implementation, PR review, or
  simple refactors unless the user is making an architectural decision.
---

# Architect

## Methodology: Walk the Decision Tree

Architecture is about trade-offs, not best practices. Gather enough context to
make the decision explicit, then present options.

- Ask only if the answer is blocking; otherwise inspect the codebase or state
  assumptions
- Ask one focused question at a time when clarification is required
- Provide your recommended answer for each blocking question
- Resolve dependencies between decisions sequentially — don't jump ahead

Gather at minimum:
- **What exists today** — greenfield or evolving an existing system?
- **Scale** — users today, projected in 12 months
- **Team** — size, expertise, operational maturity
- **Trigger** — why now? pain point, new feature, scale issue?
- **Constraints** — budget, timeline, compliance, existing infrastructure

Then present **2–3 options with explicit trade-offs** — never a single "right answer."

## Reference Files

Load the relevant reference file based on context. Read only what the conversation needs.

| Priority | Load when | Reference |
|---|---|---|
| 1 — High | Code organization, module design, why codebase feels hard to change | `references/design-principles.md` |
| 1 — High | Why code is hard to maintain, identifying what to refactor, when to refactor | `references/code-smells.md` |
| 2 — High | Service boundaries, API contracts, BFF, fullstack performance antipatterns | `references/fullstack-patterns.md` |
| 2 — High | Component architecture, state management, rendering strategy, frontend performance | `references/frontend-patterns.md` |
| 3 — Medium | Build/buy, monolith/services, SQL/NoSQL, sync/async, ADRs, C4 diagrams | `references/decision-artifacts.md` |
| 3 — Medium | "What structural pattern should I use?", plugin systems, composing/adapting systems | `references/patterns-structural.md` |
| 3 — Medium | Communication patterns, event-driven design, state machines, encapsulating algorithms | `references/patterns-behavioral.md` |

## Complexity Red Flags (Diagnose First)

Before recommending a solution, identify the symptom. These are fast first-pass signals.

**Ousterhout's 3 complexity symptoms:**
- **Change amplification** — one logical change requires edits in many unrelated places
- **Cognitive load** — developer must hold too much context to make a change safely
- **Unknown unknowns** — it's not obvious what must change when something else changes

**Architecture-level smells (Fowler):**
- **Shotgun Surgery** — one change touches many unrelated files → missing abstraction or wrong boundary
- **Divergent Change** — one module changes for many unrelated reasons → SRP violation
- **Feature Envy** — a function/hook is more interested in another module's data than its own → wrong ownership

If you see these symptoms, load `references/code-smells.md` or `references/design-principles.md`.

## Quick Decision Checks

- **Rendering strategy:** use `references/frontend-patterns.md` for CSR/SSR/SSG/ISR/RSC/Streaming/Edge trade-offs.
- **API protocol:** use `references/fullstack-patterns.md` for REST vs GraphQL vs gRPC.
- **Durable decision record:** use `references/decision-artifacts.md` for ADRs and C4 diagrams.

Adding architectural complexity has real costs: slower iteration, operational
burden, hiring requirements. Evaluate whether the complexity is paid for at
current scale.

## Output Contract

End with:

1. Recommendation
2. 2–3 alternatives considered
3. Trade-offs and risks
4. Assumptions
5. Next concrete step
6. ADR draft only if the decision is hard to reverse

More agent context in kriscard/Skills

46 other files this repository gives its agents.