Skip to main content

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.

​
Overview

decide records an architectural decision in the shared workspace knowledge graph. The decision is stored with a semantic embedding (pgvector) for later search, auto-linked to the symbols it touches in the symbol graph, included in future sync responses for all agents, and visualized in the Knowledge Graph on the web dashboard. Because decisions link to symbols, when those symbols later change Enagrams marks the decision stale — surface them with decisions_stale and either decision_reaffirm or record a new superseding decision. For hard gates use convention_propose with tier=must instead — decisions are informational; must-tier conventions block edits until resolved.

​
Parameters

ParameterTypeRequiredDescription
titlestringYesShort description of the decision
rationalestringYesWhy this decision was made
filesstringNoComma-separated file paths affected
typestringNoDecision type (see below)

​
Decision Types

TypeWhen to Use
architectureHigh-level system design choices
approachHow to implement a specific feature
implementationLow-level implementation details
tradeoffDocumented tradeoffs
conventionPatterns adopted as team standards
bugfixRoot cause and fix for a notable bug
otherEverything else

​
Response

{
  "id": "dec_abc123",
  "status": "recorded",
  "title": "Use JWT for authentication",
  "workspace": "my-startup"
}

​
Examples

​
Architecture decision

{
  "tool": "decide",
  "arguments": {
    "title": "Use JWT for authentication",
    "rationale": "Stateless tokens work with our Vercel edge deployment. No session store needed. We use short-lived access tokens (15 min) with refresh tokens.",
    "files": ["src/auth/login.ts", "src/auth/middleware.ts", "src/auth/refresh.ts"],
    "type": "architecture"
  }
}

​
Rejected alternative

{
  "tool": "decide",
  "arguments": {
    "title": "Rejected: cookie-based sessions",
    "rationale": "Would require a session store (Redis) which adds infrastructure complexity. Our edge deployment makes cookie-based sessions harder to coordinate.",
    "type": "rejection"
  }
}

​
Convention

{
  "tool": "decide",
  "arguments": {
    "title": "All API responses use { data, error } envelope",
    "rationale": "Consistent shape makes client-side error handling uniform. Error field is null on success, data is null on error.",
    "files": ["src/middleware/responseWrapper.ts"],
    "type": "convention"
  }
}

​
When to Call decide

  • When choosing a library, framework, or service
  • When deciding on a data model or API shape
  • When rejecting an approach (document it so others don’t revisit it)
  • When a pattern is used enough to become a convention
  • After fixing a non-obvious bug (record the root cause)
Decisions are permanent — they’re a historical record of how the codebase evolved. Don’t worry about over-recording. More decisions mean better context for future agents.