Architecture Design

Architecture Design Skill

Architecture Decision Record (ADR) Format

When making technical decisions, document them as ADRs:

# ADR-{number}: {Title}

## Status
Proposed | Accepted | Deprecated | Superseded

## Context
What is the issue that we're seeing that is motivating this decision?

## Decision
What is the change that we're proposing and/or doing?

## Consequences
What becomes easier or more difficult to do because of this change?

## Alternatives Considered
What other approaches were evaluated and why were they rejected?

Technical Design Checklist

Before submitting a technical design for review:

• Component boundaries are clearly defined
• Data flow is documented (inputs, transformations, outputs)
• API contracts specify request/response schemas
• Error handling strategy is defined
• State management approach is documented
• Dependencies (external services, libraries) are listed
• Performance considerations are addressed
• Security implications are assessed
• Migration strategy (if changing existing code) is defined
• Task decomposition recommendations are included

Drift Resolution Protocol

When parallel coding agents diverge from the design:

1. Identify the drift: What specifically diverged?
2. Classify severity:
   • Minor: Naming, file organization (resolve with convention)
   • Moderate: Different patterns for same problem (pick one, document why)
   • Major: Incompatible approaches (requires design revision)
3. Write resolution document:

   # Drift Resolution: {Description}
   
   ## Agents Involved
   - Agent A: {approach}
   - Agent B: {approach}
   
   ## Resolution
   {Which approach wins and why}
   
   ## Required Changes
   - Agent A: {what to change}
   - Agent B: {what to change}
   
   ## Design Doc Updates
   {What to add/change in the original design}
   

4. Communicate to all affected agents
5. Update the original design doc

Spelunk Request Templates