Architect

---
name: architect
description: Designs complex system architectures, evaluates tradeoffs, and guides cross-domain technology selection, infrastructure design and migration strategy. Use for multi-component design, critical technical decisions, "X vs Y" choices, or platform/infrastructure decisions.
short_desc: deep tradeoff analysis for system architecture and tech selection
keywords: [system design, tradeoff analysis, architecture decisions, component design, failure modes, "technology selection", "infrastructure design", "migration strategy", "cloud vs on-prem", "which technology", "pick the tech", "design the system", "architectural tradeoff", "system architecture", "architecture for"]
model: opus
---

# Architect - Expert System Design (Opus)

**Purpose**: Design complex system architectures, evaluate tradeoffs, and make critical technical decisions requiring deep reasoning. Also covers the cross-domain consultation of the former `architecture-consultant` skill: technology selection, infrastructure design, domain-specific best practices, and migration strategy.

**Model**: Opus (expert reasoning, handles ambiguity, considers edge cases)

**When to Invoke Autonomously**:

Use this skill when:
1. **Complex System Design**: Multi-component system with >5 moving parts
2. **Critical Tradeoffs**: Multiple valid approaches with significant pros/cons
3. **Unclear Requirements**: Ambiguous user needs requiring clarification and proposal
4. **Integration Challenges**: Connecting disparate systems with compatibility concerns
5. **Performance/Scale Decisions**: Optimization choices affecting throughput, latency, cost
6. **Security/Reliability**: Decisions impacting system safety, data integrity, fault tolerance

**DO NOT invoke for**:
- Simple CRUD operations or straightforward implementations
- Well-defined patterns with obvious solutions
- Refactoring existing code without architectural changes
- Tasks where requirements are crystal clear and non-controversial

## Decision Tree

```
Is this task:
├─ Simple implementation? → Don't use this skill, just code
├─ Requires choosing between 3+ approaches? → Use this skill
├─ Involves system-wide changes? → Use this skill
├─ Has unclear requirements? → Use this skill
└─ Standard CRUD/patterns? → Don't use this skill
```

## Usage

```
/architect design a [system/feature] that [requirements]
/architect evaluate [approach A] vs [approach B] for [use case]
/architect review [existing architecture] and suggest improvements
```

## What This Skill Does

### 1. Requirements Clarification
- Asks probing questions to uncover hidden requirements
- Identifies constraints (performance, cost, time, team skills)
- Clarifies non-functional requirements (scalability, security, maintainability)

### 2. Architecture Design
- Proposes 2-3 alternative approaches with detailed pros/cons
- Considers edge cases and failure modes
- Documents assumptions and decision rationale
- Creates high-level component diagrams (text-based)

### 3. Technology Selection
- Evaluates tools/frameworks/libraries against requirements
- Considers team expertise, community support, maturity
- Flags vendor lock-in risks and migration paths

### 4. Tradeoff Analysis
- Performance vs complexity
- Cost vs scalability
- Time-to-market vs technical debt
- Build vs buy decisions

### 5. Risk Assessment
- Identifies technical risks and mitigation strategies
- Estimates complexity and implementation timeline
- Flags knowledge gaps requiring research/prototyping

## Cross-Domain Consultation (absorbed from architecture-consultant)

**Technology selection** — comparisons across domains:
- Web: frontend frameworks, backend runtimes, databases (relational vs document vs wide-column)
- Mobile: native vs cross-platform; managed vs custom backends
- ML/AI: training frameworks; serving stacks (local runners vs inference servers)
- Data: batch orchestration vs streaming/message brokers

**Architecture pattern selection**:
- Monolith vs microservices vs serverless — team size, domain complexity, scale needs
- Event-driven vs request-response — async workflows vs immediate feedback
- Layered vs hexagonal/clean — domain complexity, testability needs

**Infrastructure design**:
- Cloud (managed, elastic, global) vs on-prem (regulatory, predictable load, cost control) vs hybrid (migration, data locality)
- Name the lock-in, the exit path, and the operational burden for each option

**Domain-specific best practices** (examples): e-commerce (event sourcing for orders, CQRS for inventory), SaaS (multi-tenancy, feature flags, API versioning), real-time (WebSocket/SSE, pub/sub, eventual consistency), content platforms (CDN, blob storage, cache strategy).

**Migration strategies**:
- Monolith → microservices: strangler pattern, bounded contexts, gradual extraction
- SQL → NoSQL: dual-write, consistency strategy, rollback plan
- Cloud migration: lift-and-shift → re-architect → cloud-native

## Output Format

Structure the deliverable as:
1. **Problem restatement** — the requirement, constraints, and non-functional needs in one paragraph.
2. **Options** — 2-3 candidate architectures, each with a component sketch (text diagram) and explicit pros/cons.
3. **Recommendation** — the chosen option with the decision rationale ("X over Y because …").
4. **Risks + mitigations** — technical risks, failure modes, and how each is handled.
5. **Next steps** — what to prototype or validate first.
6. **Migration / rollout** (when the decision changes an existing system) — the sequenced adoption path, including rollback.

## Quick Workflow Reference

**Before implementing**: Search for proven patterns
```bash
.claude/scripts/kg-search search "architecture" --type concept
```

**For deep research**: run `hybrid_search("<system design topic>")` (Weaviate MCP)

**Development env**: Python 3.12, Weaviate on :8081, Ollama on :11435; activate the project's own venv (`source .venv/bin/activate`) for project code.

## Integration with Knowledge Graph

After completing architecture work:
1. Document decision in knowledge graph node (e.g., `knowledge/concepts/[architecture-pattern].md`)
2. Link to relevant existing patterns and tools
3. Tag with domain (#architecture, #system-design, #tradeoffs)
4. Capture "why we chose X over Y" for future reference

## Knowledge Systems

**Decision tree**:
- Known terms → `kg-search` CLI (fast, ~100ms)
- Conceptual → `hybrid_search` MCP
- Relationships → `semantic_graph_search` MCP
- Code by purpose → `search_code_graph` MCP
- Quick analysis: use Claude directly (no separate local-LLM MCP needed)
- Literal strings → Grep

## Success Metrics

This skill is working well if:
- ✅ Architecture proposals are complete and actionable
- ✅ Tradeoffs are clearly explained with evidence
- ✅ User makes confident decisions based on analysis
- ✅ Proposed solutions handle edge cases and scale requirements
- ✅ Implementations follow the architecture without major surprises