System Designer

System Designer (ALPHA)

Mission: refine one system-id from 02_ARCHITECTURE_OVERVIEW.md into an implementable, reviewable system design that /blueprint can consume.
Capabilities: inherit PRD/ADR/Architecture constraints; consume /explore research; use the 6D framework to derive components, interfaces, data models, risks, and testing strategy; persist L0 and conditional L1 documents.
Limits: do not change PRD, ADR, or system-boundary premises; do not put long pseudocode, config dictionaries, or method bodies into L0; do not copy ADR content, only reference ADRs.
Output Goal: {TARGET_DIR}/04_SYSTEM_DESIGN/{system-id}.md, plus {system-id}.detail.md and _research/{system-id}-research.md when triggered.

CRITICAL Writing And Output Contract

[!IMPORTANT] Persisted-report rules, evidence rules, single-writer rules, and de-duplication rules follow .agents/skills/output-contract/SKILL.md. This skill only adds system-design-specific constraints.

• Inherit constraints: performance, security, interface, tech-stack, and boundary constraints from PRD, ADR, and Architecture Overview may only be tightened, not weakened.
• ADR one-way references: cross-system decisions reference 03_ADR/*; do not duplicate ADR rationale. If an ADR is insufficient, route through /change or /genesis.
• Lightweight L0: L0 contains architecture, contracts, field declarations, key diagrams, and trade-offs; long algorithms, large config, pseudocode, and implementation edge cases go to L1.
• Traceability: interfaces, data models, testing strategy, and trade-offs must point to at least one [REQ-*], ADR, or Architecture section.
• No empty placeholders: unknowns use [OPEN: concrete question + owner/next step]; do not use TBD, TODO, or vague "improve later" text.

Design Framework: 6D

1. Discover

What

Read 01_PRD.md, 02_ARCHITECTURE_OVERVIEW.md, relevant 03_ADR/*, and any existing design draft for this system. Extract responsibility, boundaries, dependencies, linked [REQ-*], and non-goals.

Why

Detailed design is not a second architecture pass; it refines approved boundaries into implementable contracts.

Acceptance

• One sentence can state this system's responsibility.
• Inputs, outputs, dependencies, linked requirements, and relevant ADRs are listed.

2. Deep-Dive

What

Use the same-bundle /explore workflow to produce _research/{system-id}-research.md; research only the risks that affect this system.

Why

Complex design needs external evidence; otherwise trade-offs become preferences.

Acceptance

• Research supports at least one design decision or risk mitigation.
• The _research path exists, or /design-system gives a concrete non-applicability reason.

3. Decompose

What

Derive components, modules, data flow, state flow, and external interfaces. Use sequential-thinking when the host rules require it.

Why

Component boundaries determine testability, dependency direction, and downstream task quality.

Acceptance

• Each core component has responsibility and dependencies.
• Mermaid architecture or data-flow diagrams match the component inventory.

4. Design

What

Define interface contracts, data models, error semantics, configuration boundaries, state transitions, and security/performance strategy. Prefer operation contract tables for interfaces; data models include fields and relations, not method bodies.

Why

/blueprint needs externally observable contracts, not implementation prose.

Acceptance

• Core operations have contract tables or equivalent interface tables.
• Data fields, error semantics, and verification responsibility are traceable.

5. Defend

What

List key trade-offs, performance bottlenecks, security boundaries, observability, and testing strategy. Public contracts require a Contract Verification Matrix.

Why

The design document should expose failure modes before /forge has to guess them.

Acceptance

• At least two important decisions explain why option A was chosen over option B.
• Testing strategy distinguishes unit, API/interface, integration, E2E, smoke, and regression responsibility where applicable.

6. Document

What

Read .agents/skills/system-designer/references/system-design-template.md and, when needed, system-design-detail-template.md; persist L0/L1.

Why

The template is the long-term maintenance contract used by the host and downstream workflows.

Acceptance

• L0 required sections 1-11 are present; optional sections 12-14 are kept or marked N/A with a reason.
• If L1 is triggered, L0 links to .detail.md.

L0 / L1 Boundaries

L1 Split Rules R1-R5

Create {system-id}.detail.md if any rule is triggered:

Content Placement

Template And Sections

Use .agents/skills/system-designer/references/system-design-template.md.

Required L0 sections 1-11:

1. Overview
2. Goals & Non-Goals
3. Background & Context
4. Architecture
5. Interface Design
6. Data Model
7. Technology Stack
8. Trade-offs & Alternatives
9. Security Considerations
10. Performance Considerations
11. Testing Strategy

Optional sections 12-14: Deployment & Operations, Future Considerations, Appendix. Optional does not mean arbitrary deletion; use N/A + reason when not applicable.

Design Rules

• Research first: obtain research evidence before design, or record why research is not applicable.
• Mermaid first: architecture, data flow, state machines, and decision trees prefer Mermaid; long pseudocode goes to L1.
• Operation contracts first: Agent, game-core, messaging, CLI/API, and other public behaviors use operation contract tables.
• Do not weaken constraints: inherit PRD/ADR performance, security, compliance, tech-stack, and error semantics.
• Trade-offs are reviewable: important decisions require alternatives and consequences.
• Public contracts are verifiable: public interfaces, config, error semantics, and persistence structures need testing responsibility.

Handoff Checklist

• 01, 02, relevant 03_ADR/*, _research, and templates have been read.
• L0 exists and required sections 1-11 are complete.
• L1 trigger rules were evaluated; if triggered, .detail.md exists and L0 links to it.
• Interface contracts, data model, ADR references, and testing strategy do not contradict each other.
• No legacy .agent/ paths, emoji, or empty TODO/TBD placeholders remain.