carloscape/octorato/long-document-revision-protocol

## Pre-Revision Checklist
 
1.Document Statistics
   -[ ] Total line count: ___
   -[ ] Number of sections (## headers): ___
   -[ ] Number of cross-references (§, Finding #, Evidence #): ___
   -[ ] Number of status markers (✅⚠️🔴⏳): ___
 
2.Change Impact Assessment
   -[ ] Which sections will I modify?
   -[ ] Which sections reference those sections?
   -[ ] Are there status markers in affected areas?
   -[ ] Will structure (section numbers) change?
 
3.Backup
   -[ ] Git commit before changes? (recommended)
   -[ ] Or: copy to _backup.md

## During Editing
 
-[ ] For each fact added: Is this fact stated elsewhere? (→ reference, don't duplicate)
-[ ] For each status change: Update the marker (✅⚠️🔴⏳)
-[ ] For each structural change: Note affected cross-references
-[ ] For each new section: Match voice/tense of surrounding content

## Post-Revision Audit
 
### 3.1 Semantic Coherence (Skill #38)
-[ ] No contradictions between edited and unedited sections
-[ ] Summary sections align with detail sections
-[ ] Conclusions still supported by evidence
 
### 3.2 Cross-Reference Integrity (Skill #39)
-[ ] All §X.Y references resolve to existing sections
-[ ] All Finding #N references exist in findings register
-[ ] All Evidence #N references exist in evidence register
-[ ] No orphan references from deleted content
 
### 3.3 Status Marker Hygiene (Skill #40)
-[ ] No ✅ on incomplete items
-[ ] No ⏳ on completed items
-[ ] No ⚠️ on resolved issues
-[ ] No stale "TBD" or "pending" text near ✅ markers
 
### 3.4 Content Deduplication (Skill #41)
-[ ] No verbatim paragraphs in multiple locations
-[ ] Key facts have single authoritative source
-[ ] Other occurrences reference the source
 
### 3.5 Voice Consistency (Skill #42)
-[ ] Tense consistent (present for facts, future for plans)
-[ ] Person consistent (we/MVH/passive)
-[ ] Tone consistent (formal-neutral throughout)
-[ ] No jarring style shifts at edit boundaries
 
### 3.6 Structural Completeness (Skill #43)
-[ ] No empty sections (header without content)
-[ ] No orphan headers (### without parent ##)
-[ ] Section numbering sequential
-[ ] All promised content delivered

# Status marker count
echo "✅: $(grep -c '✅' doc.md)"
echo "⚠️: $(grep -c '⚠️' doc.md)"
echo "🔴: $(grep -c '🔴' doc.md)"
echo "⏳: $(grep -c '⏳' doc.md)"
 
# Stale marker search
grep -n "TBD\|PENDING\|deferred\|~~" doc.md
 
# Reference inventory
grep -oE '§[0-9.]+' doc.md | sort | uniq -c | sort -rn | head -20
 
# Empty section detection
grep -n '^##' doc.md | while read line; do
  linenum=$(echo $line | cut -d: -f1)
  nextline=$((linenum + 1))
  sed -n "${nextline}p" doc.md | grep -q '^#' && echo "Empty section at line $linenum"
done

□ Contradictions? (search antonyms near edit)
□ References valid? (§, Finding #, Evidence #)
□ Markers accurate? (✅⚠️🔴⏳)
□ Duplicates? (search key phrases)
□ Voice match? (tense, person, tone)
□ Structure intact? (headers have content)

# Before major revision
git add -A && git commit -m "checkpoint before revision"
 
# After revision passes protocol
git add -A && git commit -m "revision complete - coherence verified"
 
# If issues found
git diff  # see what changed
git checkout -- document.md  # revert if needed