111 lines
5.2 KiB
Markdown
111 lines
5.2 KiB
Markdown
---
|
||
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
|