architecture-decision

Name: architecture-decision
Author: softspark

161stars21forks

How to install architecture-decision?

softspark/ai-toolkit/architecture-decision

$npx -y skills add softspark/ai-toolkit --skill architecture-decision

Installs into the current project.

Summary

Architecture decisions in ADR/RFC/RFD format: context, constraints, options, recommendation. Triggers: ADR, RFC, RFD, trade-offs, design choice, pick between, evaluate approach.

Files · 1

View on GitHub

SKILL.md

1	# Architecture Decision Skill
2
3	## Core Philosophy: "Everything is a Trade-off"
4	There are no "best solutions", only solutions with the right set of trade-offs for the specific context.
5
6	## Decision Making Process (RFD / RFC)
7	1. Context: What is the problem? Why now?
8	2. Constraints: Budget, Time, Skillset, Legacy.
9	3. Options: Propose at least 3 viable options.
10	4. Trade-off Analysis: Compare constraints vs options.
11	5. Recommendation: Choose one and justify.
12
13	## Trade-off Analysis Matrix (Template)
14
15	\| Feature \| Option A (e.g. SQL) \| Option B (e.g. NoSQL) \| Option C (e.g. File) \|
16	\|---------\|---------------------\|-----------------------\|----------------------\|
17	\| Scalability \| Medium (Vertical) \| High (Horizontal) \| Low \|
18	\| Consistency \| Strong (ACID) \| Eventual (BASE) \| N/A \|
19	\| Complexity \| Low (Known) \| Medium (New tech) \| Low \|
20	\| Cost \| $$ \| $$$ \| $ \|
21
22	## Architecture Note
23	When a decision is made, document it.
24
25	```markdown
26	# Architecture Note: Use PostgreSQL for Main Database
27
28	## Status
29	Accepted
30
31	## Context
32	We need a reliable, relational database for user data...
33
34	## Decision
35	We will use PostgreSQL 16.
36
37	## Consequences
38	- Positive: ACID compliance, rich ecosystem.
39	- Negative: Scaling writes requires sharding later.
40	```
41
42	## Critical Factors to Evaluate
43	- Reliability (Availability, Fault tolerance)
44	- Scalability (Throughput, Latency)
45	- Maintainability (Simple vs Easy, Ecosystem)
46	- Security (AuthN/Z, Encryption)
47	- Cost (Infrastructure, License, Cognitive load)
48
49	## Rules
50
51	- MUST present at least 3 viable options, including "status quo / do nothing" when relevant
52	- MUST state constraints (budget, time, team skillset, legacy) before enumerating options — options without constraints are arbitrary
53	- NEVER recommend an option without explicitly naming its failure mode and what would trigger revisiting the decision
54	- CRITICAL: the output is a document (ADR / RFC / RFD), not code changes. Code work belongs in `/plan` or `/refactor-plan`.
55	- MANDATORY: `Consequences` section names both Positive and Negative effects. A decision with only upside is not honestly analysed.
56
57	## Gotchas
58
59	- "Status quo" is a genuine option and often the right one for constrained teams. Omitting it biases the analysis toward change for change's sake.
60	- ADRs are append-only. A reversed decision gets a new ADR with `Status: Supersedes ADR-N`, not an in-place edit of the original — the history of thinking matters more than the current state.
61	- Qualitative scales (High / Medium / Low) without anchors are hand-waving. When scoring, pin each level to a measurable threshold (e.g., "High scalability = 10k req/s at p95 < 100ms on 2 nodes").
62	- "We might use X" and "We will try X" are not decisions — they are deferrals. A valid ADR states the chosen option unconditionally; if you cannot, the decision is not ready.
63	- Political constraints (team expertise, vendor relationships, executive preferences) are first-class constraints. Hiding them behind technical language produces ADRs that get silently ignored — name them explicitly in the Constraints section.
64
65	## When NOT to Load
66
67	- To find what architectural problems exist — use `/architecture-audit` (discovery) before this skill (decision)
68	- To plan implementation of an already-decided option — use `/plan` or `/refactor-plan`
69	- To design a single module's interface — use `/design-an-interface`
70	- When fewer than 2 options exist — there is no decision to make; document the constraint instead
71	- For runtime configuration choices (flag values, timeouts) — those are operational, not architectural

People who liked this also viewed

