Decisions

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:

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

{
  "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 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 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` 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:

{
  "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 response always includes the most relevant recent decisions for the agent’s current files, plus any flagged stale:

{
  "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 — “still applies, fresh again”
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:

Meeting transcripts — LLM identifies decisions in conversation text.
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.

Getting Started

Setup Guides

Concepts

What Is a Decision?

Recording a Decision

Decision Types

Semantic Search

Decisions in `sync`

Living Decisions: Staleness

Automatic Extraction

Knowledge Graph

​What Is a Decision?

​Recording a Decision

​Decision Types

​Semantic Search

​Decisions in sync

​Living Decisions: Staleness

​Automatic Extraction

​Knowledge Graph

What Is a Decision?

Recording a Decision

Decision Types

Semantic Search

Decisions in `sync`

Living Decisions: Staleness

Automatic Extraction

Knowledge Graph