# Architecture Approach Selection

> 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.

- Skill: `ghosteken/architecture-approach-selection` (Agent Skill)
- Install (CLI): `npx get-skill add ghosteken/architecture-approach-selection`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ghosteken/architecture-approach-selection/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: Ghosteken (https://skillmd.com/u/ghosteken)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/ghosteken/architecture-approach-selection

---


# Architecture Approach Selection

> 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.

| Axis | What to find out |
|---|---|
| **Scale** | Users (10 / 1K / 100K / 1M+), data volume, transaction rate |
| **Team** | Solo or team, size, expertise, co-located or distributed |
| **Timeline** | MVP/prototype vs. long-term product, time-to-market pressure |
| **Domain** | CRUD-heavy or genuinely complex business logic, real-time needs, compliance/regulatory load |
| **Constraints** | Budget, legacy systems to integrate with, an existing stack this has to fit into |

Classify the result against this rough matrix — it's a calibration aid, not a rule, and real projects sit between columns:

```
                    MVP              SaaS            Enterprise
┌──────────────────────────────────────────────────────────────┐
│ Scale        │ <1K            │ 1K-100K        │ 100K+        │
│ Team         │ Solo           │ 2-10           │ 10+          │
│ Timeline     │ Fast (weeks)   │ Medium (months)│ Long (years) │
│ Architecture │ Simple         │ Modular        │ Distributed  │
│ Patterns     │ Minimal        │ Selective      │ Comprehensive│
└──────────────────────────────────────────────────────────────┘
```

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:

```markdown
| 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 | `documentation-and-adrs` / `architecture-decision-records` |

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

```markdown
# 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

