pal-e-docs

Convention Template

template-convention Template

active template
Project

Convention Template

Template for convention notes. Conventions are rules and standards — they state how to name things, structure things, and make decisions. If it has numbered steps, it is an SOP, not a convention. If it states a rule, it is a convention.
Currently 25+ conventions exist with zero template enforcement. This template establishes the required structure so conventions can be audited, compared, and trusted.

Required Sections

Every convention note MUST contain these sections in this order:
  • h2: Convention title — format: Convention: {Descriptive Name} (e.g., Convention: Kanban Over Plans). This is the note's single h2.
  • h3: Rule — the convention stated as a clear, enforceable rule. One or two sentences. No preamble. If you cannot state the rule in two sentences, you are describing a procedure (use template-sop instead).
  • h3: Rationale — why this convention exists. What problem it solves or what principle it serves. Keep it to one paragraph. Link to the feedback memory entry or decision that created it if known.
  • h3: Examples — concrete examples showing correct and incorrect usage. Use a table, code blocks, or before/after pairs. The reader should be able to apply the rule after reading this section alone.
  • h3: Enforcement — how this convention is enforced. One of:
  • h3: Related — links to related conventions, SOPs, and templates. Use code tags for slugs.

Template

Naming Conventions

Field Convention Example
Slug <code>convention-{descriptive-name}</code> <code>convention-kanban-over-plans</code>
Title <code>Convention: {Descriptive Name}</code> <code>Convention: Kanban Over Plans</code>
Note type <code>convention</code> —
Tags <code>convention</code> + topic tag <code>convention, agent</code>
Status <code>active</code> or <code>deprecated</code> —
Project Usually <code>pal-e-agency</code> —

Conventions vs SOPs

The distinction matters. They serve different functions and have different structures.
Aspect Convention SOP
Nature Rule or standard Procedure with steps
Structure Rule + Rationale + Examples Numbered steps + preconditions + outputs
Signal "Always do X" / "Never do Y" "Step 1: ... Step 2: ..."
Template <code>template-convention</code> (this note) <code>template-sop</code> (TODO)
Slug prefix <code>convention-</code> <code>sop-</code>
Enforcement States the rule Describes the procedure that enforces it
If your note has numbered steps, it is an SOP. If it states a rule, it is a convention. If it does both, split it into a convention (the rule) and an SOP (the procedure).

The Enforcement Pyramid

Not all conventions are created equal. Enforcement level determines reliability:
  • Convention only — aspirational. Depends on agents reading and following the rule. Compliance is probabilistic. Audits catch drift.
  • SOP-enforced — procedural. The convention is embedded in a skill or SOP that agents follow. Compliance depends on whether the SOP is invoked.
  • Hook-enforced — deterministic. A hook in settings.json fires on every relevant event. The agent cannot bypass it. This is the gold standard.
A convention without enforcement is a wish. A convention with a hook is a law. The goal is to move important conventions up the pyramid over time: convention → SOP → hook.

Audit Checklist

When auditing convention notes against this template:
  • Does it have a single h2 with the Convention: {Name} format?
  • Does the Rule section state the rule in one or two sentences?
  • Does the Rationale section explain why?
  • Does the Examples section show correct and incorrect usage?
  • Does the Enforcement section name the mechanism (hook, SOP, or convention only)?
  • Does the Related section link to sibling conventions and upstream SOPs?
  • Is the slug convention-{descriptive-name}?
  • Is the note_type convention?
  • Does it have the convention tag?
  • template-sop — sibling template for SOPs
  • note-conventions — master note conventions document
  • enforcement-architecture — the enforcement stack (hooks, MCP, skills, agents)
  • convention-kanban-over-plans — example convention that follows this structure well
  • html-style-guide — HTML authoring rules for all notes