Skip to main content

​
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

TypeWhen to use
architectureHigh-level system design choices
approachHow to implement a specific feature
implementationLow-level implementation details
tradeoffDocumented tradeoffs between options
conventionPatterns adopted as team standards (prefer convention_propose for enforcement)
bugfixRoot cause and fix for a notable bug
otherAnything else worth remembering
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:
  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.