> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enagrams.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Decisions

> Shared architectural choices that keep agents aligned — and stay honest as the code changes

## What Is a Decision?

A decision is a structured record of an architectural choice: what was decided, why, and which files or symbols it affects. Decisions are how Enagrams keeps agents (and humans) aligned on the same architectural approach across sessions, branches, and weeks.

Decisions are related to but distinct from [conventions](/concepts/conventions):

* A **decision** is a one-time choice ("We picked JWT over sessions").
* A **convention** is an ongoing rule ("All API routes must return `{ ok, data, error }`"). `must`-tier conventions can block writes.

## Recording a Decision

Use the [`decide`](/mcp/decide) MCP tool:

```json theme={null}
{
  "tool": "decide",
  "arguments": {
    "title": "Use JWT for authentication",
    "rationale": "Stateless tokens work with our edge deployment on Vercel. No session store needed.",
    "files": "src/auth/login.ts,src/auth/middleware.ts",
    "decision_type": "architecture"
  }
}
```

The API parses the comma-separated `files`, resolves them against the [symbol graph](/concepts/symbol-graph) when possible, embeds the decision text for semantic search, and records the `symbol_graph_version` seen at the time. That version is what makes the decision "live" — see [staleness](#living-decisions-staleness) below.

Decisions can also be extracted automatically from meeting transcripts and coding traces.

## Decision Types

| Type             | When to use                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `architecture`   | High-level system design choices                                                                            |
| `approach`       | How to implement a specific feature                                                                         |
| `implementation` | Low-level implementation details                                                                            |
| `tradeoff`       | Documented tradeoffs between options                                                                        |
| `convention`     | Patterns adopted as team standards (prefer [`convention_propose`](/mcp/convention-propose) for enforcement) |
| `bugfix`         | Root cause and fix for a notable bug                                                                        |
| `other`          | Anything else worth remembering                                                                             |

## Semantic Search

Every decision is embedded with `text-embedding-3-small` (1536 dimensions) and stored in pgvector:

```json theme={null}
{
  "tool": "search",
  "arguments": { "query": "authentication approach", "limit": 10 }
}
```

Asking "how do we handle auth?" returns JWT-related decisions even if the original title used different words.

## Decisions in `sync`

The [`sync`](/mcp/sync) response always includes the most relevant recent decisions for the agent's current files, plus any flagged stale:

```json theme={null}
{
  "decisions": [
    {
      "id": "dec_abc",
      "title": "Use JWT for authentication",
      "rationale": "Stateless, works with edge deployment",
      "decision_type": "architecture",
      "made_by": "Developer A",
      "created_at": "2026-04-13T10:00:00Z",
      "files": ["src/auth/login.ts"],
      "is_stale": false
    }
  ],
  "stale_decisions": []
}
```

Agents use this context to avoid contradicting existing decisions.

## Living Decisions: Staleness

Decisions don't just sit in a ledger. When the code they describe changes, they get flagged.

```
decide() records decision dec_abc  → linked to validateToken symbol
  ↓
validateToken is later rewritten (detected via symbol_graph diff)
  ↓
dec_abc is marked stale
  ↓
decisions_stale() lists it
sync() surfaces it in stale_decisions for affected agents
```

Two tools resolve staleness:

* [`decision_reaffirm`](/mcp/decision-reaffirm) — "still applies, fresh again"
* [`decide`](/mcp/decide) with `supersedes: <id>` — records a new decision that replaces the old one

This keeps the ledger honest. A team of five agents can't drift apart on "what's our auth approach?" because the moment the code moves, the decision surfaces for review.

## Automatic Extraction

Decisions are also extracted automatically from:

1. **Meeting transcripts** — LLM identifies decisions in conversation text.
2. **Coding traces** — `POST /traces/push` can trigger extraction from significant diffs.

## Knowledge Graph

The dashboard visualizes decisions as a force-directed graph:

* **Nodes** — decisions, files, symbols, architectural areas.
* **Edges** — shared files/symbols between decisions.

Regions with many interconnected decisions signal hot zones of the codebase — and regions with many stale decisions signal architectural drift that needs attention.