6 picks

Type

architecture-decision

161stars21forks

View on GitHub

How to install architecture-decision?

softspark/ai-toolkit/architecture-decision

$npx -y skills add softspark/ai-toolkit --skill architecture-decision

Installs into the current project.

Summary

Architecture decisions in ADR/RFC/RFD format: context, constraints, options, recommendation. Triggers: ADR, RFC, RFD, trade-offs, design choice, pick between, evaluate approach.

Files · 1

View on GitHub

SKILL.md

1	# Architecture Decision Skill
2
3	## Core Philosophy: "Everything is a Trade-off"
4	There are no "best solutions", only solutions with the right set of trade-offs for the specific context.
5
6	## Decision Making Process (RFD / RFC)
7	1. Context: What is the problem? Why now?
8	2. Constraints: Budget, Time, Skillset, Legacy.
9	3. Options: Propose at least 3 viable options.
10	4. Trade-off Analysis: Compare constraints vs options.
11	5. Recommendation: Choose one and justify.
12
13	## Trade-off Analysis Matrix (Template)
14
15	\| Feature \| Option A (e.g. SQL) \| Option B (e.g. NoSQL) \| Option C (e.g. File) \|
16	\|---------\|---------------------\|-----------------------\|----------------------\|
17	\| Scalability \| Medium (Vertical) \| High (Horizontal) \| Low \|
18	\| Consistency \| Strong (ACID) \| Eventual (BASE) \| N/A \|
19	\| Complexity \| Low (Known) \| Medium (New tech) \| Low \|
20	\| Cost \| $$ \| $$$ \| $ \|
21
22	## Architecture Note
23	When a decision is made, document it.
24
25	```markdown
26	# Architecture Note: Use PostgreSQL for Main Database
27
28	## Status
29	Accepted
30
31	## Context
32	We need a reliable, relational database for user data...
33
34	## Decision
35	We will use PostgreSQL 16.
36
37	## Consequences
38	- Positive: ACID compliance, rich ecosystem.
39	- Negative: Scaling writes requires sharding later.
40	```
41
42	## Critical Factors to Evaluate
43	- Reliability (Availability, Fault tolerance)
44	- Scalability (Throughput, Latency)
45	- Maintainability (Simple vs Easy, Ecosystem)
46	- Security (AuthN/Z, Encryption)
47	- Cost (Infrastructure, License, Cognitive load)
48
49	## Rules
50
51	- MUST present at least 3 viable options, including "status quo / do nothing" when relevant
52	- MUST state constraints (budget, time, team skillset, legacy) before enumerating options — options without constraints are arbitrary
53	- NEVER recommend an option without explicitly naming its failure mode and what would trigger revisiting the decision
54	- CRITICAL: the output is a document (ADR / RFC / RFD), not code changes. Code work belongs in `/plan` or `/refactor-plan`.
55	- MANDATORY: `Consequences` section names both Positive and Negative effects. A decision with only upside is not honestly analysed.
56
57	## Gotchas
58
59	- "Status quo" is a genuine option and often the right one for constrained teams. Omitting it biases the analysis toward change for change's sake.
60	- ADRs are append-only. A reversed decision gets a new ADR with `Status: Supersedes ADR-N`, not an in-place edit of the original — the history of thinking matters more than the current state.
61	- Qualitative scales (High / Medium / Low) without anchors are hand-waving. When scoring, pin each level to a measurable threshold (e.g., "High scalability = 10k req/s at p95 < 100ms on 2 nodes").
62	- "We might use X" and "We will try X" are not decisions — they are deferrals. A valid ADR states the chosen option unconditionally; if you cannot, the decision is not ready.
63	- Political constraints (team expertise, vendor relationships, executive preferences) are first-class constraints. Hiding them behind technical language produces ADRs that get silently ignored — name them explicitly in the Constraints section.
64
65	## When NOT to Load
66
67	- To find what architectural problems exist — use `/architecture-audit` (discovery) before this skill (decision)
68	- To plan implementation of an already-decided option — use `/plan` or `/refactor-plan`
69	- To design a single module's interface — use `/design-an-interface`
70	- When fewer than 2 options exist — there is no decision to make; document the constraint instead
71	- For runtime configuration choices (flag values, timeouts) — those are operational, not architectural

People who liked this also viewed

6 picks

Type