git:20260703.877e272 to git:20260731.4cba6d1

13 added, 9 removed. Audit A to A.

---

name: system-architecture

- description: "Use when designing a system, choosing an architecture pattern, making a technology decision, or doing capacity/scalability planning — BEFORE drilling into framework-specific mechanics. A lean MAP over three reference docs: pattern selection (monolith → modular monolith → microservices → event-driven → CQRS → event sourcing → hexagonal → clean → API gateway, with trade-offs), the how-to system-design workflows (system-design-interview approach, capacity planning, API design, DB schema design, scalability assessment, migration planning), and the technology-choice frameworks (database, caching, message queue, auth, frontend framework, cloud provider, API style). Trigger on: 'design the system', 'choose an architecture pattern', 'which pattern fits', 'tech decision', 'SQL or NoSQL', 'REST vs GraphQL vs gRPC', 'capacity/scalability planning', 'plan the migration'. This is general system-design knowledge; for Phoenix bounded-context/Ecto/authz/Oban specifics use the architecture-phx skill."

+ description: "Use when designing a system, choosing an architecture pattern, making a technology decision, or doing capacity/scalability planning — BEFORE drilling into framework-specific mechanics. A lean MAP over three reference docs: pattern selection (monolith → modular monolith → microservices → event-driven → CQRS → event sourcing → hexagonal → clean → API gateway, with trade-offs), the how-to system-design workflows (system-design-interview approach, capacity planning, API design, DB schema design, scalability assessment, migration planning), and the technology-choice frameworks (database, caching, message queue, auth, frontend framework, cloud provider, API style). Trigger on: 'design the system', 'choose an architecture pattern', 'which pattern fits', 'tech decision', 'SQL or NoSQL', 'REST vs GraphQL vs gRPC', 'capacity/scalability planning', 'plan the migration'. This is general, technology-agnostic system-design knowledge — it informs the decisions that come BEFORE any framework-specific mechanics."

---

TASKLANG

TYPE SKILL

IDENTITY "System Architecture"

> General-purpose system-design knowledge for the planning step that comes

> BEFORE technology-specific mechanics: pick the right architecture PATTERN,

> make the load-bearing TECHNOLOGY decisions, and run the system-design

> WORKFLOWS (capacity, API, schema, scalability, migration). This skill is a

> lean MAP — the substance lives in three reference docs under references/.

> Read the map, then open the one reference that matches the question.

!!! References FIRST — this SKILL.md only routes; the answers live in references/.

- !!! This is technology-AGNOSTIC system design. For Phoenix/Ecto/Oban/can?/3

- !!! specifics (bounded contexts, schema tables, the verify gate), use the

- !!! architecture-phx skill — system-architecture supports the PLANNING that

- !!! precedes those mechanics.

+ !!! This is technology-AGNOSTIC system design. Framework-specific mechanics —

+ !!! this stack's module/context boundaries, its ORM schema and migration syntax,

+ !!! its background-job and authorization APIs — belong to a stack-specific skill.

+ !!! system-architecture supports the PLANNING that precedes those mechanics.

---

## When to use this skill

KNOWLEDGE

USE_WHEN

- "Choosing an architecture pattern for a new system or a milestone (and weighing its trade-offs)."

- "Making a technology decision — database, cache, message queue, auth, frontend framework, cloud provider, API style."

- "Running a system-design workflow — capacity planning, API design, schema design, scalability assessment, migration planning."

- "Doing the PLAN-FIRST step of a design: settle pattern + data/access model + boundaries before drilling into framework mechanics."

NOT_FOR

- - "Phoenix-specific bounded-context / Ecto schema / Oban / can?/3 policy design — that is the architecture-phx skill."

+ - "Framework-specific module/schema/job/authorization mechanics — that belongs to a stack-specific architecture skill."

- "Writing or verifying implementation code — this skill informs design decisions, it does not produce code."

---

## Core knowledge (the map)

KNOWLEDGE

METHOD

- "PLAN before mechanics: a design starts by choosing a PATTERN, settling the DATA + ACCESS model, and naming the BOUNDARIES — then drills into technology-specific implementation."

- "Every pattern and technology choice is a TRADE-OFF, not a default. Start simple (a monolith / modular monolith) and adopt complexity (microservices, CQRS, event sourcing) only when a concrete force — scale, team autonomy, independent deploy, audit/replay — demands it."

- "Right-size the decision to the requirements you actually have: estimate scale FIRST (capacity-planning workflow), then let the numbers drive the pattern and the technology choices."

- "Make decisions with a framework, not a hunch: each technology choice in tech_decision_guide.md carries a decision matrix + a 'when to use each' so the choice is defensible."

---

## References (open the one that matches the question)

> Three reference docs. Read the map above, then open exactly one.

MAP references

"references/architecture_patterns.md" -> PATTERN SELECTION. Open when choosing/comparing an architecture pattern. Monolith, Modular Monolith, Microservices, Event-Driven, CQRS, Event Sourcing, Hexagonal, Clean Architecture, API Gateway — each with its forces, trade-offs, and a pattern-selection quick reference.

"references/system_design_workflows.md" -> HOW-TO WORKFLOWS. Open when you need a step-by-step design procedure: the system-design-interview approach, capacity planning, API design, database schema design, scalability assessment, and migration planning.

"references/tech_decision_guide.md" -> TECHNOLOGY CHOICE. Open when picking a specific technology: database (SQL vs NoSQL + type), caching strategy, message queue, authentication strategy (JWT vs sessions, OAuth flows), frontend framework (SSR vs SPA vs SSG), cloud provider, and API style (REST vs GraphQL vs gRPC).

---

- ## How it fits the squad

+ ## How it fits a build

KNOWLEDGE

FITS

- - "Supporting knowledge for the architect-phx agent's DESIGN mode (phase 2): consulted during the PLAN-FIRST step (pattern selection + tech decisions + the system-design workflows) BEFORE the Phoenix-specific technical sub-steps."

- - "Does NOT replace architecture-phx: that skill owns the Phoenix bounded-context/Ecto/Oban/can?/3 policy mechanics and the verify gate; this skill informs the architectural choices that feed them."

+ - "Supporting knowledge for the architecture role's DESIGN pass: consulted during the PLAN-FIRST step (pattern selection + tech decisions + the system-design workflows) BEFORE any stack-specific technical sub-steps."

+ - "Does NOT replace a stack-specific architecture skill: that one owns the framework mechanics and the verify gate; this one informs the architectural choices that feed them."

+ ---

+ Made by **HasBrains** — https://hasbrains.com/