SecondBrain/_templates/reference.md

---
type: reference
subtype: pattern/framework  # REQUIRED — set to exactly one of: pattern/framework | api-integration | role-definitions | design-rules
title: [Human-readable title]
summary: [1-2 sentences answering "what facts do I need to look up to make a decision / integrate / understand roles?"]
tags:
  - type/reference
  - 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
last_reviewed: YYYY-MM-DD  # REQUIRED if subtype is api-integration (mutable facts: auth, endpoints, schema); otherwise delete this line
related:
  - [note-slug]  # cross-links to companion notes; omit if none
source: [project name]  # project that spawned the note
---

# [Reference Title]

## Purpose
<!-- One or two sentences: what this reference covers and the decision / integration / role-understanding it supports. Do NOT restate the summary; do NOT add background theory. -->

<!-- ============================================================
     CHOOSE YOUR SUB-TYPE — keep ONE block below, delete the other
     three AND this selector. Match the block to the `subtype` set in
     frontmatter. Each block lists its body sections.

       pattern/framework   → Core Principles · Decision Framework · Patterns · Anti-Patterns · Known Limitations
       api-integration     → Setup · Authentication · Schema / Data Model · Operations · Gotchas   (REQUIRES last_reviewed)
       role-definitions    → Roles · Inputs & Outputs · Phases · Boundaries
       design-rules        → Rules / Standards · Examples · Exceptions
     ============================================================ -->

<!-- ===== VARIANT: pattern/framework ===== -->

## Core Principles
<!-- The 1–3 foundational ideas every pattern below rests on, each as a statement plus why it holds. Lets the reader reason about cases the patterns don't name. -->

## Decision Framework
<!-- When to choose what — a flowchart, decision tree, or table mapping situation → choice. This is the section the reader scans first to pick an approach. -->

## Patterns
<!-- Named patterns, each with: when to use it, why it works, and (optional) a short example. One sub-heading per pattern. -->

### [Pattern name]
<!-- When → why → optional short example. -->

## Anti-Patterns
<!-- What to avoid, each with the tell that flags it and the fix. Not the principles restated. -->

- **[Anti-pattern / smell]** → [why it is wrong, or what to do instead]

## Known Limitations
<!-- Boundary / version-sensitive caveats: where the framework stops applying or depends on a tool's current behavior. Omit only if genuinely none. -->

<!-- ===== VARIANT: api-integration ===== -->
<!-- REQUIRES `last_reviewed` in frontmatter — these are mutable facts that drift. -->

## Setup
<!-- Prerequisites and connection steps to get the integration working: accounts, base URLs, SDK/version, env vars. Enough to go from zero to a first call. -->

## Authentication
<!-- Auth method (key / OAuth / token), where credentials live, and how tokens are obtained/refreshed. The reader configures auth from this alone. -->

## Schema / Data Model
<!-- The entities, key fields, and types the integration exposes. What the reader maps their data to. Tables work well here. -->

## Operations
<!-- The common operations / endpoints with their purpose and minimal usage shape (params in, result out). The reader picks the right call from this. -->

## Gotchas
<!-- Rate limits, quirks, breaking-change history, and version-sensitive behavior. The reader avoids the pitfall before hitting it. Omit only if genuinely none. -->

<!-- ===== VARIANT: role-definitions ===== -->

## Roles
<!-- Each role/agent and its one-line responsibility. One sub-heading or list item per role. The reader assigns work from this. -->

- **[Role]** — [responsibility in one line]

## Inputs & Outputs
<!-- What each role consumes and produces, so handoffs wire up correctly. A table (role · input · output) works well. -->

## Phases
<!-- The ordered phases/sequence and which role acts in each. The reader sequences the workflow from this. -->

## Boundaries
<!-- What each role does NOT do — the edges that prevent overlap or overreach. Omit only if genuinely none. -->

<!-- ===== VARIANT: design-rules ===== -->
<!-- This is LOOKUP material (established standards/values), not behavioral rules-with-rationale — that is the `convention` type. Keep entries as facts to conform to, not principles to internalize. -->

## Rules / Standards
<!-- The established standards as directives or values to conform to (e.g., the spacing scale, the naming format, the allowed set). The reader checks their work against these. -->

- **[Rule / standard]** — [the value or directive]

## Examples
<!-- Concrete correct applications of the standards — what conformance looks like. The reader mirrors these. -->

## Exceptions
<!-- Where the standards do not apply or apply differently. Omit only if genuinely none. -->

## Related
<!-- Wikilinks to companion notes, one line each on why it is relevant. Keep this section in whichever variant you choose. -->

- [[note-slug]] — why it is relevant