Architecture evaluation
Apply architecture evaluation whenever the user faces a system design decision — choosing between architectures, evaluating trade-offs, or documenting a technical direction. Triggers on phrases like "evaluate this architecture", "should we use microservices?", "what are the trade-offs?", "is this design scalable?", "architecture decision", "ADR", "system design review", "which database should we use?". Use proactively when the user is about to commit to a technical direction without explicit trade-off analysis.From its SKILL.md
npx -y skills add AndurilCode/craftwork --skill architecture-evaluationAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 7 stars7 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
7.5 KB, as published. Nobody here has run it
Architecture Evaluation
Core principle: Every architecture decision trades quality attributes — optimizing one degrades another. Make trade-offs explicit, document in an ADR, and assess reversibility. The best architecture is the one whose trade-offs the team can live with.
When to Use This Skill
- Choosing between system architectures or technology stacks
- Design review needs structured evaluation, not opinion
- About to commit (database, messaging pattern, deployment model) without documenting trade-offs
- An ADR needs to be produced
- "Should we use X?" where X is an architecture pattern or technology
- A
systems-thinkinganalysis surfaced structural concerns needing architecture-level resolution
Core Methodology
Step 1: Establish Decision Context
- Decision scope: Specific choice on the table (e.g., "monolith vs. microservices for the order system" — not "system design" generally)
- Decision driver: Why now? (new requirement, scaling problem, tech debt, team growth)
- Constraints: Non-negotiables — budget, team size and skills, compliance, existing infra to preserve, timeline
- Stakeholders: engineering, ops, product, security, finance
Step 2: Assess Quality Attributes
For each relevant attribute, assess current state and how each option affects it.
Key attributes (evaluate only those relevant):
- Scalability: 10x load? Scaling unit?
- Reliability: Failure mode? Blast radius?
- Performance: Latency, throughput, resource efficiency under expected and peak load
- Security: Attack surface, data protection, auth boundaries
- Maintainability: Change effort? How many teams must coordinate for a typical change?
- Operability: Deployment complexity, observability, incident response, on-call burden
- Cost: Infra, development, operational over the time horizon
Rate each option per attribute: Strong / Adequate / Weak — with one-sentence justification.
Step 3: Map Trade-Offs
Architecture trade-offs are rarely "good vs. bad" — they are "more X = less Y."
Common pairs:
- Consistency vs. availability (CAP)
- Simplicity vs. flexibility
- Performance vs. maintainability
- Development speed vs. operational complexity
- Cost vs. reliability
For each, state which way each option leans and why. This is the core of the evaluation.
Step 4: Evaluate Architecture Options
For each candidate:
- Fit to constraints: Satisfies all non-negotiables from Step 1?
- Quality attribute profile: Strong/weak where (from Step 2)?
- Adoption preconditions: What must be true to succeed? (microservices need CI/CD maturity, observability, team autonomy)
- Migration path: Incremental or big-bang cutover?
Eliminate options that violate constraints. Compare remaining via attribute profiles and trade-off positions.
Step 5: Assess Evolutionary Characteristics
How does this decision age?
- Reversibility: Hard to change in 1 year? 3 years? Switching cost?
- Lock-in vectors: Vendor, data model, API contract, team knowledge
- Migration cost if wrong: Time and money to unwind
- Optionality: Does this open or close future moves? Prefer optionality-preserving when uncertain
Step 6: Write the Architecture Decision Record
Produce an ADR — also serves as handoff to execution-planning via Contract E.
Standard format:
- Title: Short, descriptive
- Status: Proposed / Accepted / Deprecated / Superseded
- Context: Situation, constraints, forces (Steps 1-3)
- Decision: Chosen option + primary reasons
- Consequences: Positive, negative, operational, team, known risks
- Alternatives rejected: What was considered, why not chosen
Output Format
🎯 Decision Context
- Decision: [what's being decided]
- Driver: [why now]
- Constraints: [non-negotiables]
⚖️ Quality Attribute Assessment
| Attribute | Option A | Option B | Option C |
|---|---|---|---|
| Scalability | [Strong/Adequate/Weak — reason] | [rating — reason] | [rating — reason] |
| Reliability | [rating — reason] | [rating — reason] | [rating — reason] |
| Maintainability | [rating — reason] | [rating — reason] | [rating — reason] |
| Operability | [rating — reason] | [rating — reason] | [rating — reason] |
| Cost | [rating — reason] | [rating — reason] | [rating — reason] |
⚖️ Trade-Off Map
| Trade-Off | Option A leans toward | Option B leans toward |
|---|---|---|
| [Simplicity vs. Flexibility] | [direction + why] | [direction + why] |
| [Cost vs. Reliability] | [direction + why] | [direction + why] |
📋 Architecture Decision Record
- Title: [ADR-NNN: title]
- Status: Proposed / Accepted
- Context: [from Steps 1-3]
- Decision: [chosen option + reasons]
- Consequences:
- Positive: [what improves]
- Negative: [what degrades]
- Operational: [deployment, monitoring, on-call]
- Alternatives rejected:
- [Option]: rejected because [reason]
🔄 Evolutionary Assessment
- Reversibility: Easy / Moderate / Difficult — [justification]
- Lock-in risks: [vendor, data model, API, team knowledge]
- Migration cost if wrong: [estimated effort]
- Optionality: [future moves enabled or foreclosed]
📋 Execution-Planning Handoff (Contract E)
- Decision: [from ADR]
- Constraints: [non-negotiable attributes, budget, team, compliance]
- Lock-in risks: [from evolutionary assessment]
- Migration requirements: [if replacing existing]
- Sequencing hints: [build-first based on dependencies]
- Known risks: [from inversion-premortem stress test, if run]
Common Traps
Resume-Driven Architecture: Choosing tech because the team wants to learn it, not because it fits. Microservices, Kubernetes, event sourcing are powerful — and unnecessary for most systems.
Ignoring adoption preconditions: Microservices need CI/CD, observability, team autonomy. Event-driven needs idempotency discipline and debugging tooling. Evaluate whether the team can operate it, not just build it.
Optimizing for the wrong attribute: Designing for millions when you have hundreds. Maintainability and operability usually matter more than scalability.
Irreversibility blindness: Treating all decisions as equally weighted. Database choice locks in for years; caching strategy changes in a sprint. Spend evaluation effort proportional to reversibility cost.
Comparison without constraints: Evaluating in the abstract instead of against this team, this budget, this timeline. The best architecture in theory is irrelevant if the team can't build or operate it.
Thinking Triggers
- "What quality attributes are in tension, and which side are we choosing?"
- "What must be true about our team and infra for this option to succeed?"
- "How hard is it to reverse this in two years?"
- "Am I choosing this because it fits the problem, or because it's intellectually interesting?"
- "Migration path — incremental or big-bang?"