RCA-2026-04-11-001: Prevention

Preventive Measures

Short-term (This Week)

Action Owner Status

Create domus-literature spoke repo — scripture pages must build independently

Evan

[ ] Pending

Add $RV, $KJV, $WLC shell aliases to .zshrc

Evan

[ ] Pending

Add Hebrew keyboard layout to Hyprland config (kb_layout = us,es,il)

Evan

[ ] Pending

Long-term (This Quarter)

Action Owner Status

Document Antora page volume limits — single component should not exceed ~2,000 pages

Evan

[ ] Pending

Establish build verification as mandatory step before committing >50 files

Evan

[ ] Pending

Add pre-push hook to run make and block push if errors/warnings exist

Evan

[ ] Pending

Migrate Don Quijote and García Márquez to domus-literature after validation

Evan

[ ] Pending

Detection

How was it detected?

  • Cloudflare Pages build timed out at 21 minutes

  • Local make hung with no output

  • User observed branch divergence via git status

Detection Gap

The build hang produced no error — just silence. Antora does not log progress or warn when page count exceeds practical limits. A timeout or memory guard would have made the failure explicit.

The pre-existing xref errors (~100) were visible in every build log for weeks. They were normalized. When new errors from this session appeared, they were filtered using the same grep "Site built" pattern that hid the old ones.

Lessons Learned

What went well

  • Git history preserved all content — nothing was lost

  • Generation script is reusable for the spoke repo

  • Case-study xref migration (110 files) was completed correctly

  • Build was restored to zero errors, zero warnings

What could be improved

  • Build verification must happen before committing large file additions

  • Build output must be read completely — never grep for success while ignoring errors

  • Never git commit --amend on pushed commits — always create new commits

  • Never work on the same files as a running background agent

  • Fix errors when first seen, not hours later

Key Takeaways

  1. Volume limit: A single Antora component should not exceed ~2,000 pages. Beyond that, use a dedicated spoke repo.

  2. Build output is not optional. make > /tmp/build.txt 2>&1 && cat /tmp/build.txt — tee to file, then read. Never filter.

  3. Amend is destructive after push. git log --oneline origin/main -1 vs git log --oneline -1 — check before amending.

  4. Error normalization is dangerous. "Pre-existing" errors are still errors. Fix them immediately or they mask new failures.

  5. Spoke architecture exists for a reason. Large content corpora (scripture, literature) need independent build pipelines. The hub aggregates; spokes isolate.

Related

  • Plan: ~/.claude/plans/crystalline-wibbling-pony.md — domus-literature spoke creation (approved, not yet executed)

  • Memory: feedback_no_amend_after_push.md — git amend lesson

  • Memory: feedback_no_duplicate_agent_work.md — background agent lesson

  • Memory: project_domus_literature.md — spoke repo project status