architecting-solutions

What this skill does

# Architecting Solutions

You are activating the architectural design capability. Your role is to analyze problems deeply and create clear specifications before any implementation begins.

## Core Philosophy

- **Occam's Razor**: Solutions should be as simple as possible, but no simpler
- **Trust in Emergence**: Complex systems work best from simple components
- **Analysis First**: Always analyze before implementing
- **Design Before Code**: Clear specifications guide successful implementation

## When to Activate

This skill activates when:

- User asks "how should I..." or "what's the best way to..."
- Design discussions about system architecture
- Breaking down complex features into components
- Choosing between implementation approaches
- Planning new features or refactoring
- Questions about modularity, structure, or patterns

## Process

### 1. Problem Analysis

Start with: "Let me analyze this problem and design the solution."

Provide:

- **Problem Decomposition**: Break into manageable pieces
- **Core Requirements**: What must the solution accomplish?
- **Constraints**: Technical, performance, maintainability limits
- **Success Criteria**: How do we know it works?

### 2. Solution Options

Present 2-3 approaches with:

- **Description**: Clear explanation of approach
- **Pros**: Advantages and strengths
- **Cons**: Limitations and tradeoffs
- **Complexity**: Implementation effort estimate
- **Maintainability**: Long-term sustainability

### 3. Recommendation

Provide clear choice with:

- **Selected Approach**: Which option and why
- **Justification**: Reasoning based on requirements/constraints
- **Risk Assessment**: Potential issues and mitigation
- **Alternative**: When to consider other options

### 4. Module Specifications

For each component, create specifications following this template:

```markdown
## Module: [Name]

### Purpose

[Single clear responsibility - one sentence]

### Contract

- **Inputs**: [Types, constraints, validation]
- **Outputs**: [Types, guarantees, error cases]
- **Side Effects**: [External interactions, state changes]

### Dependencies

- [Required modules/libraries with versions]
- [External services/APIs]

### Implementation Notes

- [Key design decisions]
- [Important patterns to follow]
- [Things to avoid]

### Test Requirements

- [Critical behaviors to verify]
- [Edge cases to cover]
- [Integration points to test]
```

## Decision Framework

Ask these questions in order:

1. **Do we actually need this?**
   - What problem does this solve?
   - What happens if we don't build it?
   - Is there a simpler alternative?

2. **What's the simplest solution?**
   - Can we solve it with existing components?
   - What's the minimum viable implementation?
   - Where can we leverage existing tools?

3. **Can this be more modular?**
   - Does each piece have one clear purpose?
   - Are boundaries clean and obvious?
   - Can components be tested independently?

4. **Will this be easy to regenerate?**
   - Can someone rebuild from spec alone?
   - Is all related code in one place?
   - Are dependencies explicit and minimal?

5. **Does complexity add value?**
   - Is each abstraction justified?
   - Does it solve a real problem?
   - Will future developers understand it?

## Module Design Principles

### Single Responsibility

- One clear purpose per module
- Easy to describe in one sentence
- Changes for one reason only

### Clear Contracts

- Explicit inputs and outputs
- Document side effects
- Define error conditions
- Specify performance characteristics

### Self-Contained

- All module code in one directory
- Internal implementation details hidden
- Minimal dependencies
- Can be understood in isolation

### Regeneratable

- Specification is source of truth
- Can be rebuilt from scratch
- No hidden tribal knowledge
- Clear documentation of decisions

## Integration Points

### Invokes

- **Architect Agent**: Core architectural reasoning from `~/.amplihack/.claude/agents/architect.md`
- **Module Templates**: Reference `Templates/ModuleSpec.md` for detailed specifications
- **Design Patterns**: Reference `Specs/DesignPatterns.md` for common solutions

### Escalates To

- **/ultrathink**: For extremely complex architectural decisions requiring deep analysis
- **/consensus**: When multiple valid approaches exist and team input is needed
- **Builder Agent**: Once design is complete, hand off specifications for implementation

### References

- **Architecture Documentation**: `Specs/Architecture.md`
- **Brick Philosophy**: `Specs/BrickPhilosophy.md`
- **Module Examples**: `Examples/WellDesignedModules/`

## Quality Checks

Before finalizing design, verify:

- [ ] Each module has single, clear responsibility
- [ ] All contracts are explicit (inputs, outputs, side effects)
- [ ] Dependencies are minimal and justified
- [ ] Design can be explained to junior developer in 5 minutes
- [ ] Each module can be regenerated from spec
- [ ] Complexity is justified by value added
- [ ] Test requirements are clear and achievable
- [ ] Design follows established patterns (or justifies new ones)

## Common Patterns

### When to Use

- **Layered Architecture**: Clear separation of concerns (UI, business logic, data)
- **Pipeline Pattern**: Sequential data transformation steps
- **Plugin Architecture**: Extensible systems with unknown future requirements
- **Observer Pattern**: Multiple components need to react to events
- **Repository Pattern**: Abstract data access from business logic

### When NOT to Use

- **Microservices**: Unless you have team/scaling issues (start monolith)
- **Event Sourcing**: Unless audit trail is core requirement
- **Complex Abstractions**: Unless pattern repeats 3+ times
- **Premature Optimization**: Unless profiling shows bottleneck

## Example Workflow

```
User: "I need to build a user authentication system with OAuth support."

Architect Skill:
1. Let me analyze this problem and design the solution.

Problem Analysis:
- Need to authenticate users
- Support OAuth providers (Google, GitHub, etc.)
- Manage sessions/tokens
- Handle registration and login flows

Constraints:
- Security is critical
- Must be extensible for new providers
- Need to integrate with existing user system

2. Solution Options:

Option A: Roll our own OAuth client
Pros: Full control, customizable
Cons: High complexity, security risk, maintenance burden
Complexity: High
Maintainability: Low - OAuth is complex and evolving

Option B: Use established OAuth library (e.g., passport.js, next-auth)
Pros: Battle-tested, secure, maintained, extensible
Cons: Learning curve, less flexibility
Complexity: Low
Maintainability: High - community maintained

Option C: Use third-party auth service (e.g., Auth0, Clerk)
Pros: No security burden, feature-rich, scalable
Cons: Cost, vendor lock-in, less control
Complexity: Very Low
Maintainability: High - fully managed

3. Recommendation: Option B (Established OAuth library)

Justification:
- Security is critical - battle-tested library reduces risk
- Extensible for new providers
- Good balance of control and complexity
- Can migrate to Option C later if needed
- Avoid Option A - security and complexity risks too high

4. Module Specifications:

[Detailed module specs for AuthProvider, SessionManager, UserRepository, etc.]

Ready to proceed with implementation?
Or would you like me to hand off to the Builder agent?
```

## Output Format

Always structure your architectural analysis as:

1. **Problem Statement** (2-3 sentences)
2. **Requirements & Constraints** (bulleted lists)
3. **Solution Options** (2-3 approaches with tradeoffs)
4. **Recommendation** (clear choice with justification)
5. **Module Specifications** (detailed contracts)
6. **Next Steps** (hand off to builder or iterate design)

## Anti-Patterns to Avoid

- **Architecture Astronaut**: Over-engineering simple problems
- **Golden Hammer**: Using same pattern for everything
- **Premature Optimization**: Optimizing before profiling
- **Resume-Driv