pal-e-docs

Convention: Arch-SOP Pairing

convention-arch-sop-pairing Convention

active convention
Project

Convention: Arch-SOP Pairing

Every architecture note describes HOW something works. A paired SOP describes WHAT TO DO when interacting with it. Architecture without procedures is a museum exhibit — beautiful but unusable under pressure.

The Rule

Every architecture-tagged note (tag: architecture) MUST include one of the following in its content:
  • Explicit SOP link: A ### Procedures section (or equivalent) containing See <sop-slug> for procedures
  • Documented exemption: No SOP needed — <rationale> (e.g., reference-only notes, historical assessments, conceptual docs)
The link goes in the arch note pointing to the SOP. The SOP's ### Related section links back to the arch note. Bidirectional.

Why

Without this convention:
  • Architecture knowledge stays theoretical — agents can read how something works but not what to do when it breaks
  • SOPs drift from architecture — the procedures reference stale diagrams, the diagrams reference deprecated procedures
  • Cross-pillar triggers (convention-cross-pillar-triggers) have no discovery mechanism — you can't review affected SOPs if you don't know which ones pair with which arch notes
  • Dottie can't audit completeness without a convention to audit against

Good Example

arch-secrets-pipeline has a ### Procedures section:
See sop-secrets-management for step-by-step procedures (adding secrets, rotation, recovery).
The SOP's Related section links back to the architecture note. An agent debugging a secrets issue finds the architecture (HOW it works), follows the link to the SOP (WHAT TO DO), and executes. No guessing.

Discovery Pattern

When working on a topic, agents should locate both the architecture and the procedures:
  • search_notes(query="<topic>", tags="architecture") — find the HOW
  • search_notes(query="<topic>", note_type="sop") — find the WHAT TO DO
  • Check the arch note's Procedures or Related section for an explicit SOP link
  • If no link exists, flag it — either the pairing is missing or the exemption needs documenting

Current Inventory

Architecture notes and their SOP pairing status (as of 2026-03-14):
Arch Note Project Paired SOP Status
<code>arch-secrets-pipeline</code> pal-e-platform <code>sop-secrets-management</code> Paired
<code>platform-architecture</code> pal-e-platform <code>sop-deploy-recovery</code>, <code>sop-ci-pipeline-recovery</code>, <code>sop-postgres-restore</code>, <code>sop-secrets-management</code> Paired
<code>enforcement-architecture</code> pal-e-agency <code>sop-hook-block-recovery</code> Paired
<code>arch-domain-pal-e-agency</code> pal-e-agency <code>agent-workflow</code>, <code>agent-spawn-conventions</code> Paired
<code>agent-paradigm</code> pal-e-agency <code>agent-spawn-conventions</code> Paired
<code>doc-pal-e-docs-schema</code> pal-e-docs <code>sop-db-migration-recovery</code> Paired
<code>entity-page-architecture</code> pal-e-docs None needed Exempt (conceptual)
<code>arch-deployment-westside-basketball</code> Westside Basketball <code>sop-deploy-recovery</code> Paired
<code>arch-dataflow-westside-basketball</code> Westside Basketball None needed Exempt (reference)
<code>arch-domain-westside-basketball</code> Westside Basketball None needed Exempt (reference)
<code>tf-architecture-assessment-2026-02-26</code> pal-e-platform None needed Exempt (historical assessment)
<code>tf-current-filetree</code> pal-e-platform None needed Exempt (reference snapshot)
<code>tf-environment-strategy</code> pal-e-platform None needed Exempt (roadmap, not deployed)
<code>tf-modularization-roadmap</code> pal-e-platform None needed Exempt (completed plan reference)
<code>tf-best-practices-comparison</code> pal-e-platform None needed Exempt (reference)
<code>tf-postgres-strategy</code> pal-e-platform <code>sop-postgres-restore</code> Paired
<code>hook-events-reference</code> pal-e-agency <code>sop-hook-block-recovery</code> Paired
<code>argocd-image-updater</code> pal-e-platform <code>sop-deploy-recovery</code> Paired
<code>insight-devops-materializes-at-team-onboarding</code> pal-e-platform None needed Exempt (insight/essay)
Score: 10/10 explicitly paired. 8 exempt (valid). 1 was already paired (arch-secrets-pipeline). 9 newly paired by Dottie on 2026-03-14.

Audit Pattern

Dottie should periodically:
  • list_notes(tags="architecture") — get all arch notes
  • For each, check for a ### Procedures section or "No SOP needed" text
  • Flag any note missing both as a compliance gap
  • Update the inventory table in this convention after each audit
Target: 100% of arch notes explicitly paired or exempted. Current: 9/19 (47%).
  • convention-cross-pillar-triggers — pairing makes cross-pillar reviews discoverable
  • sop-post-merge-docs — /update-docs should verify pairing after merges that create arch notes
  • arch-secrets-pipeline + sop-secrets-management — the exemplar pairing
  • phase-pal-e-agency-9-ci-driven-operating-model — deliverable 9i