Skip to content

SOP-064 — Prompt-architecture review

Guide

<!-- last-reviewed: 2026-06-01 · owner: AI Systems (AI Systems Director) -->

SOP-064 — Prompt-architecture review

SOP · owner: AI Systems (AI Systems Director). Layer: SOP/Runbook (docs/canon.md). The prompt quality bar lives in .claude/agents/ai-systems-director.md (“The prompt quality bar”) — linked, not restated (one home per fact).

Interface Contract

  • Inputs: prompt / agent-def / skill-file change request ← from <requesting agent/unit> · trigger: review requested
  • Inputs: difficulty / objective metadata / AI-spec requirements ← from <issuing unit> · trigger: requirements issued
  • Outputs: prompt-change diff + per-change rationale → to Principal · trigger: review requested
  • Outputs: approved AI doc (review record) → to Archivist · trigger: artifact approved
  • Handoff trigger (in): a prompt, agent definition, or skill file is proposed for change or audit
  • Handoff trigger (out): a diff-ready review with rationale is delivered for approval (the Principal/HR approves def changes; the Director approves its own review record for preservation)
  • Definition of Done before handoff:
    • [ ] Assessed against all six prompt-quality-bar tests (sharp description, minimum viable tools, single-purpose, explicit lane boundaries, testable behavior, model-appropriate)
    • [ ] Findings are diff-ready — exact proposed text, not “tighten this” — each with a one-line rationale
    • [ ] Model mismatch (if any) flagged with a cost/quality tradeoff estimate
    • [ ] Changes to .claude/agents/ / ORG.md / JDs are proposed, not self-edited (charter rule 5)
    • [ ] Review record handed to the Archivist (0 drift)
    • [ ] Learnings captured to docs/knowledge/ if the review surfaced one

Trigger phrases are drawn from docs/handoff-triggers.md: review requested (in/out), artifact approved (to the Archivist fan-in sink). Edges to the Principal are exempt (Principal) (interface-contract-spec.md §3.1 R2).

Purpose

Hold every system prompt — agent definitions, skill files, product-feature prompts — to the prompt quality bar, and produce a diff-ready review so a bad prompt or wrong tool grant is caught before it compounds.

When to use

When a prompt/def/skill-file change is proposed, when a new agent is being authored, or on a standing audit pass. If the request is to implement an AI feature rather than review a prompt, that is SOP-067 (AI Engineer); if it is a model-tier question, that is SOP-065.

Flow

flowchart LR
  R["review requested"] --> A["Read prompt +<br/>sibling context"]
  A --> B["Assess vs<br/>quality bar"]
  B --> C["Draft diff-ready<br/>changes + rationale"]
  C --> M{"Model<br/>mismatch?"}
  M -->|yes| F["Flag tradeoff<br/>(→ SOP-065)"]
  M -->|no| P["Present diff<br/>to Principal"]
  F --> P
  P --> ARCH["artifact approved<br/>→ Archivist"]
  classDef s fill:#1d4ed8,color:#fff,stroke:#1e3a8a
  classDef d fill:#0f766e,color:#fff,stroke:#134e4a
  class R,A,B,C,F,P,ARCH s
  class M d

Text fallback: a review requested arrives → read the prompt and its sibling context (related agents, the methodology it serves, the tools it uses) → assess against the six quality-bar tests → draft diff-ready changes with rationale → if there is a model mismatch, flag the tradeoff (hand to SOP-065) → present the diff to the Principal → on approval, hand the review record to the Archivist (artifact approved).

Steps

  1. Read the prompt/def/skill file in full plus its sibling context — related agent defs, the methodology it serves, the tools it grants.
  2. Assess against the prompt quality bar (.claude/agents/ai-systems-director.md): sharp description, minimum viable tools, single-purpose, explicit lane boundaries (names the adjacent owner), testable behavior, model-appropriate.
  3. Draft diff-ready changes — exact proposed text for each defect, each with a one-line rationale. Vague suggestions fail the falsifiability bar.
  4. Flag model mismatch — if the task warrants a different tier, state the cost/quality tradeoff and hand the tier decision to SOP-065.
  5. Present to the Principal. Material changes to .claude/agents/, ORG.md, or JDs are proposed for Principal/HR approval — never self-edited. Minor typo/clarity fixes to non-def docs may be applied directly.
  6. Hand off the review record to the Archivist on approval (artifact approved); capture any learning to docs/knowledge/.

Roles / approvers

Authored and run by the AI Systems Director. Def-file changes are approved by the Principal / HR (HR owns .claude/agents/ and ORG.md). The Director approves its own review record for preservation (recorded, not an independence proof — R11).

Guardrails

  • Diff-ready or it is not done. Exact text, per-change rationale (charter rule 3).
  • Propose def changes, never self-edit them (charter rule 5).
  • Never silently comply with a prompt design you believe is wrong (GR-3).
  • Do not restate the quality bar here — link to the JD (one home per fact).
  • Draw triggers from the registry; never invent inline.

Job aid: N/A — judgement-led; the diff-ready discipline is the procedure itself. See also: .claude/agents/ai-systems-director.md (“The prompt quality bar”) · docs/units/ai-systems/charter.md · SOP-065 (model selection) · docs/sop/change-management.md (SOP-002 DoD) · docs/handoff-triggers.md · interface-contract-spec.md §3.1.