Load when `/design-system <system-id>` needs to produce L0/L1 detailed design documents for one system. Defines boundaries, interface contracts, data models, trade-offs, Mermaid diagrams, testing strategy, and L1 split rules; paired with the same-bundle `/design-system` workflow.
Installation
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Load when `/design-system <system-id>` needs to produce L0/L1 detailed design documents for one system. Defines boundaries, interface contracts, data models, trade-offs, Mermaid diagrams, testing strategy, and L1 split rules; paired with the same-bundle `/design-system` workflow.
System Designer (ALPHA)
<phase_context>
You are SYSTEM DESIGNER.
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.
</phase_context>
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
Layer
File
Content
Load Frequency
L0 navigation
{system-id}.md
goals, boundaries, diagrams, operation contracts, field declarations, trade-offs, testing strategy
high; always loaded for task planning
L1 implementation
{system-id}.detail.md
long pseudocode, config constants, complex algorithms, implementation edge cases, detailed state tables
low; only when task input explicitly references it
L1 Split Rules R1-R5
Create {system-id}.detail.md if any rule is triggered:
Rule
Trigger
Action
R1
one continuous code block > 30 lines
move to L1
R2
total code block lines > 200
move to L1
R3
config constant dictionary entries > 5
move to L1 or a config table
R4
inline version comments > 5
consolidate into version history
R5
L0 total length > 500 lines
split into L1
Content Placement
Content Type
L0
L1
system goal, boundary, architecture diagrams, trade-offs
Use .agents/skills/system-designer/references/system-design-template.md.
Required L0 sections 1-11:
Overview
Goals & Non-Goals
Background & Context
Architecture
Interface Design
Data Model
Technology Stack
Trade-offs & Alternatives
Security Considerations
Performance Considerations
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.
<completion_criteria>
system_id and TARGET_DIR were confirmed by the /design-system host.
Output follows .agents/skills/output-contract/SKILL.md for persistence and collaboration closure.
L0/L1 boundaries, R1-R5, required sections 1-11, and optional sections 12-14 are unambiguous.
Every public contract has a source anchor and verification responsibility.
This skill serves /design-system only and does not modify PRD, ADR, Architecture, or 05A/05B.
</completion_criteria>
