ADR-NNNN — <short imperative title>

• Status: Proposed
• Date: YYYY-MM-DD
• Deciders: P@puncoz
• Approved by: —
• Approved on: —
• Supersedes: —
• Superseded by: —
• Design documents: content/docs/maintain/app-flow/<slug>.mdx (when the UI changes, ADR-0008), content/docs/maintain/prd/<slug>.mdx, content/docs/maintain/architecture/system.mdx, … (the living docs this decision creates or changes — see ADR-0002)

ContextCopy Anchor Link

What problem are we solving? What forces, constraints and facts about the current codebase make this decision necessary now? State only what is true and verifiable.

DecisionCopy Anchor Link

The decision, stated plainly and in the present tense ("We use X", "Y lives in Z"). Include the concrete shape of the change: directories, file names, contracts, commands.

Options consideredCopy Anchor Link

ConsequencesCopy Anchor Link

Positive

• …

Negative / accepted trade-offs

• …

Content invariantsCopy Anchor Link

Which invariants in AGENTS.md §6 this touches, and how it keeps them. If it departs from one, say so explicitly. That departure is part of what the owner approves.

Security considerationsCopy Anchor Link

Mandatory — never omit this section (ADR-0005). For a change with no security surface, "None — this change touches no data, no endpoint and no secret" is a valid answer; an omitted section is indistinguishable from not having thought about it.

Where there is a surface, state: what content or data it handles and its classification, whether anything private can reach a public surface, what authorization applies and where it is enforced, what leaves the system (search provider, host, analytics), and what residual risk is accepted. Link content/docs/maintain/security/<slug>.mdx when the feature warrants its own analysis.

Implementation notesCopy Anchor Link

What actually changes in the repo once this is approved. Keep this list checkable — it is the scope of the implementation that follows the approval.

• …
• Tests — the happy path and the obvious failure paths (ADR-0007). If some part cannot be unit-tested, say which, and say what was verified instead.
• bun run lint, bun run types:check and bunx next build pass.

Docs to update on implementationCopy Anchor Link

Living design documents are snapshots of the system as it stands — edit them in place, never as a log of what changed (ADR-0002). Delete anything in them that is no longer true.

• content/docs/maintain/app-flow/<slug>.mdx — if the UI changed
• content/docs/maintain/prd/<slug>.mdx — requirements + user stories
• content/docs/maintain/erd/system.mdx — if persisted data changed
• content/docs/maintain/architecture/system.mdx · content/docs/maintain/dfd/ · content/docs/maintain/state/ · content/docs/maintain/sequence/ · content/docs/maintain/api/ · content/docs/maintain/rbac/ — whichever the change requires (ADR-0002)
• content/docs/maintain/security/ — secrets.mdx if a secret is introduced; threat-model.mdx if the attack surface changed; <slug>.mdx if the feature warrants its own analysis
• AGENTS.md — <what changes, if the way we work changed>
• README.md — <what changes, if the project overview changed>
• content/docs/maintain/adr/index.mdx — index row + status