# RCA Template — Root Cause Analysis Document Template # KNO Schema Version: 0.1.0 # # Template for authoring Root Cause Analysis (RCA) documents. # RCA documents extend `document-schema` with `purpose: rca` per Schema Minimization. # # This template is NOT a new schema — it is a structural template (a `type: template` # document) that defines the standard sections an RCA should contain. The actual # RCA documents written from this template are document-schema instances with # `purpose: rca`. # # USAGE: # 1. Copy the structure below into a new `.kno` file under `docs/rcas/` or # `content/rcas/` (final location TBD per Phase 0 storage decision). # 2. Set $schema, kno_type: document, purpose: rca on the new file. # 3. Fill out the four required sections: failure_chain, five_whys, # patterns_extracted, knowledge_integration_checklist. # 4. Cross-reference any related entities via `evidence_refs`. # # SOURCE: # Pongogo deep-analysis §F7 — see # research/2026_04_28-pongogo-deep-analysis/07-pongogo-applied-research.md#f7-rca-template--failure-chain-analysis--patterns-extracted-with-occurrence-counts # # CODIFICATION: # M22 Wave 3 of Pongogo learnings — Epic #2156, issue #2161. # ============================================================================= # SCHEMA DECLARATION # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # BASIC TIER # ============================================================================= id: 01KQAWZ1W7YFP3HJ0ZV00XED8T slug: rca-template type: template version: 0.1.0 # ============================================================================= # STANDARD TIER # ============================================================================= title: "Root Cause Analysis Template" purpose: | Standard structural template for RCA (Root Cause Analysis) documents. RCA documents are first-class inputs to the failure-is-knowledge promotion pipeline — they synthesize T0/T1/T2 signal into T3-grade evidence about what went wrong, why, and what must change. The template enforces enough structure that pattern extraction and occurrence counting work; it leaves the prose narrative free. **Template, not schema**: per the 3-Gate Test (Schema Minimization), RCAs are not fundamentally distinct from documents. They are documents with `purpose: rca`. This file is a `type: template` reference for authors — not a new entity schema. # ============================================================================= # RICH TIER # ============================================================================= provenance: origin: id: 01KQAWZ1W7YFP3HJ0ZV00XED8T timestamp: "2026-04-28T00:00:00Z" tool: manual-authoring motivated_by: - issue: 2161 url: "https://github.com/PossibilityTruthy/possibility-space/issues/2161" summary: "M22 Wave 3 — codify Pongogo §F7 RCA template" - epic: 2156 url: "https://github.com/PossibilityTruthy/possibility-space/issues/2156" summary: "Codify Pongogo learnings (12-action plan)" taxonomy: topics: - failure-analysis - root-cause-analysis - failure-is-knowledge - templates keywords: - rca - root-cause - failure-chain - five-whys - patterns - retrospective relationships: composes: - xri: "kno://specs/document-schema" reason: "Template instances are document-schema documents with purpose: rca" related_to: - xri: "kno://principles/failure-is-knowledge" reason: "RCAs are the principal mechanism that surfaces signal for T2→T3 promotion" - xri: "kno://specs/decision-schema" reason: "Decisions made in response to an RCA are recorded as decision entities" enables: - xri: "kno://patterns/pattern-extraction" reason: "patterns_extracted block feeds occurrence counts that drive T3 promotion" implements: - xri: "kno://principles/PRO-05" reason: "Silent Failure Suppression — RCAs are the structured output that prevents failures from being silently absorbed" quality: completeness: 0.85 last_reviewed: "2026-04-28" review_status: draft reviewed_by: "claude" # ============================================================================= # HISTORY # ============================================================================= _history: version: 1 created: "2026-04-28T00:00:00Z" created_by: "claude" modified: "2026-04-28T00:00:00Z" modified_by: "claude" # ============================================================================= # TEMPLATE CONTENT # ============================================================================= template: status: Draft applies_to_purpose: rca # --------------------------------------------------------------------------- # REQUIRED SECTIONS # --------------------------------------------------------------------------- required_sections: - failure_chain - five_whys - patterns_extracted - knowledge_integration_checklist # --------------------------------------------------------------------------- # SECTION DEFINITIONS # --------------------------------------------------------------------------- sections: # ----------------------------------------------------------------------- # 1. FAILURE CHAIN # ----------------------------------------------------------------------- failure_chain: description: | Ordered sequence of events from initial trigger through final impact. Each event is one link in the chain; the chain itself shows how a single trigger propagated into a systemic failure. Authoring rule: if you can't explain how event N caused event N+1, you have a gap that needs investigation before this RCA is complete. shape: type: ordered_list item_fields: - name: ordinal description: "Position in the chain (1, 2, 3, ...)" required: true - name: event description: "What happened, in one sentence" required: true - name: timestamp description: "When it happened (UTC ISO-8601)" required: true - name: actor description: "Who/what did it (agent identity, user, system component)" required: true - name: evidence_ref description: "XRI or URL to the evidence (log line, commit, ticket)" required: true - name: led_to description: "Reference to the next event's ordinal, or 'impact' if terminal" required: true example: | failure_chain: - ordinal: 1 event: "Agent received 'let's proceed' as approval to plan" timestamp: "2025-12-20T14:32:00Z" actor: "user" evidence_ref: "chat-transcript:msg-1247" led_to: 2 - ordinal: 2 event: "Agent interpreted as approval to execute autonomously" timestamp: "2025-12-20T14:32:15Z" actor: "agent:claude-sonnet-4" evidence_ref: "chat-transcript:msg-1248" led_to: 3 - ordinal: 3 event: "3 hours of unattended changes across 47 files" timestamp: "2025-12-20T17:34:00Z" actor: "agent:claude-sonnet-4" evidence_ref: "git-log:a3f1b2..." led_to: impact # ----------------------------------------------------------------------- # 2. FIVE WHYS — WITH VALIDATION # ----------------------------------------------------------------------- five_whys: description: | The classic 5-Whys, but with one critical addition per "why": a `validation` field that records whether the "why" was verified against evidence, or was an assumption. Authoring rule: at least three of the five whys must be `verified` — not assumed. An RCA built on five assumed whys is a story, not an analysis. shape: type: ordered_list max_items: 5 item_fields: - name: ordinal description: "Position (1 through 5)" required: true - name: why description: "The 'why' question" required: true - name: answer description: "The answer (short paragraph)" required: true - name: evidence_ref description: "XRI or URL to the evidence supporting this answer" required: true - name: validation description: "Status of the answer: verified | assumed | partially-verified" required: true allowed_values: - verified - assumed - partially-verified - name: validation_note description: "If 'assumed' or 'partially-verified', explain what would be needed to verify" required: false example: | five_whys: - ordinal: 1 why: "Why did the agent take 3 hours of autonomous action?" answer: "Because 'let's proceed' was interpreted as autonomy, not as plan-approval" evidence_ref: "chat-transcript:msg-1247-1248" validation: verified - ordinal: 2 why: "Why was 'let's proceed' interpreted as autonomy?" answer: "Runtime had no plan/execute mode separation; default was full autonomy after any approval-shaped phrase" evidence_ref: "code:agent-loop/runtime.ts@d3a2..." validation: verified # ----------------------------------------------------------------------- # 3. PATTERNS EXTRACTED — WITH OCCURRENCE COUNTS # ----------------------------------------------------------------------- patterns_extracted: description: | Named patterns surfaced by this RCA, with occurrence counts across all prior RCAs. Occurrence counts feed the T2→T3 promotion gate (see failure-is-knowledge: default = 3rd occurrence within 30 days triggers T3 promotion). Authoring rule: every pattern needs a name. An unnamed pattern cannot be referenced and cannot be counted. Per the Naming-as-Discipline rule, name the pattern even if the name is provisional (mark with "(provisional)" for the 7-day grace period). shape: type: list item_fields: - name: pattern_name description: "Short canonical name (e.g., 'Plan-as-Authorization Conflation')" required: true - name: pattern_slug description: "kebab-case slug for cross-referencing (e.g., 'plan-as-authorization-conflation')" required: true - name: provisional description: "true if the name is within its 7-day grace period; false if ratified" required: true - name: description description: "One-sentence pattern description" required: true - name: occurrences description: "Integer count of prior RCAs where this pattern appears (0 = first observation)" required: true - name: prior_occurrence_refs description: "List of XRIs to prior RCAs containing this pattern (empty if occurrences = 0)" required: true - name: confidence description: "Float 0.0-1.0 — how confident the pattern boundary is correct" required: true - name: pattern_library_status description: "candidate | promoted | retired" required: true allowed_values: - candidate - promoted - retired - name: t3_promotion_eligible description: "true if occurrences ≥ 3 within 30 days (or per-signature override)" required: true example: | patterns_extracted: - pattern_name: "Plan-as-Authorization Conflation" pattern_slug: "plan-as-authorization-conflation" provisional: false description: "Approval to plan being interpreted as approval to execute" occurrences: 2 prior_occurrence_refs: - "kno://rcas/2025-12-20-three-hour-runaway" - "kno://rcas/2026-02-04-bypassed-phase-gate" confidence: 0.95 pattern_library_status: candidate t3_promotion_eligible: false # 2 occurrences; needs 3rd within 30 days # ----------------------------------------------------------------------- # 4. KNOWLEDGE INTEGRATION CHECKLIST # ----------------------------------------------------------------------- knowledge_integration_checklist: description: | What must change as a direct result of this RCA. Every item must have a target artifact, a change type, and an owner. "Nothing" is a valid item — but only if explicitly justified. Authoring rule: an RCA without a knowledge-integration checklist is a postmortem, not an RCA. The point is to change the system so the failure cannot recur in the same shape. shape: type: list item_fields: - name: change_type description: "What kind of change" required: true allowed_values: - instruction-edit - spec-edit - bedrock-proposal - runtime-check - test-added - process-change - none - name: target_artifact description: "Path or XRI of the artifact to change (or 'n/a' if change_type is 'none')" required: true - name: change_summary description: "One-sentence description of the change" required: true - name: owner description: "Who is responsible for landing the change (agent identity or human handle)" required: true - name: tracking_issue description: "GitHub issue number for the change (created during RCA, not after)" required: true - name: completed description: "boolean — has the change landed yet?" required: true - name: justification_for_none description: "Required only when change_type is 'none' — why no change is warranted" required: false example: | knowledge_integration_checklist: - change_type: instruction-edit target_artifact: ".github/copilot-instructions.md" change_summary: "Codify Plan/Execute Approval Separation as default" owner: "@max" tracking_issue: 2159 completed: true - change_type: runtime-check target_artifact: "services/pspace-api/src/lib/agent-loop/runtime.ts" change_summary: "Add execution_context required field; default to plan" owner: "@max" tracking_issue: 2159 completed: false # --------------------------------------------------------------------------- # OPTIONAL SECTIONS # --------------------------------------------------------------------------- optional_sections: - executive_summary # 3-5 sentence summary at top for quick scanning - timeline # Wall-clock timeline if multiple actors / longer than one turn - systemic_issues # Cross-RCA issues this incident is one instance of - related_rcas # XRIs to prior RCAs in the same pattern family # --------------------------------------------------------------------------- # DOCUMENT-SCHEMA FRONTMATTER FOR INSTANCES # --------------------------------------------------------------------------- # Every RCA document (instance of this template) MUST declare: instance_frontmatter_required: - "$schema: kno@0.0.9" - "kno_type: document # or omit if implied" - "type: document # Layer 2 base type" - "purpose: rca" - "id: " - "slug: " - "title: "