Skip to content

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

architecture

Verified

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 optionsarchitecture (this)
Write an ADRarchitecture (this)
Refactor messy coderefactoring-patterns
Improve code qualityclean-code
Design DB schemadatabase-design
Design API shapeapi-patterns

🎯 Selective Reading Rule

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

FileDescriptionWhen to Read
context-discovery.mdQuestions to ask, project classificationStarting architecture design
trade-off-analysis.mdADR templates, trade-off frameworkDocumenting decisions
pattern-selection.mdDecision trees, anti-patternsChoosing patterns
examples.mdMVP, SaaS, Enterprise examplesReference implementations
patterns-reference.mdQuick lookup for patternsPattern comparison

🔗 Related Skills

SkillUse 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:

DimensionQuestion
CorrectnessDoes it satisfy core requirements safely?
OperabilityIs it observable, debuggable, supportable?
Time-to-ValueHow fast can the team deliver useful value?
Team FitDoes current team expertise support it?
Cost ProfileInfra and implementation cost trajectory
EvolvabilityCan 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: 197kUpdated 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