---
model: opus
---

# /tas-sad $ARGUMENTS

Role: SE - Software Engineer
Create or update Solution Architecture Document.

## Prerequisite
- docs/prd.md must exist. If not, notify user to run /tas-prd first.

## Gate (run first)
If `workflow.gate_enforcement: true` in `tas.yaml` (default true): require `docs/prd.md` frontmatter `artifact-status: approved` — grep only the `artifact-status:` line. Missing or not `approved` → **STOP**: "🚫 Gate: /tas-sad needs PRD approved (docs/prd.md artifact-status = {value}). Set it to `approved`, or set `workflow.gate_enforcement: false` for solo mode." If `false` → skip.

## Actions
1. Need context from root/tas.yaml for project info, workflow config
2. Need context from docs/prd.md to understand requirements
3. If brownfield: need context from docs/codebase-overview.md if available
4. Check if docs/sad.md already exists:

### CREATE mode (file doesn't exist):
5. Need context from .tas/templates/SAD.md
6. Create file docs/sad.md per Torus SAD template
7. **Derive modules and components from FRs (WHAT → HOW)** — this is the core of the SAD. For each FR in the PRD, decide which **modules** realize it, then fill **§7 Module & Component** — one subsection per container with (A) a **module table** and (B) a **component table**. Each module gets a stable global `MOD-NN` ID (responsibility, the interface it provides, dependencies → MOD-IDs or container/external names + protocol, FRs). Then decompose each module into its **components** — the architecturally significant building blocks (controller, service, adapter, repository, gateway…), each with a module-prefixed ID `MOD-NN.C#`, a responsibility/interface, and the FR(s) it serves. Keep components to significant blocks (2-6 per module), NOT every class/file. The **mandatory zoom diagram** shows components as nodes labelled with their IDs (grouped by module + internal wiring + inbound callers + outbound calls, with protocols). Describe components concretely enough that feature breakdown can map each Feature to the exact component(s) it builds.
   - **Verify coverage (component-level — the "never missed" guarantee)** using the component tables: every component (`MOD-NN.C#`) belongs to a module and lists ≥1 FR (or `infra — reason`); every FR is realized by ≥1 component; every module owns ≥1 component. A component with no FR/infra, an FR with no component, or a module with no component is a gap — add the missing piece before continuing.
   - **Traceability gate (component coverage):** if any component lacks an FR and an `infra` justification, OR any FR has no component, OR any module has no component: SAD `artifact-status: draft` → emit a ⚠ warning listing the gaps and continue; SAD `artifact-status: approved` → **hard-block**: do not finalize until coverage is clean. (Run the `coverage-auditor` agent to produce the pass/fail report the SE approves on — see `.tas/agents/coverage-auditor.md`.)
   - **System Context → external actors from BRD.Actor** — populate §5 externals from BRD's `AT-NNN` of type "External system" (each keeps its `AT-NNN`); do not invent externals with no BRD Actor. Human actors are represented via their PRD Persona, not listed here.
   - **Data Architecture** — model the PRD entities technically using their `E-NNN` codes (Domain Model: key attributes + accurate cardinality; ERD; Data Classification; Retention Policy). Stop at schema level — indexes/partitions/per-feature columns belong to Feature Technical Plan.ERD Delta.
   - **Integration Contract → Integration Contract Registry** — register every cross-module and external contract with an `IC-NN` ID (+ its Producer MOD). These are the stable anchors a Feature Technical Plan copies into its DO NOT CHANGE section; a coding agent must not change an IC signature without a new ADR.
   - **Security Architecture → §10 Security Controls** — after the threat-model/auth/zones prose, enumerate every control/mitigation with a `SEC-NN` ID, its STRIDE threat, and whether it is realized as a dedicated Feature or a cross-cutting constraint. These are tracked so the break gate can assert each is addressed by a Feature.
   - **Architectural Decisions (ADR Index)** — this section is an INDEX only. Do not write decisions inline; run `/tas-adr` to create each immutable `docs/adr/ADR-NNN.md` file and add a linking row here.
