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
| Parameter | Type | Required | Description |
|---|
title | string | Yes | Short description of the decision |
rationale | string | Yes | Why this decision was made |
files | string | No | Comma-separated file paths affected |
type | string | No | Decision type (see below) |
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 |
convention | Patterns adopted as team standards |
bugfix | Root cause and fix for a notable bug |
other | Everything 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.
