Skip to content

MustafaKucukcoskun/Refine-agent-kit / .agents/skills/architecture

architecture

Verified

FileKindSize
SKILL.mdskill md4.4 KB
context-discovery.mdmarkdown1.6 KB
examples.mdmarkdown2.4 KB
pattern-selection.mdmarkdown2.6 KB
patterns-reference.mdmarkdown2.3 KB
trade-off-analysis.mdmarkdown1.5 KB
---
name: architecture
description: Architectural decision-making with decision artifacts — constraint envelope, option matrix, trade-off scoring, ADR-Lite, and risk register. Use when choosing tech stack, picking between REST/GraphQL/gRPC, designing a migration, making a tooling decision, or writing an ADR. Do NOT use for code style (that's clean-code) or line-level refactoring (that's refactoring-patterns). Keywords: architecture, ADR, decision, trade-off, design, migration, pick, choose, evaluate, stack.
allowed-tools: Read, Glob, Grep
---

# Architecture Decision Framework

> "Requirements drive architecture. Trade-offs inform decisions. ADRs capture rationale."

## When to Use vs. Related Skills

| You want to… | Use |
|---|---|
| Choose between 2+ tech options | **architecture** (this) |
| Write an ADR | **architecture** (this) |
| Refactor messy code | `refactoring-patterns` |
| Improve code quality | `clean-code` |
| Design DB schema | `database-design` |
| Design API shape | `api-patterns` |

## 🎯 Selective Reading Rule

**Read ONLY files relevant to the request!** Check the content map, find what you need.

| File                    | Description                              | When to Read                 |
| ----------------------- | ---------------------------------------- | ---------------------------- |
| `context-discovery.md`  | Questions to ask, project classification | Starting architecture design |
| `trade-off-analysis.md` | ADR templates, trade-off framework       | Documenting decisions        |
| `pattern-selection.md`  | Decision trees, anti-patterns            | Choosing patterns            |
| `examples.md`           | MVP, SaaS, Enterprise examples           | Reference implementations    |
| `patterns-reference.md` | Quick lookup for patterns                | Pattern comparison           |

---

## 🔗 Related Skills

| Skill                             | Use For                 |
| --------------------------------- | ----------------------- |
| `@[skills/database-design]`       | Database schema design  |
| `@[skills/api-patterns]`          | API design patterns     |
| `@[skills/deployment-procedures]` | Deployment architecture |

---

## Core Principle

**"Simplicity is the ultimate sophistication."**

- Start simple
- Add complexity ONLY when proven necessary
- You can always add patterns later
- Removing complexity is MUCH harder than adding it

---

## Validation Checklist

Before finalizing architecture:

- [ ] Requirements clearly understood
- [ ] Constraints identified
- [ ] Each decision has trade-off analysis
- [ ] Simpler alternatives considered
- [ ] ADRs written for significant decisions
- [ ] Team expertise matches chosen patterns

---

## Decision Quality Protocol (MANDATORY)

For each architectural milestone, produce a **Decision Packet**.

### Decision Packet Structure

1. Problem statement and desired outcome.
2. Constraint envelope (hard/soft/open).
3. Option space (minimum 3 viable options).
4. Trade-off scoring matrix.
5. Chosen option + rationale.
6. Risks, mitigations, and rollback strategy.
7. Revisit triggers (when to re-open this decision).

### Trade-off Scoring Matrix

Score each option from 1 to 5 on these dimensions:

| Dimension     | Question                                    |
| ------------- | ------------------------------------------- |
| Correctness   | Does it satisfy core requirements safely?   |
| Operability   | Is it observable, debuggable, supportable?  |
| Time-to-Value | How fast can the team deliver useful value? |
| Team Fit      | Does current team expertise support it?     |
| Cost Profile  | Infra and implementation cost trajectory    |
| Evolvability  | Can it adapt to next-stage product needs?   |

Use weighted scoring only when stakeholders agree on priorities.

### Unknown-Unknown Scan

Before finalizing architecture, answer:

1. Which assumptions are least validated?
2. Which integration points can fail silently?
3. What breaks first at 10x scale?
4. Which decision creates irreversible lock-in?

If uncertainty is high, prefer reversible decisions and staged rollout.

---

## SaaS and Product Systems Guidance

When user asks for full SaaS/system design, avoid single-path recommendations.

Always provide:

1. Baseline architecture (fastest reliable path).
2. Scale-ready variant (for growth stage).
3. Frontier variant (higher upside, higher risk).

Then recommend one path based on explicit constraints, not preference bias.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall