architecture

/architecture

If you see unfamiliar placeholders or need to check which tools are connected, see CONNECTORS.md. This skill follows the SKILL-CONTRACT.md — it appends a machine_output block.

Create an Architecture Decision Record (ADR) or evaluate a system design. For a scored, staff-level review of a whole system (not a single decision), use the architecture-review skill.

Usage

/architecture $ARGUMENTS

Modes

Create an ADR: "Should we use Kafka or SQS for our event bus?" Evaluate a design: "Review this microservices proposal" System design: "Design the notification system for our app"

See the system-design skill for detailed frameworks on requirements gathering, scalability analysis, and trade-off evaluation.

Output — ADR Format

# ADR-[number]: [Title]

**Status:** Proposed | Accepted | Deprecated | Superseded
**Date:** [Date]
**Deciders:** [Who needs to sign off]

## Context
[What is the situation? What forces are at play? Include technical constraints, current-state limitations, and business drivers.]

## Decision
[What is the change we're proposing? State clearly and directly.]

## Options Considered

### Option A: [Name]
| Dimension | Assessment |
|-----------|------------|
| Complexity | [Low/Med/High] |
| Cost | [Assessment] |
| Scalability | [Assessment] |
| Team familiarity | [Assessment] |

**Pros:**
- [Pro 1]
- [Pro 2]

**Cons:**
- [Con 1]
- [Con 2]

### Option B: [Name]
| Dimension | Assessment |
|-----------|------------|
| Complexity | [Low/Med/High] |
| Cost | [Assessment] |
| Scalability | [Assessment] |
| Team familiarity | [Assessment] |

**Pros:**
- [Pro 1]
- [Pro 2]

**Cons:**
- [Con 1]
- [Con 2]

## Trade-off Analysis
[Key trade-offs between options with clear reasoning. Explain why the selected option was chosen despite its associated cons.]

## Consequences
- **(+) Positive:** [What becomes easier, enabled, or decoupled as a result of this decision]
- **(-) Negative:** [What becomes harder, more complex, or what architectural debt/consequences we are actively accepting]
- **(~) Neutral:** [Changes that are neither inherently good nor bad, but alter standard operating procedures]

## Action Items
1. [ ] [Implementation step]
2. [ ] [Follow-up verification or telemetry monitoring setup]

Output Contract

This is a process skill — it produces an ADR, so it OMITS the scorecard (use architecture-review to score a system). Append a machine_output block per SKILL-CONTRACT.md; the decision and its accepted consequences go in findings.

machine_output:
  skill: architecture
  version: "1.0"
  timestamp: <ISO-8601>
  status: complete
  findings:
    - id: A1
      severity: medium
      category: decision
      location: event-bus
      description: Chose SQS over Kafka; accepts a lower throughput ceiling for lower ops burden
  recommendations:
    - id: R1
      action: Revisit the decision if sustained throughput exceeds 3k msg/s
      effort: low
      addresses: [A1]
  artifacts:
    - adr
  next_actions:
    - skill: architecture-review
      reason: Validate the decision in the context of the whole system
    - skill: documentation
      reason: Publish the ADR into the decision log

If Connectors Available

If ~~knowledge base is connected:

• Search for prior ADRs and design docs
• Find relevant technical context

If ~~project tracker is connected:

• Link to related epics and tickets
• Create implementation tasks

Tips

1. State constraints upfront — "We need to ship in 2 weeks" or "Must handle 10K rps" shapes the answer.
2. Name your options — Even if you're leaning one way, I'll give a more balanced analysis with explicit alternatives.
3. Include non-functional requirements — Latency, cost, team expertise, and maintenance burden matter as much as features.