You will play two roles in sequence to design this feature:

**Role A: Domain Architect**
- Context: Full project structure, requirements document
- Goal: Design that fits this specific project
- Considerations: Existing patterns, technical constraints, team familiarity

**Role B: Best Practice Advisor**
- Context: Feature requirements only (no project context)
- Goal: Ideal design based on universal best practices
- Considerations: Industry standards, scalability, maintainability

Start with Role A. After your design, I will ask you to switch to Role B.

Now switch to Role B (Best Practice Advisor).

Review the Role A design above and provide:
1. What you agree with
2. Concerns or risks
3. Alternative suggestions
4. Can we reach consensus? [Yes / Need discussion]

Now return to Role A (Domain Architect).

Review Role B's feedback and provide:
1. Valid points you can accept
2. Points you must reject (with project-specific reasons)
3. Proposed compromises
4. Final stance: [Agreement / Need user decision]

Now synthesize both perspectives into a final design.
Document in "Risks & Tradeoffs" section:
- Chosen approach
- Rejected alternatives and why
- Assumptions made
- Points requiring user decision (if any)

projectRoot/
  └── docs/
        └── {serviceName}/
              ├── spec.md   # spec skill output
              ├── arch.md      # ← This skill's output
              └── trace.md      # debug skill output

⚠️ **Logical Inconsistency Detected**

**Existing Design**: {previously confirmed design content}
**User Feedback**: {new conflicting input}
**Conflict Point**: {which principle/decision is conflicting}

{
  "title": "Resolve Design Inconsistency",
  "questions": [
    {
      "id": "resolution",
      "prompt": "Existing design conflicts with new feedback. How should we proceed?",
      "options": [
        {"id": "keep_original", "label": "Keep original - Ignore new feedback"},
        {"id": "accept_new", "label": "Accept new - Revise design"},
        {"id": "merge", "label": "Merge - Incorporate both (explain how)"},
        {"id": "re_debate", "label": "Re-debate - Restart discussion with new constraints"}
      ]
    }
  ]
}

{
  "title": "Start Design Debate",
  "questions": [
    {
      "id": "has_requirements",
      "prompt": "Do you have a requirements document? (docs/{serviceName}/spec.md)",
      "options": [
        {"id": "yes", "label": "Yes - I will provide via @filepath"},
        {"id": "no", "label": "No - Need requirements refinement first"}
      ]
    }
  ]
}

Task(
  subagent_type: "domain-architect",
  description: "Project context-based design",
  prompt: """
    Requirements: {requirements MD content}
    Feature description: {feature description}
    Project structure: {project exploration results}

    Based on the above information, provide a design proposal.
  """
)

Task(
  subagent_type: "best-practice-advisor",
  description: "Best practice-based design",
  prompt: """
    Feature description: {feature description only, no project context}

    Provide an ideal design proposal for implementing this feature.
  """
)

From now on, I will relay another LLM's response.
That LLM was also instructed on the same feature definition.

Other agent's design:
{other_agent_response}

Review from your perspective and provide:
1. Points you agree with
2. Concerns
3. Alternative suggestions (if any)
4. Can we reach consensus: [Agree / Need further discussion]

{
  "title": "Design Information Supplement Required",
  "questions": [
    {
      "id": "missing_info",
      "prompt": "The following information is missing:\n- {list of missing items}\n\nHow would you like to proceed?",
      "options": [
        {"id": "provide", "label": "Provide - I will provide the information"},
        {"id": "infer", "label": "Allow inference - AI can estimate"},
        {"id": "skip", "label": "Skip - I will supplement later"}
      ]
    }
  ]
}

## 8. Risks & Tradeoffs (Debate Conclusion)

### Chosen Option
- (adopted design approach)

### Rejected Alternatives
- (unadopted items from Best Practice proposals and reasons)

### Reasoning
- Project constraints: ...
- Best practice adoption: ...
- Future improvement points: ...

### Assumptions
- **Confirmed**: (clearly decided in debate)
- **Estimated**: (assumed due to lack of confirmation)

# Feature Design Doc: {Feature Name}

> Created: {date}
> Service: {serviceName}
> Requirements document: docs/{serviceName}/spec.md

## 0. Summary

### Goal
(Goal this feature aims to achieve - 1-2 sentences)

### Non-goals
- (Items excluded from this scope)

### Success metrics
- (List of success criteria)

---

## 1. Scope

### In scope
- (Items included in this implementation)

### Out of scope
- (Future improvements or excluded items)

---

## 1.5. Tech Stack

```yaml
tech_stack:
  language: "{language and version}"        # e.g., Python 3.11, TypeScript 5.x
  framework: "{framework}"                  # e.g., FastAPI, NestJS
  database: "{DB type and version}"         # e.g., PostgreSQL 15
  orm: "{ORM package or Raw SQL}"           # e.g., SQLAlchemy, Prisma
  third_party:                              # External services
    - "{service 1}"                         # e.g., Redis
    - "{service 2}"                         # e.g., Kafka
  infra: "{infra}"                          # e.g., K8s, Docker, AWS

database_schema:
  new_tables:
    - name: "{table_name}"
      description: "{table description}"
      columns:
        - name: "id"
          type: "INTEGER"
          constraints: ["PK", "AUTO_INCREMENT"]
          description: "Primary key"
        - name: "{column_name}"
          type: "{type}"
          constraints: ["{constraint1}", "{constraint2}"]
          description: "{description}"
        - name: "created_at"
          type: "TIMESTAMP"
          constraints: ["NOT NULL", "DEFAULT NOW()"]
          description: "Creation timestamp"

  modified_tables:
    - name: "{table_name}"
      changes:
        - column: "{column_name}"
          type: "{type}"
          action: "ADD"          # ADD | DROP | MODIFY
          description: "{description}"

  indexes:
    - table: "{table_name}"
      columns: ["{column1}", "{column2}"]
      type: "BTREE"              # BTREE | HASH | GIN | etc.
      unique: false

migrations:
  - type: "CREATE_TABLE"
    table: "{table}"
    description: "{description}"
  - type: "ALTER_TABLE"
    table: "{table}"
    description: "{change content}"
  - type: "CREATE_INDEX"
    table: "{table}"
    description: "{index description}"

Client->>API: {request}
API->>Service: {method call}
Service->>DB: {DB operation}
DB-->>Service: {result}
Service-->>API: {return}
API-->>Client: {response}

api_endpoints:
  - name: "{API name}"
    method: "{GET|POST|PUT|DELETE}"
    path: "/api/v1/{path}"
    description: "{API description}"
    auth_required: true
    request:
      headers:
        - name: "Authorization"
          type: "string"
          required: true
      params:                    # Query params (GET) or Path params
        - name: "{param}"
          type: "{type}"
          required: true
      body:                      # Request body (POST/PUT)
        content_type: "application/json"
        schema:
          field1: "{type}"
          field2: "{type}"
    response:
      success:
        status: 200
        schema:
          success: "boolean"
          data: "{type or object}"
      errors:
        - status: 400
          code: "INVALID_INPUT"
          message: "{error message}"
        - status: 404
          code: "NOT_FOUND"
          message: "{error message}"

---

# Completion Guidance

After saving document, inform user:

> ✅ **Design Document Complete**
>
> Saved to: `docs/{serviceName}/arch.md`
>
> **Next Step**: Run `build` skill to begin implementation.
> → Recommended to switch to **Sonnet model** in new session (cost savings)

---

# Integration Flow