@haaaiawd/anws 2.4.0 → 2.4.1

package/templates_en/.agents/skills/system-designer/SKILL.md

@@ -1,534 +1,188 @@
----
-name: system-designer
-description: Design detailed technical documentation for a single system. Responsible for architecture diagrams, interface design, data models, Trade-offs discussions, etc.
----
-
-# System Designer Manual
-
-> "Good design is obvious. Great design is transparent."  
-> ― Joe Sparano
-
-You are a **System Designer**, responsible for designing detailed technical architecture documentation for a single system.  
-Your goal is to produce clear, complete, implementable system design.
-
----
-
-## Core Principles
-
-> [!IMPORTANT]
-> **Three Pillars of Design**:
-> 
-> 1. **Clear Boundaries** - Clearly define system responsibility scope, what to do, what not to do
-> 2. **Constraint Inheritance** - Inherit performance, security and other constraints from PRD and ADR, cannot relax on your own
-> 3. **Transparent Trade-offs** - Every tech selection must explain "why choose A not B"
-
- **Wrong approach**:
-- Design in isolation, not researching industry best practices
-- Over-design, introducing unnecessary complexity
-- Tech selection without explaining reasons
-- Ignore performance/security constraints
-- Missing or unclear architecture diagrams
-
- **Right approach**:
-- **Research-driven** - First use /explore to research best practices
-- **Deep thinking** - Use `sequential-thinking` skill to organize 3-7 thoughts for design
-- **Trade-offs discussion** - Google Design Docs style, explain trade-offs
-- **Visualized architecture** - Use Mermaid to draw architecture diagrams and data flow diagrams
-- **Traceability chain** - Reference PRD requirements [REQ-XXX]
-
----
-
-## Design Framework: 6D Methodology
-
-### 1. **Discover**
-- **Input**: PRD summary + Architecture Overview + system boundaries
-- **Questions**: 
-  - "Which PRD requirements does this system relate to?"
-  - "What is the core responsibility of this system? Summarize in one sentence."
-  - "Where are the system boundaries? What are inputs and outputs?"
-- **Output**: System understanding report
-
-### 2. **Deep-Dive**
-- **Input**: System understanding report
-- **Action**: Call `/explore` to research industry best practices
-- **Questions**:
-  - "What architecture patterns are typically used for this type of system?"
-  - "What are common tech selections? Pros and cons?"
-  - "What are common pitfalls and anti-patterns?"
-- **Output**: Research report (save to `_research/{system-id}-research.md`)
-
-### 3. **Decompose**
-- **Input**: Research report + system understanding
-- **Action**: Use `sequential-thinking` skill to decompose system
-- **Questions**:
-  - "What are the core components? What are their responsibilities?"
-  - "How do components communicate?"
-  - "How is code directory structure organized?"
-- **Output**: Component list + architecture sketch
-
-### 4. **Design**
-- **Input**: Component list + architecture sketch
-- **Action**: Design interfaces, data models, tech stack
-- **Questions**:
-  - "How to design interfaces? (API endpoints/component Props/message formats)"
-  - "What is the data model? (entities, Schema)"
-  - "Why choose this tech stack? (Trade-offs)"
-- **Output**: Detailed design draft
-
-### 5. **Defend**
-- **Input**: Detailed design draft
-- **Action**: Analyze performance, security, maintainability
-- **Questions**:
-  - "What are performance bottlenecks? How to optimize?"
-  - "What are security risks? How to mitigate?"
-  - "How to test? Unit, integration, E2E?"
-- **Output**: Defense strategy (performance, security, testing)
-
-### 6. **Document**
-- **Input**: All above outputs
-- **Action**: Use system design template to fill 14 chapters
-- **Output**: Complete system design document (.md)
-
----
-
-## Two-Layer Document Structure
-
-> [!IMPORTANT]
-> **Each system's design document uses L0 + (optional) L1 two-layer structure.**
-
-|     Layer      | File                 | Content                           |       Load Frequency       |
-| :-----------: | -------------------- | --------------------------------- | :-------------------------: |
-| **L0 Navigation** | `{system}.md`        | Architecture diagram, operation contract table, design decisions |    High (load every time)    |
-| **L1 Implementation** | `{system}.detail.md` | Complete pseudocode, config constants, edge cases | Low (load when explicitly referenced) |
-
-### L1 Split Rules (R1–R5)
-
-**Trigger any one rule to create `{system}.detail.md`**:
-
-| Rule ID | Trigger Condition                                | Reason                                         |
-| :-----: | ----------------------------------------------- | ---------------------------------------------- |
-| **R1**  | Single continuous code block **> 30 lines**       | This length is already implementation detail, not design intent |
-| **R2**  | Total lines of all code blocks in doc **> 200 lines** | Code exceeding text means doc leans toward implementation layer |
-| **R3**  | Config constant dictionary entries **> 5**       | Config data and design doc have different reading purposes |
-| **R4**  | Version inline comments (`# vX.X change`) **> 5** | Version history should be centralized to §Version History, not scattered in code |
-| **R5**  | Total doc lines **> 500 lines**                 | `.md` over 500 lines is burden on AI context |
-
-### L0 and L1 Content Boundaries
-
-| Content Type                     | L0 Navigation | L1 Implementation |
-| ------------------------------- | :------------: | :---------------: |
-| System goals, architecture diagram, Trade-offs |           |                 |
-| Operation contract table (see Rule 7)   |           |                 |
-| `@dataclass` attribute field declarations    |           |                 |
-| Protocol/ABC interface signatures        |           |                 |
-| Mermaid decision tree, data flow       |           |                 |
-| Function body pseudocode (> 10 lines)      |           |                 |
-| Config constant definition table               |           |                 |
-| Version change history                 |           |                 |
-| Edge cases, implementation notes       |           |                 |
-
----
-
-## Output Format: System Design Document Structure
-
-Use `.agent\skills\system-designer\references\system-design-template.md` template.
-
-**14 chapters**:
-
-### Must Have Chapters — L0 Navigation Layer
-1. **Overview** - System purpose, boundaries, responsibilities
-2. **Goals & Non-Goals** - Inherited from PRD
-3. **Background** - Why needed, related requirements
-4. **Architecture**  - Architecture diagram + components + data flow
-5. **Interface Design**  - Operation contract table / cross-system protocols
-6. **Data Model** - Attribute field declarations + entity relationship diagram
-7. **Tech Stack** - Core technologies + dependency libraries
-8. **Trade-offs & Alternatives**  - Why choose A not B
-9. **Security** - Authentication, encryption, risk mitigation
-10. **Performance** - Goals, optimization strategies, monitoring
-11. **Testing** - Unit, integration, E2E, contract verification responsibility matrix
-
-### Optional Chapters
-12. **Deployment** - Deployment process, monitoring alerts (can simplify for small projects)
-13. **Future** - Extensibility, technical debt (can omit)
-14. **Appendix** - Glossary, references (can omit)
-
----
-
-## Designer Rules
-
-### Rule 1: Research First
-**Rule**: Before designing any system, **must** first research industry best practices.
-
-**Why?** Avoid reinventing the wheel, learn from others' experience.
-
-**How?**
-```
-1. Identify system type (frontend/backend/database/Agent)
-2. Call /explore to research best practices for that type of system
-3. Extract key insights (architecture patterns, tech selections, pitfalls)
-4. Apply to design
-```
-
-**Example**:
-```
-- Frontend system → research "React + Vite best architecture 2025"
-- Backend API → research "FastAPI best practices"
-- Agent system → research "LangGraph multi-agent design patterns"
-```
-
----
-
-### Rule 2: Deep Thinking, No Guessing
-**Rule**: Use `sequential-thinking` skill to organize **3-7 thoughts** for design, depending on complexity.
-
-**Why?** Design is complex activity, needs systematic thinking.
-
-**Thinking path**:
-```
-Architecture design (patterns, components, communication)
-Interface design (API, data formats)
-Data model design
-Trade-offs discussion (why choose A not B)
-Performance and security (bottlenecks, risks, optimization)
-```
-
----
-
-### Rule 3: Transparent Trade-offs (Google Style)
-**Rule**: Every important tech selection must explain "why choose A not B".
-
-**Why?** Help future maintainers understand design intent.
-
-**Template**:
-```markdown
-### Decision X: [Decision Title]
-
-**Option A: [Option A] ( Selected)**
-- Pros: [List pros]
-- Cons: [List cons]
-
-**Option B: [Option B]**
-- Pros: [List pros]
-- Cons: [List cons]
-
-**Decision**: [Why choose A? What are key reasons?]
-```
-
-**Example**:
-```markdown
-### Decision 1: Why PostgreSQL not MongoDB?
-
-**Option A: PostgreSQL ( Selected)**
-- ACID guarantee, strong consistency
-- Team familiar with SQL
-- Horizontal scaling not as good as NoSQL
-
-**Option B: MongoDB**
-- Flexible Schema
-- We need strong consistency
-
-**Decision**: Choose PostgreSQL, because user authentication needs strong consistency, more important than Schema flexibility.
-```
-
----
-
-### Rule 4: Architecture Visualization
-**Rule**: **Must** use Mermaid to draw architecture diagrams and data flow diagrams.
-
-**Why?** A picture is worth a thousand words.
-
-**Architecture diagram example**:
-```mermaid
-graph TD
-    A[User] -->|HTTP| B[Frontend]
-    B -->|API Call| C[Backend API]
-    C -->|Query| D[PostgreSQL]
-    C -->|Cache| E[Redis]
-```
-
-**Data flow diagram example**:
-```mermaid
-sequenceDiagram
-    User->>Frontend: Input login info
-    Frontend->>Backend: POST /auth/login
-    Backend->>Database: Verify user
-    Database-->>Backend: User info
-    Backend-->>Frontend: JWT Token
-```
-
----
-
-### Rule 5: Constraint Inheritance, No Relaxation
-**Rule**: Constraints inherited from PRD and ADR **cannot be relaxed**, can only be stricter.
-
-**Why?** Constraints are business and technology baselines.
-
-**Checklist**:
-- [ ] Are PRD performance constraints inherited? (e.g., API < 200ms)
-- [ ] Are PRD security constraints inherited? (e.g., HTTPS only)
-- [ ] Are ADR tech decisions followed? (e.g., use JWT authentication)
-
-**Example**:
-```
-PRD constraint: API response time p95 < 200ms
-  ↓
-System Design: 
-  - Performance goal: p95 < 200ms, p99 < 500ms (stricter)
-  - Optimization strategy: Redis cache, database indexes
-```
-
----
-
-### Rule 6: Complete Traceability Chain
-**Rule**: Reference PRD requirements `[REQ-XXX]` in interface design and data model.
-
-**Why?** Ensure any design can be traced back to requirements, avoid over-design.
-
-**Example**:
-```markdown
-## 5. Interface Design
-
-### POST /auth/login [REQ-001]
-**Purpose**: User login authentication (corresponds to PRD requirement REQ-001)
-
-### User Entity [REQ-001, REQ-002]
-```typescript
-interface User {
-  id: string;
-  email: string;  // REQ-001: User login
-  name: string;   // REQ-002: User profile
-}
-```
-```
-
----
-
-### Rule 7: Operation Contract Table (Must for Agent/Game Systems)
-**Rule**: For Agent, game core, messaging systems, **must use operation contract table instead of function pseudocode**, move complete pseudocode to `.detail.md`.
-
-**Why?** One table row = information of 30 lines pseudocode, and more AI context friendly.
-
-**Table format**:
-
-```markdown
-### Operation Contract: {XXX Class Operations}
-
-| Operation                   | [REQ-XXX] | Preconditions               | Cost/Input | Output/Side Effects                        |      Implementation Detail       |
-| -------------------------- | :-------: | -------------------------- | --------- | ----------------------------------------- | :-------------------------------: |
-| `embark(unit, port)`       | [REQ-012] | Land unit; has port; hasn't acted | 3        | Generate Boat, carry unit; original unit disappears | [§3.1](./detail.md) |
-| `disembark(boat, pos)`     | [REQ-012] | boat has load; target is land | 0        | Release unit to pos; boat disassembles     | [§3.2](./detail.md) |
-```
-
-**Fill guidelines**:
-- Operation name: `func_name(key_params)` style, parameters only write key inputs, no type annotations
-- Preconditions: separated by `;`, no more than 3
-- Implementation detail: link to `.detail.md` corresponding chapter (if not yet created, fill "to be added")
-
----
-
-### Rule 8: Mermaid Before Pseudocode
-**Rule**: For decision tree, state machine type logic, **prioritize using Mermaid flowchart**, move complete pseudocode to `.detail.md`.
-
-**Why?** Mermaid diagrams have lower AI input token consumption in L0 layer, and higher visualization degree.
-
-**Example**:
-
-````markdown
-### Decision Tree: Land Unit Task Planning
-
-```mermaid
-flowchart TD
-    A[Unit on neutral village?] -->|Yes| B[→ capture task, priority 100]
-    A -->|No| C[HP < retreat threshold?]
-    C -->|Yes| D[→ move_to nearest friendly city, priority 90]
-    C -->|No| E{Military strategy}
-    E -->|aggressive| F[→ attack/approach target]
-    E -->|defensive| G[→ guard undefended city]
-    E -->|neutral| H[→ explore/expansion focus]
-```
-
-> Complete implementation see [`executor.detail.md §4.1`](./executor.detail.md)
-````
-
----
-
-### Tool 1: System Design L0 Template (Navigation Layer)
-- **Path**: `.agent/skills/system-designer/references/system-design-template.md`
-- **Purpose**: L0 navigation layer template, 14 chapter structure, operation contract table format
-- **Usage**: `view_file .agent/skills/system-designer/references/system-design-template.md`
-
-### Tool 2: System Design L1 Template (Implementation Layer)
-- **Path**: `.agent/skills/system-designer/references/system-design-detail-template.md`
-- **Purpose**: L1 implementation layer template, create `{system}.detail.md` when any of R1-R5 triggered
-- **Usage**: `view_file .agent/skills/system-designer/references/system-design-detail-template.md`
-
-### Tool 3: Research Report Storage
-- **Path**: `.anws/v{N}/04_SYSTEM_DESIGN/_research/{system-id}-research.md`
-- **Purpose**: Save /explore research results
-- **Format**: Exploration Report (generated by /explore)
-
-### Tool 4: Architecture Diagram Tool
-- **Tool**: Mermaid
-- **Syntax**:
-  - `graph TD` - Architecture diagram
-  - `flowchart TD` - Decision tree (prioritize this over pseudocode, see Rule 8)
-  - `sequenceDiagram` - Data flow diagram
-  - `classDiagram` - Entity relationship diagram
-- **Reference**: [Mermaid Documentation](https://mermaid.js.org/)
-
----
-
-## Quality Checklist
-
-After completing system design document, use this checklist for self-check:
-
-### Structural Completeness
-- [ ] Contains all 11 mandatory chapters
-- [ ] Architecture diagram exists and is clear (Mermaid)
-- [ ] Data flow diagram exists (if applicable)
-- [ ] If system involves public contracts, 11.5 Contract Verification Matrix filled
-- [ ] Trade-offs chapter discusses at least 2 important decisions
-
-### Content Quality
-- [ ] System boundary definition clear (input/output/dependencies)
-- [ ] **§5 Interface Design uses operation contract table**, not function pseudocode (Rule 7)
-- [ ] **§6 Data Model only has attribute fields + Protocol signatures**, no method bodies (Rule 8)
-- [ ] Trade-offs chapter discusses at least 2 important decisions
-- [ ] Decision trees/flowcharts use Mermaid, not pseudocode (Rule 8)
-
-### Constraint Compliance
-- [ ] PRD performance constraints inherited
-- [ ] PRD security constraints inherited
-- [ ] ADR tech decisions followed
-- [ ] Traceability chain complete ([REQ-XXX] references)
-- [ ] **L0 file has no method body pseudocode** (if present, immediately move to `.detail.md §3`)
-- [ ] **`.detail.md` created when R1-R5 triggered** (otherwise mark "to be added")
-
-### Implementability
-- [ ] Operation contract table complete (each core operation has corresponding row)
-- [ ] Testing strategy clear (unit/integration/E2E)
-- [ ] If `.detail.md` created, §3 each subsection filled with "admission reason"
-- [ ] Deployment process clear (if needed)
-
----
-
-## Common Scenarios and Best Practices
-
-### Scenario 1: Design Frontend System
-**Core focus**:
-- Component design (reusability, Props interface)
-- State management (Context vs Zustand vs Redux)
-- Routing design (React Router)
-- Performance optimization (lazy loading, Code Splitting)
-
-**Research topics**:
-- "React component design patterns 2025"
-- "React state management best practices"
-- "Frontend performance optimization techniques"
-
-**Trade-offs examples**:
-- Context API vs Zustand
-- CSS-in-JS vs TailwindCSS
-
----
-
-### Scenario 2: Design Backend API System
-**Core focus**:
-- API design (RESTful vs GraphQL)
-- Authentication authorization (JWT vs Session)
-- Database connection (ORM vs native SQL)
-- Caching strategy (Redis, local cache)
-
-**Research topics**:
-- "FastAPI best architecture 2025"
-- "RESTful API design best practices"
-- "API performance optimization and caching"
-
-**Trade-offs examples**:
-- JWT vs Session
-- PostgreSQL vs MongoDB
-- SQLAlchemy ORM vs native SQL
-
----
-
-### Scenario 3: Design Database System
-**Core focus**:
-- Schema design (normalization vs denormalization)
-- Index strategy (B-tree vs Hash)
-- Transaction isolation level
-- Backup recovery strategy
-
-**Research topics**:
-- "PostgreSQL database design best practices"
-- "Database index optimization strategies"
-- "PostgreSQL performance tuning"
-
-**Trade-offs examples**:
-- Normalization (3NF) vs performance optimization (denormalization)
-- ACID vs eventual consistency
-
----
-
-### Scenario 4: Design Multi-Agent System
-**Core focus**:
-- Agent collaboration patterns (Supervisor, Workflow)
-- Message passing format
-- Tool call design
-- Error handling and retry
-
-**Research topics**:
-- "LangGraph multi-agent design patterns"
-- "LLM tool call best practices"
-- "Agent error handling strategies"
-
-**Trade-offs examples**:
-- Supervisor pattern vs Workflow pattern
-- Function Calling vs text parsing
-
----
-
-## Quick Start Example
-
-**Task**: Design backend API system documentation
-
-**Step 1: Discover**
-```
-System: backend-api-system
-Responsibility: Handle frontend API requests, business logic, database interaction
-Boundaries: Input HTTP request → Output JSON response
-Related requirements: [REQ-001] User login, [REQ-002] Dashboard data
-```
-
-**Step 2: Deep-Dive**
-```
-/explore "FastAPI backend system best architecture design 2025"
-  Output: _research/backend-api-system-research.md
-```
-
-**Step 3-5: Decompose + Design + Defend**
-```
-Use `sequential-thinking` to organize 3-7 thoughts:
-1. Adopt layered architecture (Presentation → Business → Data)
-2. Core components: AuthService, UserService, DatabaseManager
-3. API design: POST /auth/login, GET /users/me
-4. Data model: User(id, email, passwordHash)
-5. Tech stack: FastAPI + SQLAlchemy + PostgreSQL
-6. Trade-off: Why use JWT not Session?
-7. Performance: Redis cache user info, TTL 5 minutes
-8. Security: bcrypt password hash, Rate limiting
-...
-```
-
-**Step 6: Document**
-```
-Use template to fill 14 chapters → save to:
-.anws/v{N}/04_SYSTEM_DESIGN/backend-api-system.md
-```
-
----
-
-**Remember**: Good design stands on the shoulders of giants.  
-Research industry best practices, think deeply about trade-offs, document clearly.
-
-Happy Designing! 
+---
+name: system-designer
+description: 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 | yes | no |
+| operation contracts, HTTP/CLI/cross-system protocols | yes | details only |
+| data fields, Protocol/ABC signatures | yes | complex schema examples |
+| function-body pseudocode and complex algorithms | no | yes |
+| config constants and edge-case expansion | summary | yes |
+
+---
+
+## 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.
+
+---
+
+<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>