pal-e-docs

SOP Template

template-sop Template

active template
Project

SOP Template

Standard Operating Procedures are step-by-step processes that agents and humans follow to complete recurring tasks. SOPs are "how to do things" (procedures). Conventions are "how to name things" (rules). Do not confuse them.
This template defines the required structure for all note_type: sop notes. Currently 25+ SOPs exist with zero template enforcement. This template enables hook validation via convention-block-first-access.

Required Sections

Every SOP note MUST contain these sections in this order:
  • h2: SOP title — format: SOP: {Descriptive Name} ({Optional Context}). This is the note's top-level heading. Examples: SOP: Board Workflow (Continuous Kanban), SOP: Incident Response, SOP: Secrets Management.
  • h3: Purpose — one paragraph. States when this SOP applies, who uses it (agent, human, or both), and what outcome it produces. An agent reading only this paragraph should know whether this is the right SOP for its current task.
  • h3: Steps — ordered list. Each step is a single actionable instruction. Name exact tools, commands, MCP calls, or UI actions. No ambiguity. An agent should be able to follow these without asking clarifying questions. If a step has sub-steps, use a nested ordered list.
  • h3: Rules — bulleted list of constraints and invariants. These are the "never do X" and "always do Y" guard rails that apply regardless of which step you are on.
  • h3: Related — bulleted list of links to related SOPs, conventions, skills, and templates using inline <code>slug</code> references.

Template

Optional Sections

Some SOPs need additional structure beyond the four required sections. These are permitted between Steps and Rules:
  • h3: Column Semantics / Mapping Tables — when the SOP defines a system with named states (e.g., kanban columns, pipeline stages)
  • h3: DORA Integration — when the SOP directly impacts a DORA metric
  • h3: Recovery — when the procedure has known failure modes with distinct recovery paths
  • h4: Sub-sections under Steps — when a step has enough detail to warrant its own heading (e.g., sop-board-workflow uses h4 headings under Item Lifecycle)
Optional sections must not replace or omit any required section.

Naming Convention

Field Value Notes
Slug <code>sop-{descriptive-name}</code> e.g., <code>sop-board-workflow</code>, <code>sop-incident-response</code>, <code>sop-secrets-management</code>
Note type <code>sop</code> Database column. Required on all SOP notes.
Tags <code>sop</code> (topic tag) Retiring when <code>note_type</code> column is fully adopted. Keep for now during transition.
Status <code>active</code> or <code>deprecated</code> Deprecated SOPs are superseded, not deleted. Reference the replacement in the Related section.
Project The project that owns the procedure Cross-cutting SOPs go to <code>pal-e-agency</code>. Platform SOPs go to <code>pal-e-platform</code>.

Legacy Slugs

Some existing SOPs predate the sop- prefix convention and use descriptive slugs without the prefix (e.g., pr-review-loop, worktree-workflow, agent-workflow). These are grandfathered. New SOPs MUST use the sop- prefix.

Quality Criteria

An SOP is ready when:
  • Agent-executable: an agent can follow the Steps without asking questions. If it needs interpretation, the SOP needs more detail.
  • Tool-specific: steps name exact tools, commands, or MCP calls — not vague actions like "update the config."
  • Constraint-complete: the Rules section captures every "never" and "always" that an agent might violate without explicit instruction.
  • Self-contained: the SOP does not require reading another SOP to execute. It may reference related SOPs for context, but the steps stand alone.
  • Testable: each step has an observable outcome. An auditor can verify whether the step was performed correctly.

Validation Rules

Hook validators should check:
  • Note has note_type: sop
  • Note has an h2 heading matching SOP: *
  • Note has h3 sections: Purpose, Steps, Rules, Related (in order, required)
  • Steps section contains an <ol> (ordered list)
  • Rules section contains a <ul> (unordered list)
  • Related section contains at least one <code> slug reference
  • Status is either active or deprecated
  • template-convention — sibling template for convention notes
  • note-conventions — canonical reference for note types, slugs, tags, and linking
  • sop-board-workflow — exemplar SOP that follows this template's structure
  • template-board — sibling template for board notes
  • template-project-page — sibling template for project page notes
  • html-style-guide — HTML authoring convention for note content