---
type: convention
title: [Human-readable title]
summary: [1-2 sentences answering "When I encounter X, what rule should I follow, and why?"]
tags:
  - type/convention
  - domain/[field]
  - tool/[tool]       # if tool-specific
  - client/[client]   # if client-specific
  - project/[project] # if project-specific
scope: [global|project|client]
last_updated: YYYY-MM-DD
date: YYYY-MM-DD          # creation date — set once, never updated
related:
  - [note-slug]  # cross-links to companion notes; omit if none
source: [project name]  # project that spawned the note
---

# [Convention Name]

## Purpose
<!-- 1–2 sentences: what recurring decision or situation this convention governs and why it matters. Do NOT restate the summary. -->

## Core Principles
<!-- 3–7 principles, each stated as a rule PLUS its rationale ("do X because Y"), not a bare directive. Number them. -->

**1. [Principle stated as a rule].**
[Rationale — why this rule exists and what following it buys you.]

## Patterns
<!-- Concrete ways the principles show up in practice — what to do, with named techniques or short examples. -->

**[Pattern name].** [What to do, concretely.]

## Anti-Patterns
<!-- Concrete things this convention forbids, each with the tell that flags it. What to avoid, not the principles restated. -->

- **[Smell / thing to avoid]** → [why it is wrong, or what to do instead]

## Exceptions
<!-- Known cases where the convention does NOT apply, or applies differently. Omit the section only if there are genuinely none. -->

**[Case].** [Why the convention bends or does not apply here.]