Given a feature/project's context (scale, team, timeline, domain, constraints — via batched AskUserQuestion rounds), surfaces candidate architectural approaches, defaulting to the simplest option that works, grounded in internal decision trees plus current web-researched practice for the specific domain (offline-first sync, search, background jobs, multi-tenancy, real-time collaboration, and others as they come up) — then writes its own deep-dive-style selection document. Use when asked "what methods/approaches can I use for this", "what's the right architecture/stack for this", or before committing to a pattern (monolith vs. microservices, sync vs. event-driven, Repository vs. direct ORM, REST vs. GraphQL, how much DDD). NOT for the PRD (`breakdown-feature-prd`), validating a vague idea (`brainstorming`), a full implementation plan (`breakdown-feature-implementation`), or the ADR (`documentation-and-adrs`) — this picks the approach; those build it out or record it later.
Curated from a community-sourced "architecture" skill (context discovery, pattern-selection decision trees, trade-off analysis) found archived and unexposed in archive/skills-community/. Rewritten to stop short of re-teaching what this plugin's other skills already own — ADR templates, Clean/Hexagonal/DDD depth, API/DB pattern depth, named libraries — and to hand off to them instead.
Overview
Before a feature or a project commits to a pattern, someone has to answer "what are my actual options here, and which one fits this context" — not "which pattern do I personally reach for by habit." This skill runs that selection pass like a real consult, not a lookup: interrogate the context thoroughly via AskUserQuestion until there's genuinely enough to reason from, check this skill's own decision trees for the cross-cutting structural concerns, and search the web for how the exact domain at hand (offline-first sync, search, background job processing, real-time collaboration, multi-tenant isolation, and anything else with real established prior art — these are examples, not the full list) is actually being solved right now — then come back with 1-3 real candidates per concern, each with pros/cons/complexity and the condition under which it stops being the right call, written up as a saved document. Not a single prescribed answer presented as the only option, and not a lookup table answer when the domain has moved past what a static table captures.
This applies the same way whether the input is a single feature ("what approach should I use for notifications/search/a workflow engine") or a whole new project ("what should the architecture/stack look like for this app") — the context-gathering and decision trees below don't change shape, only the scope of what's being decided.
Why This Skill Exists: Counteract Anchoring, Not Just Complexity
Left alone, both humans and agents tend to reach for whatever approach occurs to them first — the familiar one, the one just used last time — and build on it without ever actually comparing it to the alternatives. That's the gap this skill closes: it forces the comparison to actually happen (the decision trees, the web research, the candidate table) before any approach gets picked, including the one that felt obvious going in.
This cuts both ways, and neither direction is the "safe" one to assume without checking:
The obvious approach is sometimes genuinely correct — plain CRUD often is best served by a plain CRUD implementation, and this skill isn't here to manufacture complexity where none is warranted (see the Core Principle below). When the comparison confirms the obvious choice, that's a legitimate outcome.
The obvious approach is sometimes wrong, or incomplete — the first idea that comes to mind is often just the most familiar one, not the one that actually fits this project's scale/team/timeline, or the one current domain practice has moved toward. Skipping the comparison because an answer already "feels right" is exactly the failure mode this skill exists to prevent.
The test is never "which one do I already believe is right" — it's "did I actually run the comparison before answering." An obvious answer that's survived Steps 2-5 is a validated recommendation; an obvious answer that skipped them is just an assumption wearing this skill's output format.
Core Principle: Default to the Simplest Effective Option
Once the comparison above has actually happened, this is the tie-breaker: at every step below — the decision trees, the web research, the final candidate table — the simplest option that actually solves the stated problem wins, unless a specific, confirmed requirement rules it out. Microservices, full DDD, CRDTs, event sourcing, and similar heavyweight patterns are never the default recommendation; they're the exception, reached for only when the gating questions and anti-pattern checks below are all cleared. "More sophisticated" and "more correct" are not the same claim — don't let a pattern's reputation stand in for it actually being justified by this context's gathered facts. This principle is not license to skip straight to an answer, obvious or otherwise, without running the steps that justify it — see above.
When to Use
Asked "what methods/approaches can I use for this" about a specific feature or an entire project
Choosing between architectural shapes before writing code: monolith vs. modular monolith vs. microservices, synchronous vs. event-driven, Repository/Unit-of-Work vs. direct ORM access, how much (if any) DDD, REST vs. GraphQL vs. gRPC at the top level
Starting a new project or a feature that implies a whole domain (notifications, multi-tenancy, payments, search, a workflow engine) and no approach has been chosen yet
A chosen pattern is being second-guessed ("is microservices actually justified here?") and needs re-examining against the project's real scale/team/timeline, not just defended by habit
When NOT to use:
Requirements aren't written down yet at all — use spec-driven-development or breakdown-feature-prd first; this skill needs something concrete to evaluate against, even if it's just "a feature idea plus a few answered questions," not nothing
The approach is already chosen and the task is building it out — use breakdown-feature-implementation (full plan) or incremental-implementation (build it)
The ask is really "is this idea worth building at all" — that's brainstorming, one level up from this skill
Writing up the decision once it's made — documentation-and-adrs (and architecture-decision-records for the ADR mechanics) own that, using this skill's output as their Alternatives Considered
Process
Step 1: Gather Context First — Thoroughly, in Batched Rounds
Don't suggest an architecture before knowing what it's for, and don't settle for a thin first pass either — the whole point of this skill is reasoning from real context, not from a generic template. Ask via AskUserQuestion in batched rounds (several related questions per round, not one question per round) and keep going across more than one round when the use case has real sub-decisions worth asking about — the same scaling discipline deep-dive uses: more rounds for a use case that implies several independent sub-decisions (an offline-first app raises sync strategy, conflict resolution, and connectivity-detection as three separate things worth asking about), one tight round for something genuinely simple. Stop once the axes below are actually answered, not after an arbitrary number of rounds — padding with questions that don't change the recommendation is as much a failure as not asking enough.
If an existing codebase already answers some of these (an existing stack, an existing team size visible from the repo/org), read that first and only ask about what's left — don't make the user restate what's already observable.
Step 2: Search the Web for Current Best Practice in the Specific Domain
The decision trees in Step 3 cover cross-cutting structural concerns (data access, business rules, scaling, real-time) that don't change much year to year. They do not cover domain-specific prior art — how offline-first sync is actually being built right now, what a real-time collaboration engine looks like today, how search relevance or multi-tenant isolation is typically solved — and that's exactly the part a static internal table goes stale on fastest.
Once the feature/domain is known from Step 1, identify whether it's the kind of problem with real, named, current prior art (offline-first, real-time collaboration/CRDTs, search, recommendation, payments compliance, multi-tenancy isolation models, and similar well-trodden domains usually are; a plain CRUD feature usually isn't). If so:
Check references/architecture-domain-playbooks.md first — it's seeded from real web research for a handful of common domains, each dated. If it already covers this domain and the "last checked" date is recent, it's a usable starting point.
Either way, run a fresh WebSearch (start with mode: "standard"; go to "extended" if the first pass comes back thin, generic, or possibly outdated) to confirm or refresh it — this is a fast-moving area, and the reference file is a starting point, never a substitute for checking. Find how this specific problem is being approached currently: named strategies, named tools/libraries/services genuinely in current use for it, and the trade-offs people actually report between them.
Ground every option this surfaces in what the search actually returned — cite what was found, don't present a plausible-sounding approach as current practice without having checked. If search comes back thin or inconclusive, say so plainly rather than filling the gap with an invented-sounding answer.
If this uncovers a domain not yet in the playbook reference, add it there in the same shape (see that file's own "Adding a New Playbook Entry" section) so the next feature in the same domain starts from something instead of zero.
Fold the result into the candidate table (Step 5 below) as its own set of options alongside whatever the decision trees in Step 3 produced — domain-specific and structural concerns both show up there, not as two disconnected outputs.
Skip this step outright for a feature with no real domain-specific prior art to speak of (a plain internal CRUD screen, for instance) — it isn't needed everywhere, only where the "best practice" actually depends on current, fast-moving domain knowledge the internal decision trees were never meant to capture.
Step 3: Run the Decision Trees Per Concern
Work through references/architecture-decision-trees.md's four concern-specific trees (data access complexity, business rules complexity, independent scaling, real-time requirements) for whatever this feature/project actually touches — treat each concern independently, since a project can land on "Repository pattern" for data access and "simple REST" for its API in the same breath. That reference also holds the three gating questions every pattern must clear before it's recommended (what problem does it solve here, is there a simpler alternative, can it be deferred) — this is the mechanical form of the Core Principle above, apply it every time, not just when a pattern feels obviously heavy.
Step 4: Check Against Known Anti-Patterns
Check whatever Step 3 recommended against the anti-pattern table in references/architecture-decision-trees.md. If a recommendation shows up there without its stated condition actually being true for this project, that's the signal to downgrade to the simpler alternative in the same row — not to justify the complex one after the fact.
Step 5: Present Candidates With Trade-offs, Not One Verdict
For each real decision point, give the options as a table, not a single recommendation stated as fact:
| Option | Pros | Cons | Complexity | When this is the right call |
|---|---|---|---|---|
| [Option A] | ... | ... | Low | [the condition under which A fits] |
| [Option B] | ... | ... | High | [the condition under which B fits] |
State which option fits this project's Step 1 answers and why — but as a recommendation the user can push back on, not a decision already made on their behalf. This table is the raw material for Step 7's document (and, later, for an ADR's Alternatives Considered) — it is not itself an ADR, and it doesn't get written up as one here.
Step 6: Hand Off the Depth to the Skill That Owns It
This skill's job stops at "here's the shape and why" — the next layer of depth for whichever shape gets picked belongs elsewhere:
Once you've picked...
Go deeper with
Repository/DDD/Clean/Hexagonal internals
architecture-patterns
The actual database schema, indexing, ORM choice
database-design (or database-architect)
REST vs. GraphQL vs. gRPC specifics, endpoint/contract design
api-patterns / api-and-interface-design
A specific named library within the chosen category
references/library-reuse.md
Turning the chosen approach into a full technical plan
breakdown-feature-implementation
Recording the decision as a historical ADR once it ships
Re-deriving any of these inline instead of handing off is exactly the duplication this plugin's own contributing rules forbid — point there, don't restate it. Writing up the selection itself is the one exception: this skill owns that output directly (Step 7 below), the same way deep-dive owns its own spec file rather than handing that off.
Step 7: Produce the Two Outputs
Modeled directly on how deep-dive closes out its own interrogation — two outputs, not a hand-off to another skill:
Output A — the Desired Approach, in prose. 2-3 paragraphs that state the recommended direction for every concern decided above (data access, business rules, scaling, real-time, and any domain-specific practice from Step 2) as one dense instruction — specific enough to hand straight to breakdown-feature-implementation or incremental-implementation without either of them having to re-derive the reasoning.
Output B — the detailed selection file:
# Architecture Approach: [Feature/Project Name]
## Context
[Scale/Team/Timeline/Domain/Constraints from Step 1, stated plainly — this is what every decision below is actually grounded in.]
## [Concern Name] — e.g. Data Access, Business Rules, Scaling, Real-time, or a domain-specific concern from Step 2
**Candidates considered:**
| Option | Pros | Cons | Complexity | When this is the right call |
|---|---|---|---|---|
| ... | ... | ... | ... | ... |
**Decision:** [the recommended option]
**Rationale:** [why, tied to Step 1's actual answers — not a generic justification]
**Gating questions passed:** [problem solved / simpler alternative checked / deferrable checked — per references/architecture-decision-trees.md]
**Anti-pattern check:** [confirmed clear of references/architecture-decision-trees.md's anti-pattern table, or noted if a condition isn't fully met]
... one section per concern actually decided ...
## Out of Scope
- [What this selection explicitly doesn't decide, and why — e.g. "specific database indexing strategy: see database-design"]
## Open Questions
- [Any concern where more than one candidate is still genuinely live, left for the user to break the tie on, rather than silently picked here]
Save to approach-selections/<feature-slug>.md under the project's external output location (see references/external-output-paths.md) — outside the project's own repo, never a path git in this project tracks or ignores. Create the directory if it doesn't exist. If a file for this feature already exists, ask whether to update it in place or start a new one (<feature-slug>-2.md). This is a distinct subpath from specs/ — this skill's output is upstream of spec-driven-development and breakdown-feature-implementation, not a replacement for either; it answers "which approach," not "the full technical plan" or "what are we building and why."
This is also why this skill's own output is never an ADR: an ADR (documentation-and-adrs/architecture-decision-records) records a decision already made, after the fact; this file is the forward-looking selection the implementation starts from.
Worked Examples and Domain Playbooks
Calibration material lives in two reference files, not inline here — references/architecture-worked-examples.md (how much architecture a project like this actually needs, by scale/team/timeline) and references/architecture-domain-playbooks.md (current web-researched practice for recurring domains: offline-first sync, multi-tenancy, real-time collaboration, background jobs, search, and more added over time as new domains come up). Both exist to be checked, not memorized — specific tools and figures in either age, and should be re-verified rather than assumed.
Common Rationalizations
Rationalization
Reality
"I know the right pattern for this, I don't need to ask about scale/team/timeline first"
The same feature gets a different right answer at 100 users vs. 100K, solo vs. 10 engineers. Gather the context before recommending, even when a pattern seems obvious.
"Microservices/DDD/Event-driven is the modern, correct way to build this"
"Modern" isn't a justification — check it against the three gating questions and the anti-pattern table before recommending it.
"I'll just give one clear recommendation, options are indecisive"
A single unexamined opinion is exactly what this skill replaces — give the real candidates with trade-offs, state which one fits best and why, but leave the choice visibly theirs.
"I'll write an ADR here since I'm already discussing the decision"
This skill's output is a forward-looking selection file, not an ADR — the actual ADR (template, status, storage) belongs to documentation-and-adrs/architecture-decision-records, written later once the decision has shipped. Don't invent a second ADR format or an in-repo storage path here.
"I'll explain Clean/Hexagonal/DDD in depth here since the user asked about architecture"
That depth already lives in architecture-patterns — name the pattern and hand off, don't re-teach it inline.
"The worked examples / domain playbook list specific tools, I'll just use those without checking"
Both reference files are calibration and a research starting point, not a frozen stack recommendation — re-check any named library against references/library-reuse.md, and re-run the web search for anything domain-specific and date-sensitive.
"This pattern is the modern, more sophisticated choice, I'll recommend it"
The Core Principle is simplest-effective-wins by default — "modern" or "sophisticated" isn't a justification on its own; it still has to clear the gating questions and anti-pattern check.
"I already know the obvious answer here, I'll skip straight to it"
The obvious answer might be right, but that's exactly what has to be checked, not assumed — run the decision trees and web research anyway; confirming the obvious choice after the comparison is a different (and more trustworthy) thing than never comparing at all.
"Picking the simplest option means I don't need to run the comparison"
Simplest-wins is the tie-breaker after real candidates exist, not a shortcut around producing them — a simple answer reached without comparison is still just an assumption, even when it happens to be correct.
"I'll hand the write-up off to spec-driven-development since it already writes specs"
Not for this skill's output — it writes its own selection file directly, the same way deep-dive owns its own spec file rather than handing that off. spec-driven-development is for the PRD stage before this skill runs, or the later stage where the chosen approach becomes a full technical plan.
Red Flags
A pattern recommended before scale/team/timeline/domain/constraints were gathered or already known
A single option presented as the answer, with no trade-off table and no simpler alternative considered
A heavyweight pattern (microservices, full DDD, CRDTs, event sourcing) recommended as the default without clearing the gating questions and anti-pattern check first
An ADR invented here instead of leaving that to documentation-and-adrs/architecture-decision-records for later
Clean/Hexagonal/DDD internals, database schema specifics, or REST/GraphQL contract design re-explained here instead of pointing to the skill that owns that depth
A worked example's or domain playbook's named tool treated as a current recommendation without re-checking it
The selection write-up handed off to another skill instead of being written directly as this skill's own output
The web-research step skipped for a feature with real, well-known domain-specific prior art (offline-first, real-time collaboration, multi-tenancy, and similar)
A recommendation reached by going straight to the "obvious" or familiar approach, with the decision trees/web research skipped because the answer already felt settled
Simplicity used as an excuse to skip the comparison steps, rather than as the tie-breaker applied once real candidates actually exist
Verification
Scale, team, timeline, domain, and constraints were gathered (via AskUserQuestion, in batched rounds, or read from existing context) before any pattern was suggested
For a feature with real domain-specific prior art, references/architecture-domain-playbooks.md was checked and a fresh WebSearch confirmed or refreshed it
Each independent concern (data access, business rules, scaling, real-time, and any domain-specific one) was decided separately, not forced to a single overall pattern
Every recommended pattern passed the three gating questions and the anti-pattern check in references/architecture-decision-trees.md, with simplest-effective winning by default
Candidates were presented as a trade-off table (pros/cons/complexity/when-valid), not a single stated verdict
Deeper specifics (pattern internals, schema, API contract, named library) were handed off to the skill that owns them, not re-derived here
This skill wrote its own two-part output (dense prompt + structured selection file) directly, saved to approach-selections/<feature-slug>.md, rather than handing the write-up off elsewhere
Any newly-researched domain not yet in references/architecture-domain-playbooks.md was added there in the same shape
See Also
references/architecture-decision-trees.md — the four concern-specific decision trees, gating questions, and anti-pattern table
references/architecture-worked-examples.md — calibration examples by scale/team/timeline
references/architecture-domain-playbooks.md — web-researched current practice for recurring domains (offline-first, multi-tenancy, real-time collaboration, and more as they're added)
documentation-and-adrs / architecture-decision-records — where the chosen approach gets recorded as a historical ADR, later
architecture-patterns — Clean/Hexagonal/DDD depth once one of those is the chosen shape
database-design / database-architect, api-patterns / api-and-interface-design — the next layer of depth for data and API shape decisions
references/library-reuse.md — the specific library to name once an ecosystem and category are known
breakdown-feature-implementation — turns a chosen approach into a full technical plan
deep-dive — the output format this skill's Step 7 is modeled on
brainstorming — one level up, for validating whether the underlying idea is worth building at all
1---2name: architecture-approach-selection3description: Given a feature/project's context (scale, team, timeline, domain, constraints — via batched AskUserQuestion rounds), surfaces candidate architectural approaches, defaulting to the simplest option that works, grounded in internal decision trees plus current web-researched practice for the specific domain (offline-first sync, search, background jobs, multi-tenancy, real-time collaboration, and others as they come up) — then writes its own deep-dive-style selection document. Use when asked "what methods/approaches can I use for this", "what's the right architecture/stack for this", or before committing to a pattern (monolith vs. microservices, sync vs. event-driven, Repository vs. direct ORM, REST vs. GraphQL, how much DDD). NOT for the PRD (`breakdown-feature-prd`), validating a vague idea (`brainstorming`), a full implementation plan (`breakdown-feature-implementation`), or the ADR (`documentation-and-adrs`) — this picks the approach; those build it out or record it later.4metadata:5 source: https://skillmd.com/skills/ghosteken/architecture-approach-selection6---78# Architecture Approach Selection910> Curated from a community-sourced "architecture" skill (context discovery, pattern-selection decision trees, trade-off analysis) found archived and unexposed in `archive/skills-community/`. Rewritten to stop short of re-teaching what this plugin's other skills already own — ADR templates, Clean/Hexagonal/DDD depth, API/DB pattern depth, named libraries — and to hand off to them instead.1112## Overview1314Before a feature or a project commits to a pattern, someone has to answer "what are my actual options here, and which one fits *this* context" — not "which pattern do I personally reach for by habit." This skill runs that selection pass like a real consult, not a lookup: interrogate the context thoroughly via `AskUserQuestion` until there's genuinely enough to reason from, check this skill's own decision trees for the cross-cutting structural concerns, *and* search the web for how the exact domain at hand (offline-first sync, search, background job processing, real-time collaboration, multi-tenant isolation, and anything else with real established prior art — these are examples, not the full list) is actually being solved right now — then come back with 1-3 real candidates per concern, each with pros/cons/complexity and the condition under which it stops being the right call, written up as a saved document. Not a single prescribed answer presented as the only option, and not a lookup table answer when the domain has moved past what a static table captures.1516This applies the same way whether the input is **a single feature** ("what approach should I use for notifications/search/a workflow engine") or **a whole new project** ("what should the architecture/stack look like for this app") — the context-gathering and decision trees below don't change shape, only the scope of what's being decided.1718## Why This Skill Exists: Counteract Anchoring, Not Just Complexity1920Left alone, both humans and agents tend to reach for whatever approach occurs to them first — the familiar one, the one just used last time — and build on it without ever actually comparing it to the alternatives. That's the gap this skill closes: it forces the comparison to actually happen (the decision trees, the web research, the candidate table) before any approach gets picked, including the one that felt obvious going in.2122This cuts both ways, and neither direction is the "safe" one to assume without checking:2324- **The obvious approach is sometimes genuinely correct** — plain CRUD often *is* best served by a plain CRUD implementation, and this skill isn't here to manufacture complexity where none is warranted (see the Core Principle below). When the comparison confirms the obvious choice, that's a legitimate outcome.25- **The obvious approach is sometimes wrong, or incomplete** — the first idea that comes to mind is often just the most *familiar* one, not the one that actually fits this project's scale/team/timeline, or the one current domain practice has moved toward. Skipping the comparison because an answer already "feels right" is exactly the failure mode this skill exists to prevent.2627The test is never "which one do I already believe is right" — it's "did I actually run the comparison before answering." An obvious answer that's survived Steps 2-5 is a validated recommendation; an obvious answer that skipped them is just an assumption wearing this skill's output format.2829## Core Principle: Default to the Simplest Effective Option3031Once the comparison above has actually happened, this is the tie-breaker: at every step below — the decision trees, the web research, the final candidate table — **the simplest option that actually solves the stated problem wins, unless a specific, confirmed requirement rules it out.** Microservices, full DDD, CRDTs, event sourcing, and similar heavyweight patterns are never the default recommendation; they're the exception, reached for only when the gating questions and anti-pattern checks below are all cleared. "More sophisticated" and "more correct" are not the same claim — don't let a pattern's reputation stand in for it actually being justified by *this* context's gathered facts. This principle is not license to skip straight to an answer, obvious or otherwise, without running the steps that justify it — see above.3233## When to Use3435- Asked "what methods/approaches can I use for this" about a specific feature or an entire project36- Choosing between architectural shapes before writing code: monolith vs. modular monolith vs. microservices, synchronous vs. event-driven, Repository/Unit-of-Work vs. direct ORM access, how much (if any) DDD, REST vs. GraphQL vs. gRPC at the top level37- Starting a new project or a feature that implies a whole domain (notifications, multi-tenancy, payments, search, a workflow engine) and no approach has been chosen yet38- A chosen pattern is being second-guessed ("is microservices actually justified here?") and needs re-examining against the project's real scale/team/timeline, not just defended by habit3940**When NOT to use:**4142- Requirements aren't written down yet at all — use `spec-driven-development` or `breakdown-feature-prd` first; this skill needs something concrete to evaluate against, even if it's just "a feature idea plus a few answered questions," not nothing43- The approach is already chosen and the task is building it out — use `breakdown-feature-implementation` (full plan) or `incremental-implementation` (build it)44- The ask is really "is this idea worth building at all" — that's `brainstorming`, one level up from this skill45- Writing up the decision once it's made — `documentation-and-adrs` (and `architecture-decision-records` for the ADR mechanics) own that, using this skill's output as their Alternatives Considered4647## Process4849### Step 1: Gather Context First — Thoroughly, in Batched Rounds5051Don't suggest an architecture before knowing what it's for, and don't settle for a thin first pass either — the whole point of this skill is reasoning from real context, not from a generic template. Ask via `AskUserQuestion` in batched rounds (several related questions per round, not one question per round) and keep going across more than one round when the use case has real sub-decisions worth asking about — the same scaling discipline `deep-dive` uses: more rounds for a use case that implies several independent sub-decisions (an offline-first app raises sync strategy, conflict resolution, and connectivity-detection as three separate things worth asking about), one tight round for something genuinely simple. Stop once the axes below are actually answered, not after an arbitrary number of rounds — padding with questions that don't change the recommendation is as much a failure as not asking enough.5253| Axis | What to find out |54|---|---|55| **Scale** | Users (10 / 1K / 100K / 1M+), data volume, transaction rate |56| **Team** | Solo or team, size, expertise, co-located or distributed |57| **Timeline** | MVP/prototype vs. long-term product, time-to-market pressure |58| **Domain** | CRUD-heavy or genuinely complex business logic, real-time needs, compliance/regulatory load |59| **Constraints** | Budget, legacy systems to integrate with, an existing stack this has to fit into |6061Classify the result against this rough matrix — it's a calibration aid, not a rule, and real projects sit between columns:6263```64 MVP SaaS Enterprise65┌──────────────────────────────────────────────────────────────┐66│ Scale │ <1K │ 1K-100K │ 100K+ │67│ Team │ Solo │ 2-10 │ 10+ │68│ Timeline │ Fast (weeks) │ Medium (months)│ Long (years) │69│ Architecture │ Simple │ Modular │ Distributed │70│ Patterns │ Minimal │ Selective │ Comprehensive│71└──────────────────────────────────────────────────────────────┘72```7374If an existing codebase already answers some of these (an existing stack, an existing team size visible from the repo/org), read that first and only ask about what's left — don't make the user restate what's already observable.7576### Step 2: Search the Web for Current Best Practice in the Specific Domain7778The decision trees in Step 3 cover cross-cutting structural concerns (data access, business rules, scaling, real-time) that don't change much year to year. They do **not** cover domain-specific prior art — how offline-first sync is actually being built right now, what a real-time collaboration engine looks like today, how search relevance or multi-tenant isolation is typically solved — and that's exactly the part a static internal table goes stale on fastest.7980Once the feature/domain is known from Step 1, identify whether it's the kind of problem with real, named, current prior art (offline-first, real-time collaboration/CRDTs, search, recommendation, payments compliance, multi-tenancy isolation models, and similar well-trodden domains usually are; a plain CRUD feature usually isn't). If so:8182- Check `references/architecture-domain-playbooks.md` first — it's seeded from real web research for a handful of common domains, each dated. If it already covers this domain and the "last checked" date is recent, it's a usable starting point.83- Either way, run a fresh `WebSearch` (start with `mode: "standard"`; go to `"extended"` if the first pass comes back thin, generic, or possibly outdated) to confirm or refresh it — this is a fast-moving area, and the reference file is a starting point, never a substitute for checking. Find how this specific problem is being approached currently: named strategies, named tools/libraries/services genuinely in current use for it, and the trade-offs people actually report between them.84- Ground every option this surfaces in what the search actually returned — cite what was found, don't present a plausible-sounding approach as current practice without having checked. If search comes back thin or inconclusive, say so plainly rather than filling the gap with an invented-sounding answer.85- If this uncovers a domain not yet in the playbook reference, add it there in the same shape (see that file's own "Adding a New Playbook Entry" section) so the next feature in the same domain starts from something instead of zero.86- Fold the result into the candidate table (Step 5 below) as its own set of options alongside whatever the decision trees in Step 3 produced — domain-specific and structural concerns both show up there, not as two disconnected outputs.87- Skip this step outright for a feature with no real domain-specific prior art to speak of (a plain internal CRUD screen, for instance) — it isn't needed everywhere, only where the "best practice" actually depends on current, fast-moving domain knowledge the internal decision trees were never meant to capture.8889### Step 3: Run the Decision Trees Per Concern9091Work through `references/architecture-decision-trees.md`'s four concern-specific trees (data access complexity, business rules complexity, independent scaling, real-time requirements) for whatever this feature/project actually touches — treat each concern independently, since a project can land on "Repository pattern" for data access and "simple REST" for its API in the same breath. That reference also holds the three gating questions every pattern must clear before it's recommended (what problem does it solve here, is there a simpler alternative, can it be deferred) — this is the mechanical form of the Core Principle above, apply it every time, not just when a pattern feels obviously heavy.9293### Step 4: Check Against Known Anti-Patterns9495Check whatever Step 3 recommended against the anti-pattern table in `references/architecture-decision-trees.md`. If a recommendation shows up there without its stated condition actually being true for this project, that's the signal to downgrade to the simpler alternative in the same row — not to justify the complex one after the fact.9697### Step 5: Present Candidates With Trade-offs, Not One Verdict9899For each real decision point, give the options as a table, not a single recommendation stated as fact:100101```markdown102| Option | Pros | Cons | Complexity | When this is the right call |103|---|---|---|---|---|104| [Option A] | ... | ... | Low | [the condition under which A fits] |105| [Option B] | ... | ... | High | [the condition under which B fits] |106```107108State which option fits *this* project's Step 1 answers and why — but as a recommendation the user can push back on, not a decision already made on their behalf. This table is the raw material for Step 7's document (and, later, for an ADR's Alternatives Considered) — it is not itself an ADR, and it doesn't get written up as one here.109110### Step 6: Hand Off the Depth to the Skill That Owns It111112This skill's job stops at "here's the shape and why" — the next layer of depth for whichever shape gets picked belongs elsewhere:113114| Once you've picked... | Go deeper with |115|---|---|116| Repository/DDD/Clean/Hexagonal internals | `architecture-patterns` |117| The actual database schema, indexing, ORM choice | `database-design` (or `database-architect`) |118| REST vs. GraphQL vs. gRPC specifics, endpoint/contract design | `api-patterns` / `api-and-interface-design` |119| A specific named library within the chosen category | `references/library-reuse.md` |120| Turning the chosen approach into a full technical plan | `breakdown-feature-implementation` |121| Recording the decision as a historical ADR once it ships | `documentation-and-adrs` / `architecture-decision-records` |122123Re-deriving any of these inline instead of handing off is exactly the duplication this plugin's own contributing rules forbid — point there, don't restate it. Writing up the selection itself is the one exception: this skill owns that output directly (Step 7 below), the same way `deep-dive` owns its own spec file rather than handing that off.124125### Step 7: Produce the Two Outputs126127Modeled directly on how `deep-dive` closes out its own interrogation — two outputs, not a hand-off to another skill:128129**Output A — the Desired Approach, in prose.** 2-3 paragraphs that state the recommended direction for every concern decided above (data access, business rules, scaling, real-time, and any domain-specific practice from Step 2) as one dense instruction — specific enough to hand straight to `breakdown-feature-implementation` or `incremental-implementation` without either of them having to re-derive the reasoning.130131**Output B — the detailed selection file:**132133```markdown134# Architecture Approach: [Feature/Project Name]135136## Context137[Scale/Team/Timeline/Domain/Constraints from Step 1, stated plainly — this is what every decision below is actually grounded in.]138139## [Concern Name] — e.g. Data Access, Business Rules, Scaling, Real-time, or a domain-specific concern from Step 2140**Candidates considered:**141| Option | Pros | Cons | Complexity | When this is the right call |142|---|---|---|---|---|143| ... | ... | ... | ... | ... |144145**Decision:** [the recommended option]146**Rationale:** [why, tied to Step 1's actual answers — not a generic justification]147**Gating questions passed:** [problem solved / simpler alternative checked / deferrable checked — per references/architecture-decision-trees.md]148**Anti-pattern check:** [confirmed clear of references/architecture-decision-trees.md's anti-pattern table, or noted if a condition isn't fully met]149150... one section per concern actually decided ...151152## Out of Scope153- [What this selection explicitly doesn't decide, and why — e.g. "specific database indexing strategy: see database-design"]154155## Open Questions156- [Any concern where more than one candidate is still genuinely live, left for the user to break the tie on, rather than silently picked here]157```158159Save to `approach-selections/<feature-slug>.md` under the project's external output location (see `references/external-output-paths.md`) — outside the project's own repo, never a path git in this project tracks or ignores. Create the directory if it doesn't exist. If a file for this feature already exists, ask whether to update it in place or start a new one (`<feature-slug>-2.md`). This is a distinct subpath from `specs/` — this skill's output is upstream of `spec-driven-development` and `breakdown-feature-implementation`, not a replacement for either; it answers "which approach," not "the full technical plan" or "what are we building and why."160161This is also why this skill's own output is never an ADR: an ADR (`documentation-and-adrs`/`architecture-decision-records`) records a decision already made, after the fact; this file is the forward-looking selection the implementation starts from.162163## Worked Examples and Domain Playbooks164165Calibration material lives in two reference files, not inline here — `references/architecture-worked-examples.md` (how much architecture a project like this actually needs, by scale/team/timeline) and `references/architecture-domain-playbooks.md` (current web-researched practice for recurring domains: offline-first sync, multi-tenancy, real-time collaboration, background jobs, search, and more added over time as new domains come up). Both exist to be checked, not memorized — specific tools and figures in either age, and should be re-verified rather than assumed.166167## Common Rationalizations168169| Rationalization | Reality |170|---|---|171| "I know the right pattern for this, I don't need to ask about scale/team/timeline first" | The same feature gets a different right answer at 100 users vs. 100K, solo vs. 10 engineers. Gather the context before recommending, even when a pattern seems obvious. |172| "Microservices/DDD/Event-driven is the modern, correct way to build this" | "Modern" isn't a justification — check it against the three gating questions and the anti-pattern table before recommending it. |173| "I'll just give one clear recommendation, options are indecisive" | A single unexamined opinion is exactly what this skill replaces — give the real candidates with trade-offs, state which one fits best and why, but leave the choice visibly theirs. |174| "I'll write an ADR here since I'm already discussing the decision" | This skill's output is a forward-looking selection file, not an ADR — the actual ADR (template, status, storage) belongs to `documentation-and-adrs`/`architecture-decision-records`, written later once the decision has shipped. Don't invent a second ADR format or an in-repo storage path here. |175| "I'll explain Clean/Hexagonal/DDD in depth here since the user asked about architecture" | That depth already lives in `architecture-patterns` — name the pattern and hand off, don't re-teach it inline. |176| "The worked examples / domain playbook list specific tools, I'll just use those without checking" | Both reference files are calibration and a research starting point, not a frozen stack recommendation — re-check any named library against `references/library-reuse.md`, and re-run the web search for anything domain-specific and date-sensitive. |177| "This pattern is the modern, more sophisticated choice, I'll recommend it" | The Core Principle is simplest-effective-wins by default — "modern" or "sophisticated" isn't a justification on its own; it still has to clear the gating questions and anti-pattern check. |178| "I already know the obvious answer here, I'll skip straight to it" | The obvious answer might be right, but that's exactly what has to be checked, not assumed — run the decision trees and web research anyway; confirming the obvious choice after the comparison is a different (and more trustworthy) thing than never comparing at all. |179| "Picking the simplest option means I don't need to run the comparison" | Simplest-wins is the tie-breaker *after* real candidates exist, not a shortcut around producing them — a simple answer reached without comparison is still just an assumption, even when it happens to be correct. |180| "I'll hand the write-up off to spec-driven-development since it already writes specs" | Not for this skill's output — it writes its own selection file directly, the same way `deep-dive` owns its own spec file rather than handing that off. `spec-driven-development` is for the PRD stage before this skill runs, or the later stage where the chosen approach becomes a full technical plan. |181182## Red Flags183184- A pattern recommended before scale/team/timeline/domain/constraints were gathered or already known185- A single option presented as the answer, with no trade-off table and no simpler alternative considered186- A heavyweight pattern (microservices, full DDD, CRDTs, event sourcing) recommended as the default without clearing the gating questions and anti-pattern check first187- An ADR invented here instead of leaving that to `documentation-and-adrs`/`architecture-decision-records` for later188- Clean/Hexagonal/DDD internals, database schema specifics, or REST/GraphQL contract design re-explained here instead of pointing to the skill that owns that depth189- A worked example's or domain playbook's named tool treated as a current recommendation without re-checking it190- The selection write-up handed off to another skill instead of being written directly as this skill's own output191- The web-research step skipped for a feature with real, well-known domain-specific prior art (offline-first, real-time collaboration, multi-tenancy, and similar)192- A recommendation reached by going straight to the "obvious" or familiar approach, with the decision trees/web research skipped because the answer already felt settled193- Simplicity used as an excuse to skip the comparison steps, rather than as the tie-breaker applied once real candidates actually exist194195## Verification196197- [ ] Scale, team, timeline, domain, and constraints were gathered (via `AskUserQuestion`, in batched rounds, or read from existing context) before any pattern was suggested198- [ ] For a feature with real domain-specific prior art, `references/architecture-domain-playbooks.md` was checked and a fresh `WebSearch` confirmed or refreshed it199- [ ] Each independent concern (data access, business rules, scaling, real-time, and any domain-specific one) was decided separately, not forced to a single overall pattern200- [ ] Every recommended pattern passed the three gating questions and the anti-pattern check in `references/architecture-decision-trees.md`, with simplest-effective winning by default201- [ ] Candidates were presented as a trade-off table (pros/cons/complexity/when-valid), not a single stated verdict202- [ ] Deeper specifics (pattern internals, schema, API contract, named library) were handed off to the skill that owns them, not re-derived here203- [ ] This skill wrote its own two-part output (dense prompt + structured selection file) directly, saved to `approach-selections/<feature-slug>.md`, rather than handing the write-up off elsewhere204- [ ] Any newly-researched domain not yet in `references/architecture-domain-playbooks.md` was added there in the same shape205206## See Also207208- `references/architecture-decision-trees.md` — the four concern-specific decision trees, gating questions, and anti-pattern table209- `references/architecture-worked-examples.md` — calibration examples by scale/team/timeline210- `references/architecture-domain-playbooks.md` — web-researched current practice for recurring domains (offline-first, multi-tenancy, real-time collaboration, and more as they're added)211- `documentation-and-adrs` / `architecture-decision-records` — where the chosen approach gets recorded as a historical ADR, later212- `architecture-patterns` — Clean/Hexagonal/DDD depth once one of those is the chosen shape213- `database-design` / `database-architect`, `api-patterns` / `api-and-interface-design` — the next layer of depth for data and API shape decisions214- `references/library-reuse.md` — the specific library to name once an ecosystem and category are known215- `breakdown-feature-implementation` — turns a chosen approach into a full technical plan216- `deep-dive` — the output format this skill's Step 7 is modeled on217- `brainstorming` — one level up, for validating whether the underlying idea is worth building at all
Run npx get-skill add ghosteken/architecture-approach-selection in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.
Given a feature/project's context (scale, team, timeline, domain, constraints — via batched AskUserQuestion rounds), surfaces candidate architectural approaches, defaulting to the simplest option that works, grounded in internal decision trees plus current web-researched practice for the specific domain (offline-first sync, search, background jobs, multi-tenancy, real-time collaboration, and others as they come up) — then writes its own deep-dive-style selection document. Use when asked "what methods/approaches can I use for this", "what's the right architecture/stack for this", or before committing to a pattern (monolith vs. microservices, sync vs. event-driven, Repository vs. direct ORM, REST vs. GraphQL, how much DDD). NOT for the PRD (`breakdown-feature-prd`), validating a vague idea (`brainstorming`), a full implementation plan (`breakdown-feature-implementation`), or the ADR (`documentation-and-adrs`) — this picks the approach; those build it out or record it later. It is listed under Product & Planning on SkillMD.
This skill has not completed SkillMD's automated safety review yet. Independent scanners report: SkillSpector: PASS, Skill Scanner: PASS. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.
This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.
Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.
Ghosteken (@ghosteken) published this skill. Their other Agent Skills are listed on their SkillMD profile.