| name | Architecture Design |
| description | Evaluate system design, recommend refactors, review boundaries and coupling.
Use when: Evaluating a new feature design before implementation, choosing between implementation approaches, reviewing component boundaries, or creating architectural decision records. Also use when refactoring existing code for maintainability.
Don't use when: Reviewing a specific PR's code changes (use code-review). Don't use for debugging runtime failures (use debug-troubleshooting). Don't use for Kubernetes manifest or infrastructure design (use the appropriate ops skill). Don't use for writing tests (use testing-strategies).
Outputs: Architecture analysis document with current state assessment, recommendations with tradeoffs, and incremental migration steps.
|
| requires | [] |
Architecture Design
Routing
Use This Skill When
- Evaluating a new feature design before implementation
- Choosing between two or more implementation approaches
- Refactoring existing code to improve maintainability
- Reviewing system boundaries and interfaces
- Creating an ADR (Architectural Decision Record)
- Someone asks "how should we build this?" or "should we refactor this?"
Don't Use This Skill When
- Reviewing a specific PR diff → use code-review
- Debugging a runtime error → use debug-troubleshooting
- Designing Kubernetes manifests or Flux config → use ops skills
- Writing or designing test cases → use testing-strategies
- The question is about deployment process → use gitops-deploy
Analysis Framework
1. Understand Current State
git clone https://github.com/rajsinghtech/<repo>.git /tmp/arch-review
cd /tmp/arch-review
find . -type f -name "*.go" -o -name "*.ts" -o -name "*.py" | head -50
cat go.mod 2>/dev/null || cat package.json 2>/dev/null || cat requirements.txt 2>/dev/null
2. Evaluate
- Separation of concerns — Does each module have a clear, single responsibility?
- Dependencies — Are dependency directions clean? Circular dependencies?
- Interfaces — Are boundaries well-defined? Can components be tested independently?
- Data flow — How does data move through the system? Any unnecessary transformations?
- Error handling — Is it consistent? Do errors propagate with context?
- Scalability — What breaks first under load? What's the bottleneck?
3. Recommend
Provide recommendations with:
- What to change
- Why it improves the system
- How to migrate (incremental steps, not big-bang rewrites)
- Tradeoffs — what you gain vs what you give up
Architecture Review Template
## Architecture Review: <Component/System>
### Current State
<Overview of the current architecture, key components, and how they interact>
### Strengths
- <What's working well>
- <Good patterns in use>
### Concerns
| Concern | Severity | Impact |
|---------|----------|--------|
| <description> | High/Med/Low | <what breaks or degrades> |
### Recommendations
#### 1. <Recommendation Title>
- **What:** <specific change>
- **Why:** <benefit>
- **How:** <migration steps>
- **Tradeoff:** < >
ADR (Architectural Decision Record) Template
# ADR-<number>: <Title>
**Status:** Proposed | Accepted | Deprecated | Superseded
**Date:** <date>
**Deciders:** <who>
## Context
<What is the issue or question that needs a decision?>
## Decision
<What is the change that we're proposing/doing?>
## Consequences
### Positive
- <benefit>
### Negative
- <cost or risk>
### Neutral
- <observation>
Edge Cases
- Premature optimization: If the system works and is maintainable, don't refactor for theoretical future scale
- Brownfield vs greenfield: Existing code has existing users — always consider migration cost
- Cross-repo dependencies: Changes spanning openclaw-workspace and kubernetes-manifests need coordinated PRs
