Architecture Designer

---
name: architecture-designer
description: Design or redesign system structure from an inspection of the current code and architecture. Produce component, dependency, and data-ownership maps, tradeoffs, an architecture decision record (ADR) draft, and an incremental migration plan. Use for structural feature or system decisions. Do NOT use to choose the architecture style (architecture-advisor), design tenancy (saas-platform-architect), model domain concepts (domain-modeler), or record an already-made decision (adr-writer).
---

# Architecture Designer

Here, **CI** means continuous integration and **deps** means dependencies.
An **ADR** is an architecture decision record for a pivotal choice.

## Purpose

Produce a target architecture that is reachable from the real current one.
The deliverable is a set of maps (components, dependencies, data ownership),
named risks, an explicit tradeoff analysis, an ADR draft for the pivotal
decision, and a migration plan in reviewable increments. Designing from the
actual codebase — not from how the README says it works — is the core
discipline; the most expensive architecture documents are the ones describing
a system that does not exist.

## Use When

- Use when: asked "how should we structure X" — a new feature with structural
  weight, a subsystem redesign, a monolith/module/service question.
- Use when: a new integration or dependency needs a home and a boundary.
- Use when: a proposed change would alter who owns data or which direction
  dependencies point.
- Do NOT use when: the business concepts themselves are unclear — run
  `domain-modeler` first; structure follows meaning.
- Do NOT use when: the decision is already made and needs recording — that is
  `adr-writer` (this skill hands its ADR draft there).
- Do NOT use when: judging an existing design without proposing one — delegate
  to the `principal-architecture-reviewer` subagent.
- Do NOT use when: designing job retry, scheduling, or idempotency semantics —
  hand those to `background-job-orchestration-architect`.
- Do NOT use when: choosing the architecture style — that is
  `architecture-advisor`; this skill produces the concrete structure.
- Do NOT use when: designing tenancy — that is `saas-platform-architect`;
  this skill handles structure with no tenancy dimension.

## Inputs to Inspect

1. The actual code layout: top-level modules/packages, entry points, and the
   import/reference graph between them (sampled, not assumed).
2. Build and deploy artifacts: what actually ships together (workspaces,
   Dockerfiles, CI jobs) — deployment units are architecture facts.
3. Schema and data access: which modules read/write which tables or stores.
4. Existing ADRs, architecture docs, and diagrams — as claims to verify
   against the code, not as ground truth.
5. The domain model, if one exists; run `domain-modeler` first if core
   concepts are undefined.
6. Nonfunctional constraints stated by the human: scale, latency, team split,
   compliance, budget.

## Workflow

1. **Inspect current state first.** Map the real components, their
   dependencies (including direction), and data ownership from code and
   config. Where docs contradict code, record the drift as a finding.
2. **State the forces.** What is this design being asked to optimize —
   change isolation, team autonomy, latency, cost, operability? Rank them;
   an unranked list decides nothing.
3. **Draft the target component map:** components, responsibilities, allowed
   dependency directions, and the contract at each boundary (sync call,
   event, shared table — be honest about the last one).
4. **Assign data ownership:** every store/table gets exactly one owning
   component; readers go through its contract. Flag shared-write tables as
   the risks they are.
5. **Name coupling and cohesion risks** in the target: cycles, god
   components, chatty boundaries, distributed transactions, hidden coupling
   through the database.
6. **Run the tradeoff analysis:** at least two viable options compared across
   complexity, delivery speed, operability, cost, reversibility, and failure
   modes. Recommend one; say what would change the recommendation.
   Before asking the user to choose a build option, define unfamiliar terms,
   explain why each option is viable, and give case-specific pros and cons.
   Separate money, setup effort, delivery time, and ongoing upkeep; use $0
   when there is no direct purchase cost and label uncertain figures. Explain
   why the recommendation fits this system and team. End the choice
   presentation with one clear owner decision question; do not pick the
   option silently.
7. **Draft the ADR** for the pivotal decision (context, decision,
   alternatives, consequences) — hand to `adr-writer` for completion with
   rollback plan and review date. Steps 7–8 are drafted for the recommended
   option and marked pending the owner's answer.
8. **Write the migration plan:** ordered, individually shippable increments
   from current to target, each with a verification step and a stop point.
   "Big-bang rewrite" is not a migration plan.

## Output Format

```
ARCHITECTURE DESIGN — <scope>
Current state (inspected): components, dependencies, data ownership;
  drift found between docs and code
Forces (ranked): <what this design optimizes, in order>
Target component map: <component — responsibility — allowed deps — boundary contract>
Data ownership map: <store/table → owning component; flagged shared writes>
Coupling/cohesion risks: <each with consequence>
Options considered: <plain-language meaning and reason for A vs B (vs C);
  pros/cons; money, setup, delivery-time, upkeep costs; complexity,
  reversibility, failure modes>
Recommendation: <option + why it fits + what would change it>
ADR draft: <context, decision, alternatives, consequences> → adr-writer
Migration plan: <increment → verification → stop point>, order matters
Assumptions & open questions: <each with risk-if-wrong / who answers>
```

## Validation Checklist

- [ ] Current-state map cites real files/modules inspected — not reconstructed
      from docs or memory.
- [ ] Doc-vs-code drift, if found, is listed as a finding.
- [ ] Every target boundary names its contract type; shared-database coupling
      is declared, not hidden.
- [ ] Every data store has exactly one owner in the target map.
- [ ] At least two options genuinely compared; the recommendation names its
      reversal condition.
- [ ] Any user-facing build choice explains terminology, reason for each
      option, pros/cons, costs including time and upkeep, and the recommended
      fit before asking the user to decide.
- [ ] Migration plan increments are individually shippable and verifiable.
- [ ] No implementation performed — this skill designs; it does not restructure
      code.

## Gotchas

- The README architecture and the import graph disagree more often than not;
  the import graph is the one running in production.
- "Extract a service" answers a team/deployment problem, not a code-quality
  problem — check which one the human actually has.
- Two components sharing write access to one table are one component with
  extra steps; no diagram fixes that until ownership is assigned.
- Designing for imagined scale adds real complexity for hypothetical load;
  tie every scale-driven choice to a stated number.
- A migration plan whose first increment is "refactor everything" will never
  ship increment two.

## Stop Conditions

- Core domain concepts are undefined or contested → stop; run
  `domain-modeler` (or `source-of-truth-reconciler` if sources conflict).
- The design would change security, tenant-isolation, or data-handling
  posture → surface via `human-approval-boundary` before recommending.
- Constraints are missing that would flip the recommendation (team size,
  latency budget, compliance) → ask; do not pick a default silently.
- The human asks to implement the design in the same pass → the migration
  plan's increment 1 becomes a separate, scoped task; confirm before touching
  code.

## Supporting Files

- [references/architecture-artifacts.md](references/architecture-artifacts.md) —
  quality bars for each map, contract-type catalog, tradeoff table template,
  and migration-increment patterns.
- `evals/evals.json` — trigger + behavior cases.
- `evals/trigger-evals.json` — discrimination against `domain-modeler` and
  `adr-writer` (design cluster).