8. **Well-Architected completeness pass** — read `.tas/rules/common/architecture-completeness.md` and walk all 6 pillars against the drafted Data Architecture → Deployment Topology sections. Every pillar must read `Covered`, `N/A — reason`, or `Gap → action`. Fix gaps in the SAD now, or log them in Risks & Mitigation with an owner. Do not leave a pillar undecided.
9. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — add `artifacts.sad`.
10. **Seed `docs/architecture-map.yaml`** per `.tas/rules/common/architecture-map.md` — seed EVERY tracked design item as `status: planned`: each `MOD-NN` (+ `components` map) from §7; each `E-NNN` from §8.1 (`entities`); each `IC-NN` (+ `producer_mod`) from §9.2 (`contracts`); each `NFR-NNN` from §11 (`nfrs`); each `SEC-NN` from §10 (`security`). This as-built map has NO approval gate, so done-time coverage / trace can read it without reopening (or re-approving) the SAD. `/tas-master-plan` then asserts every seeded item is claimed by a Feature.
11. **Suggest `/tas-agents`** — once the SAD is approved, tell the user to run `/tas-agents` to (re)generate the flat, per-section context in `CLAUDE.md`/`AGENTS.md` from this SAD, so coding agents load distilled context without reading the full SAD.

### UPDATE mode (file exists):
5. Do NOT read full docs/sad.md. Grep its headings (`^#{1,4} `) to locate the section(s) the change touches, then Read only those sections by line range.
6. $ARGUMENTS is change description. If not provided, ask user which section to update.
7. Update only the targeted section(s), keep unchanged sections as-is
8. **Catalog sync** — if the change adds/removes/renames a tracked item (module, component, entity `E-NNN`, contract `IC-NN`, NFR `NFR-NNN`, or security control `SEC-NN`), update the matching SAD table in the same edit (assign new ID, keep coverage valid: every component has an FR/infra, every FR has a component, every module owns ≥1 component), and sync `docs/architecture-map.yaml` per `.tas/rules/common/architecture-map.md` (add/retire the entry as `status: planned, origin: feature`; design fields only). IDs are stable — never reuse a retired ID.
8b. **Claim prompt (close the maintenance gap)** — for every NEW `origin: feature` item this update added, it now has no claiming Feature. Emit a ⚠ list: "New design items need a Feature claim: {IDs}. Run `/tas-feature` (single) or `/tas-master-plan` (full re-break) to claim them, else `/tas-status` will report them UNCOVERED." Do not silently leave new items unclaimed.
9. **Well-Architected re-check** — for any pillar touched by this change (per `.tas/rules/common/architecture-completeness.md`), re-confirm coverage; log new gaps in Risks & Mitigation.
10. Add line to Changelog section at end
11. If change is important architectural decision, suggest user run /tas-adr
12. Update `project-status.yaml` per `.tas/rules/common/project-status.md` — update `artifacts.sad`.
13. **Suggest `/tas-agents`** — the SAD changed, so the generated sections in `CLAUDE.md`/`AGENTS.md` are now stale; tell the user to re-run `/tas-agents` to keep agent context in sync.

## Mermaid Rules
- C4 diagrams MUST use Mermaid flow diagram
- Start with :::mermaid, end with :::
- DO NOT use bare () in node labels — wrap the label in quotes `["...(...)..."]` if parentheses are unavoidable
- NEVER put () in an edge label (the text between `|...|`) — it breaks the parser. Keep edge labels plain (e.g. `-->|HTTPS REST|`)
- For line breaks inside a node label use `<br />`, NOT `\n` (renders correctly)
- Example: A["Web App<br />Next.js"] -->|HTTPS| B["API Gateway"]
- Include views: System Context, Container, Component, Data, Deployment

## Principles
- SAD must align with tech stack in CLAUDE.md
- **Architectural Decisions is an ADR Index** — decisions live in immutable `docs/adr/ADR-NNN.md` files (created by `/tas-adr`), never inline in the SAD
- **Data Architecture uses `E-NNN` codes** from PRD.Product Data Model so the entity chain stays traceable (BRD.Entity → PRD.DM → SAD.Data Architecture → Feature Technical Plan ERD Delta)
- **Integration Contracts (`IC-NN`)** in the Integration Contract Registry are stable — they become the DO NOT CHANGE anchors in Feature Technical Plans
- ERD must use Mermaid erDiagram
- Sequence diagram uses Mermaid sequenceDiagram

## Final Step — Token Log

Follow `.tas/rules/common/token-logging.md`: write AI Usage Log to `docs/sad.md`.