Process Templates

Decisions and incidents must survive the chat that produced them. Keep these short enough that agents and humans actually read them. See Decision Records.

ADR template

Use for cross-cutting choices agents otherwise re-litigate. One decision per file. Status must be honest.

# ADR-<NNNN>: <Title>

- Status: `<proposed | accepted | superseded by ADR-XXXX | deprecated>`
- Date: `<YYYY-MM-DD>`
- Deciders: `<names>`
- Tags: `<payments | auth | data | …>`

## Context
<Force that requires a decision — constraints, symptoms, scale. 1 short paragraph.>

## Decision
<What we will do. Imperative, specific. Not "we should consider…".>

## Consequences
- Positive: `<…>`
- Negative / accepted cost: `<…>`
- Follow-ups: `<tickets / doc updates / CLAUDE.md pointer>`

## Alternatives considered
| Option | Why rejected |
|---|---|
| `<A>` | `<…>` |
| `<B>` | `<…>` |

## Compliance
- Agents must not propose rejected options without a new ADR
- Pointer added in: `CLAUDE.md` / `ARCHITECTURE.md` — `<yes/no + path>`

Release notes

Use for versions humans and agents can cite. Prefer user-visible truth over commit laundry lists.

# Release <X.Y.Z> — <YYYY-MM-DD>

## Highlights
- `<user-visible change>`
- `<…>`

## Changes
### Added
- `<…>`

### Changed
- `<…>`

### Fixed
- `<…>`

### Removed / deprecated
- `<…>` — migration: `<link or steps>`

## Breaking changes
- `<API / schema / config>` — action required: `<…>`

## Deploy notes
- Migrations: `<none | order / expand-contract>`
- Feature flags: `<defaults>`
- Rollback: `<summary or link to DEPLOYMENT.md>`

## Verification
- Smoke: `<commands / URLs>`
- Known issues: `<…>`

Postmortem

Use after customer impact, data risk, or a serious agent-caused mess. Blameless on people; ruthless on process and agent controls.

# Postmortem — <incident title>

- Date of incident: `<…>` · Duration: `<…>` · Severity: `<…>`
- Authors: `<…>` · Status: `<draft | published>`

## Summary
<What broke, who felt it, in 3–5 sentences.>

## Impact
- Users / revenue / data: `<…>`
- Detected by: `<alert | customer | human review of agent PR>`

## Timeline (UTC)
| Time | Event |
|---|---|
| `<…>` | `<…>` |

## Root cause
<Technical cause. If an agent contributed: which missing gate failed (spec, review, test, deploy).>

## What went well
- `<…>`

## What went poorly
- `<…>`

## Action items
| Action | Owner | Due | Done |
|---|---|---|---|
| `<prevent recurrence>` | `<…>` | `<…>` | [ ] |
| `<detect faster>` | `<…>` | `<…>` | [ ] |
| `<doc / CLAUDE.md / checklist update>` | `<…>` | `<…>` | [ ] |

## Agent-specific controls (if applicable)
- [ ] Spec / blast-radius rule updated
- [ ] Review checklist gap closed
- [ ] Automated gate added: `<test / lint / CI>`

Architecture review notes

Use for a structured review of a proposed design or an existing hotspot. Output decisions, not vibes.

# Architecture review — <system / proposal>

Date: `<…>` · Facilitator: `<…>` · Attendees: `<…>`
Materials: `<ARCHITECTURE.md / ADR drafts / diagrams>`

## Question under review
`<single decision or risk to resolve>`

## Current / proposed design (as understood)
`<5–10 lines or link; correct misunderstandings here>`

## Constraints that bind
- `<latency, compliance, team skill, existing ADRs>`

## Options discussed
| Option | Pros | Cons | Advocate |
|---|---|---|---|
| `<A>` | `<…>` | `<…>` | `<…>` |
| `<B>` | `<…>` | `<…>` | `<…>` |

## Decision
- Chose: `<…>`
- Recorded in: `<ADR-NNNN | DECISIONS.md | deferred>`
- Explicitly rejected: `<…>`

## Risks accepted
- `<risk>` — monitoring / mitigation: `<…>`

## Follow-ups
- [ ] `<doc update>`
- [ ] `<spike / prototype>`
- [ ] `<CLAUDE.md pointer>`

## What agents may / may not do next
- May: `<implement within decision>`
- Must not: `<re-open rejected options, expand scope>`

Related

• Decision Records — when to write ADRs
• What Not to Delegate — human-owned decisions
• Constraints and Validation — keeping designs honest
• Production Debugging — incident workflows
• Templates index