Risk Assessment

Risk	Likelihood	Mitigation
Content loss during split	Low	Git tracks every change. One commit per case study — atomic and reversible.
Broken xrefs after directory change	Medium	Full-path xrefs required. Build verification catches broken references immediately.
Nav becomes too long with granular entries	Medium	74 case studies x 4 sections avg = ~300 nav entries. Consider nav grouping by year or collapsible sections in future UI update.
Inconsistent partial splits	Low	Per-type patterns are defined in this CR. Every file follows the same template for its type.
Context tag misassignment	Low	Each file is read individually. When ambiguous, default to personal and correct later.

Risk

Likelihood

Mitigation

Content loss during split

Low

Git tracks every change. One commit per case study — atomic and reversible.

Broken xrefs after directory change

Medium

Full-path xrefs required. Build verification catches broken references immediately.

Nav becomes too long with granular entries

Medium

74 case studies x 4 sections avg = ~300 nav entries. Consider nav grouping by year or collapsible sections in future UI update.

Inconsistent partial splits

Low

Per-type patterns are defined in this CR. Every file follows the same template for its type.

Context tag misassignment

Low

Each file is read individually. When ambiguous, default to personal and correct later.

Rollback Plan

Pre-Implementation: Capture Baseline

Before each phase begins, record the starting commit hash. This is the rollback anchor.

# Record baseline before starting a phase
BASELINE=$(git rev-parse HEAD)
echo "Phase N baseline: $BASELINE" | tee -a /tmp/modularization-baselines.txt

# Verify clean state
git status
# Expected: clean working tree

Per-Commit Validation (Delta Check)

Every commit converts one case study. After each commit, validate that content is unchanged by comparing the original monolithic file against the new partials.

# Step 1: Extract text content from the original file (before the commit)
# git show retrieves the file as it existed in the parent commit
git show HEAD~1:docs/modules/ROOT/pages/case-studies/changes/<original-file>.adoc \
  | grep -v '^//' | grep -v '^=' | grep -v '^:' | grep -v '^$' \
  | sort > /tmp/delta-original.txt

# Step 2: Concatenate all new partials into one stream
cat docs/modules/ROOT/partials/case-studies/changes/<slug>/*.adoc \
  | grep -v '^//' | grep -v '^=' | grep -v '^:' | grep -v '^$' \
  | sort > /tmp/delta-partials.txt

# Step 3: Compare — delta should be zero for content lines
diff /tmp/delta-original.txt /tmp/delta-partials.txt

# Expected: no output (identical content)
# If output exists: content was lost or altered — investigate before proceeding

The delta formula:

Delta = |Lines(original)| - |Lines(partials)|

Delta == 0  → content preserved (proceed)
Delta > 0   → content lost (investigate — lines missing from partials)
Delta < 0   → content added (investigate — unintended additions)

Quantitative Validation (Per Phase)

After completing an entire phase, validate aggregate line counts.

# Count total content lines in new partials for this phase
PARTIAL_LINES=$(find docs/modules/ROOT/partials/case-studies/changes/ \
  -name "*.adoc" -exec cat {} \; | grep -cv '^$\|^//\|^=\|^:')

# Compare against known baseline from inventory
# (Changes phase: ~14,200 lines total, content lines ~11,000)
echo "Partial content lines: $PARTIAL_LINES"

# Page shells should all be < 15 lines
find docs/modules/ROOT/pages/case-studies/changes/*/  \
  -name "*.adoc" -exec awk 'END{if(NR>15) print FILENAME": "NR" lines"}' {} \;
# Expected: no output

Single Case Study Rollback

If one case study conversion is wrong, revert that single commit.

# Step 1: Identify the commit
git log --oneline --all -- "docs/modules/ROOT/pages/case-studies/changes/<slug>/" | head -1
# Output: abc1234 refactor(case-study): modularize CR-2026-XX-XX-slug

# Step 2: Revert it
git revert abc1234

# Step 3: Verify build
make 2>&1 | grep -E "WARN|ERROR"

# Step 4: Verify the original file is restored
ls docs/modules/ROOT/pages/case-studies/changes/<original-file>.adoc
# Expected: file exists (restored by revert)

Full Phase Rollback

If an entire phase needs to be undone, revert all commits back to the baseline.

# Step 1: Read baseline from the record
cat /tmp/modularization-baselines.txt
# Phase 1 baseline: abc1234def567

# Step 2: List all commits since baseline
git log --oneline $BASELINE..HEAD

# Step 3: Revert the range (creates one revert commit per original commit)
git revert --no-commit $BASELINE..HEAD
git commit -m "revert: rollback Phase N case studies modularization"

# Step 4: Verify
make 2>&1 | grep -E "WARN|ERROR"
git diff $BASELINE --stat
# Expected: no differences (fully rolled back)

Post-Rollback Validation

After any rollback, confirm the delta is zero against the original state.

# Compare current state against the recorded baseline
git diff $BASELINE --stat
# Expected: 0 files changed, 0 insertions, 0 deletions

# Verify build
make 2>&1 | grep -E "WARN|ERROR"

# Verify nav resolves
make serve &
# Spot-check nav links in browser, then kill server