{
  "uid": "cogitave.learn.use-the-decision-guides.how-decision-guides-work",
  "kind": "moduleUnit",
  "href": "/modules/use-the-decision-guides/how-decision-guides-work/",
  "title": "How decision guides work",
  "summary": "",
  "type": null,
  "products": [],
  "roles": [],
  "levels": [],
  "subjects": [],
  "headings": [
    "The three layers",
    "The shape every guide follows",
    "Why "the default needs nothing recorded""
  ],
  "source": "[ADR-0021](../../../../standards/docs/decisions/0021-technology-selection-guidance.md)\nrecords why these guides exist and where they sit. Before this ADR, nothing\nmapped a *workload* to a *store* or a *compute runtime* - each team re-derived\nthe mapping, the answers drifted, and, in an MCP-native estate, an agent could\nnot answer \"recommend a store for workload W\" because the mapping was not\nwritten down as data anywhere. The ADR closes that gap with a **three-layer\nguidance model**.\n\n## The three layers\n\n| Layer | Question | Artifact |\n| --- | --- | --- |\n| **Selection** | *which* family for *which* workload/task | database-selection, infrastructure-selection, model-selection |\n| **Radar** (rings) | *what* is adopted at each layer | [technology-radar](../../../../standards/docs/standards/technology-radar.md) |\n| **Domain** (how-to) | *how* to build with the choice | [naming](../../../../standards/docs/standards/naming.md), [reliability](../../../../standards/docs/standards/reliability.md), [saas](../../../../standards/docs/standards/saas.md), and the rest |\n\nThe selection guides **consume** the radar's ring for each option - they never\nre-rank it - and **defer** every build-time detail to the domain standards.\nModel selection is explicitly the \"third sibling\" alongside database and\ninfrastructure selection, governed by the same ADR.\n\n## The shape every guide follows\n\nRead any of the three guides and you will find the same four pieces, in this\norder:\n\n1. **A stated default.** Database selection defaults to **Postgres** (or\n   Cogitave Core's query layer for full-text, vector, and graph workloads).\n   Infrastructure selection defaults to **containers on managed Kubernetes**\n   for a long-running service. Model selection defaults to the **most capable\n   Claude tier** for any new or correctness-critical task.\n2. **A real, walkable decision tree.** Each guide gives an ordered flow -\n   database selection's five-step tree (access pattern, consistency, query\n   shape, scale, cost), infrastructure selection's per-capability flowcharts,\n   and model selection's criteria table (reasoning depth, latency, context,\n   cost, modality, tool-use, structured output). Walk the tree in order and\n   stop at the first step that forces a non-default answer.\n3. **A deviation rule.** You may land somewhere other than the default only on\n   a **measured need** - a benchmark or production signal, tied to a\n   [reliability](../../../../standards/docs/standards/reliability.md) SLO or\n   error budget, never a hunch - recorded in an ADR (or, for model selection,\n   an eval showing a cheaper tier holds quality). This is the\n   [technology radar](../../../../standards/docs/standards/technology-radar.md)'s\n   own rule inherited verbatim: *deviate with an ADR and a migration path off\n   the bootstrap.*\n4. **A machine-readable matrix.** Each guide's decision tree is also carried as\n   valid YAML (for example\n   [data/database-selection.yaml](../../../../standards/docs/standards/data/database-selection.yaml)),\n   projected into Cogitave Core as a queryable reference node. A human reads\n   the prose tree; an agent resolves the same answer via `docs_search` /\n   `query_graph` over the identical data - see\n   [Core's MCP interface](../../../../core/docs/mcp-interface.md).\n\n> [!NOTE]\n> Model selection's deviation rule has a second gate the other two do not:\n> moving a task to a **lower** tier always needs eval evidence, and only a\n> Tier-4 (distilled/self-hosted) build additionally needs an ADR plus a\n> [model-training](../../../../standards/docs/standards/model-training.md)\n> project. Escalating **up** for correctness needs no ADR at all - correctness\n> is always allowed to cost more.\n\n## Why \"the default needs nothing recorded\"\n\nChoosing Postgres, a container on k8s, or the most capable tier for a new task\nneeds **no ADR** - it is simply following the guide. Only *leaving* the\ndefault is a decision that must be recorded, because that is the moment\noperational burden, consistency complexity, or cost is traded for something\nthe default does not give you, and a reviewer or an agent needs to see why.\n",
  "partOf": "cogitave.learn.use-the-decision-guides",
  "durationInMinutes": 7,
  "quiz": null
}