STD-013: Case Studies Taxonomy

Every operational event — outages, planned changes, vendor engagements, deployments, root cause investigations — produces structured documentation. Case studies are not bureaucracy; they are the mechanism that converts experience into institutional knowledge. Without them, the same failures recur and the same lessons are re-learned.

Principles

  1. Every operational event gets documented. If it changed production state, caused an outage, required vendor support, or deployed infrastructure, it gets a case study. Undocumented events are invisible to future operators.

  2. Naming is deterministic. The filename is derived mechanically from prefix + date + slug. No creativity required, no ambiguity possible. Given the event type and date, the filename is predictable.

  3. Cross-referencing creates audit trails. An incident references its RCA. The RCA references the change record that fixed it. The change record references the runbook used. This chain is the audit trail.

  4. Context tagging enables filtering. Every case study carries a :context: attribute (work or personal) enabling separate views and reporting.

Directory Structure

case-studies/
├── tac/            # Vendor TAC cases (Cisco, Microsoft, etc.)
├── incidents/      # Incident reports (INC-*)
├── changes/        # Change requests (CR-*)
├── rca/            # Root cause analysis (RCA-*)
├── deployments/    # Major deployment records (DEPLOY-*)
├── templates/      # Templates for new entries
└── diagrams/       # D2/Mermaid source files for case study diagrams

All case study files reside under pages/case-studies/ in their respective subdirectory.

Naming Convention

Prefix Format Example

TAC-

TAC-YYYY-MM-DD-<vendor>-<slug>.adoc

TAC-2026-03-12-cisco-8021x-auth-failures.adoc

INC-

INC-YYYY-MM-DD-<slug>.adoc

INC-2026-03-10-vault-backup-selinux.adoc

CR-

CR-YYYY-MM-DD-<slug>.adoc

CR-2026-03-12-p50-arch-to-ubuntu.adoc

RCA-

RCA-YYYY-MM-DD-NNN-<slug>.adoc

RCA-2026-03-16-001-8021x-eaptls-ca-chain.adoc

DEPLOY-

DEPLOY-YYYY-MM-DD-<slug>.adoc

DEPLOY-2026-02-14-bind-dns-ha.adoc

Dates are ISO 8601 (YYYY-MM-DD). Slugs are kebab-case. RCA uses a sequential number (NNN) when multiple analyses occur on the same date.

Context Tagging

Every case study MUST include a :context: attribute in its document header:

:context: work     // CHLA, professional engagements
:context: personal // Domus Digitalis, home infrastructure

This attribute enables filtered views and context-aware reporting across the case study index.

Cross-Reference Chain

Case studies do not exist in isolation. They form a learning lifecycle:

INC (Incident) → RCA (Root Cause Analysis) → Pattern (Transferable Lesson) → Standard (Codified Rule)

  • An Incident documents what happened and how it was resolved.

  • An RCA investigates why it happened and how to prevent recurrence.

  • A Pattern extracts the transferable wisdom for the pattern journal.

  • A Standard codifies the lesson into enforceable policy.

Every document in this chain MUST cross-reference its predecessor and successor. Orphaned documents — incidents without RCAs, RCAs without pattern entries — represent incomplete learning.

Trigger Rules

Certain events MUST produce specific document types. This is not discretionary.

Event Required Documents Notes

P1 or P2 incident

INC- + RCA- (within 5 business days)

RCA is mandatory per STD-010

P3 incident

INC-; RCA- SHOULD be created

RCA recommended but not required

P4 incident

INC- MAY be created

Required if 3+ P4s share the same root cause category within 30 days

Planned change to production

CR-

Follows change control (STD-005)

Vendor support engagement

TAC-

Filed at case open, updated through resolution

Major deployment or migration

DEPLOY-

Infrastructure builds, platform migrations, HA deployments

Changes made during incident resolution

CR- per change

Changes during incidents still follow change control

Statistics Maintenance

The case studies index page (pages/case-studies/index.adoc) displays counts using antora.yml attributes:

  • 1 — TAC case count

  • 7 — Incident count

  • 32 — Change request count

  • 10 — RCA count

  • 7 — Deployment count

  • 2026-04-01 — Last updated date

When adding a new case study entry, the corresponding stats attribute in antora.yml MUST be incremented and 2026-04-01 MUST be set to the current date.

Requirements

  1. Every case study MUST use the correct prefix from the Naming Convention table.

  2. Every case study MUST be filed in its correct subdirectory under pages/case-studies/.

  3. Every case study MUST include a :context: attribute with value work or personal.

  4. P1 and P2 incidents MUST produce both an INC- report and an RCA- analysis.

  5. Every RCA- document MUST cross-reference its originating INC- document.

  6. Every INC- resolved by a configuration change MUST cross-reference the corresponding CR- document.

  7. Statistics attributes in antora.yml MUST be updated when adding or removing case study entries.

  8. The case studies index page MUST be updated with a table row for every new entry.

  9. Slugs MUST be kebab-case: lowercase, hyphens only, no underscores or spaces.

  10. Dates in filenames MUST use ISO 8601 format (YYYY-MM-DD).

Compliance

Check Method Pass Criterion

Correct prefix used

Filename starts with a registered prefix (TAC-, INC-, CR-, RCA-, DEPLOY-)

No invented prefixes

Filed in correct directory

File resides in pages/case-studies/<type>/ matching its prefix

No misplaced files

Context attribute present

Document header contains :context: work or :context: personal

Attribute present and valid

Cross-references complete

INC references RCA; RCA references INC and CR; CR references related INC if applicable

No orphaned documents in the chain

Statistics current

Stats attributes in antora.yml match actual file counts per category

Counts accurate

Index updated

pages/case-studies/index.adoc contains a table row for every case study file

No undiscoverable entries

Trigger rules followed

P1/P2 incidents have RCAs; planned changes have CRs; vendor cases have TACs

Required documents exist

Related