Architecture Decisions Skill

Purpose

Enable structured architecture decision-making through quality attribute analysis, trade-off evaluation, and technology selection using industry-standard frameworks.

Parameters

decision_context

decision_type

tradeoff

quality_priorities

["performance", "maintainability"]

constraints

{}

options

Execution Flow

┌──────────────────────────────────────────────────────────┐
│ 1. VALIDATE: Check input parameters                       │
│ 2. CONTEXTUALIZE: Understand problem domain               │
│ 3. IDENTIFY: List quality attributes and constraints      │
│ 4. ANALYZE: Evaluate options against criteria             │
│ 5. SCORE: Create decision matrix                          │
│ 6. RECOMMEND: Provide primary + alternatives              │
│ 7. DOCUMENT: Generate ADR content                         │
└──────────────────────────────────────────────────────────┘

Retry Logic

VALIDATION_ERROR

CONTEXT_UNCLEAR

INSUFFICIENT_OPTIONS

Logging & Observability

log_points:
  - event: skill_invoked
    level: info
    data: [decision_type, quality_priorities]
  - event: analysis_complete
    level: info
    data: [options_count, top_recommendation]
  - event: error_occurred
    level: error
    data: [error_type, context]

metrics:
  - name: decision_time_ms
    type: histogram
  - name: options_evaluated
    type: counter
  - name: confidence_score
    type: gauge

Error Handling

E001

E002

E003

E004

Unit Test Template

test_cases:
  - name: "Database selection decision"
    input:
      decision_context: "E-commerce order management system"
      decision_type: "technology"
      quality_priorities: ["reliability", "performance"]
      options: ["PostgreSQL", "MongoDB"]
    expected:
      has_recommendation: true
      has_rationale: true
      confidence_gte: 0.7

  - name: "Missing context error"
    input:
      decision_context: ""
    expected:
      error_code: "E001"

  - name: "Microservices vs Monolith"
    input:
      decision_context: "Startup MVP with 4 developers"
      decision_type: "pattern"
      quality_priorities: ["deployability", "maintainability"]
    expected:
      has_trade_offs: true
      alternatives_count_gte: 1

Troubleshooting

Common Issues

Debug Checklist

□ Is problem domain clearly defined?
□ Are quality attributes prioritized?
□ Are all options technically viable?
□ Are constraints explicitly stated?
□ Is success criteria measurable?

Examples

Example: Technology Selection

Input:
  decision_context: "Real-time inventory system for retail"
  decision_type: "technology"
  quality_priorities: ["performance", "scalability"]
  options: ["Redis", "PostgreSQL", "MongoDB"]

Output:
  recommendation: "Redis for hot data + PostgreSQL for persistence"
  confidence: 0.85
  trade_offs:
    - "Redis: Fast but requires cache invalidation strategy"
    - "PostgreSQL: ACID compliant but higher latency"
  adr_content: |
    # ADR: Hybrid Redis + PostgreSQL for Inventory
    ## Decision: Use Redis for real-time inventory counts, PostgreSQL for order data
    ## Rationale: Balances performance needs with data durability

Integration

Quality Standards

• Atomic: Single decision per invocation
• Traceable: All decisions link to rationale
• Reversible: Document rollback strategy when applicable

Version History