decide

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.

Overview

Coordination & Context

Workstreams

Test Gate

Negotiation

Tasks

Conventions & Living Decisions

Overview

Parameters

Decision Types

Response

Examples

Architecture decision

Rejected alternative

Convention

When to Call `decide`

​Overview

​Parameters

​Decision Types

​Response

​Examples

​Architecture decision

​Rejected alternative

​Convention

​When to Call decide

Overview

Parameters

Decision Types

Response

Examples

Architecture decision

Rejected alternative

Convention

When to Call `decide`