> ## 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.

# decide

> Record an architectural decision for the team

## 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](/concepts/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`](/mcp/decisions-stale) and either [`decision_reaffirm`](/mcp/decision-reaffirm) or record a new superseding decision.

For hard gates use [`convention_propose`](/mcp/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

```json theme={null}
{
  "id": "dec_abc123",
  "status": "recorded",
  "title": "Use JWT for authentication",
  "workspace": "my-startup"
}
```

## Examples

### Architecture decision

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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)

<Note>
  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.
</Note>