Section Revise

# Section Revision Workflow (Existing Content)

## Purpose

Revise existing section content: archive old visuals, update narrative, regenerate infographics using existing .content.md files, create release candidate. Uses Beads for WBS tracking. **Data accuracy is the absolute priority.**

## When to Use This Skill

Use this skill when you have EXISTING section content that needs revision:
- Existing draft(s) need updating
- Old visuals need regeneration
- Data corrections required
- Narrative needs refinement

**✅ DO use for:**
- Revising sections with existing drafts + visuals
- Updating content after data corrections
- Regenerating infographics with improved prompts
- Creating new RC from revised content

**❌ DO NOT use for:**
- Creating new sections from scratch (use `/section-create`)
- Final polish only (use `/section-publish`)
- Quick edits without visual work

## Related Skills
/section-create, /section-publish, /textbook-bestpractices, /infographics-bestpractices, /validate

## How This Differs from Other Skills

| Skill | Starting Point | Use Case |
|-------|---------------|----------|
| `/section-create` | Research + Q&A (from scratch) | New section authoring |
| `/section-revise` | Existing drafts + visuals | Revision + regeneration |
| `/section-publish` | Final draft (polish only) | RC generation |

**Key difference:** `/section-revise` reuses existing .content.md files and considers latest draft, but archives old visuals and regenerates.

## Required Skills Preload

**🔴 CRITICAL: Load these skills FIRST:**

```markdown
/textbook-bestpractices       # Academic writing
/infographics-bestpractices   # Visual design
/narrative-refine-validate    # Claim validation
/validate                     # Fact-checking

Workflow Overview

┌──────────────────────────────────────────────────┐
│ INPUT: Existing section with drafts + visuals    │
│ (e.g., docs/writing/2-education/...)            │
└──────────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────────┐
│ STEP 0: Beads WBS Creation                       │
│ - Create epic for revision                       │
│ - Track archive, validate, regenerate, RC        │
└──────────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────────┐
│ STEP 1: Archive Existing Visuals                 │
│ - Move visual folders → archive/                 │
│ - Preserve .content.md and .prompt.md files      │
│ - Copy preserved files back to new folders       │
└──────────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────────┐
│ STEP 2: Review Latest Draft                      │
│ - Identify highest draft number                  │
│ - Review against success criteria                │
│ - Determine revision needs                       │
└──────────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────────┐
│ STEP 3: Validate & Refine (if needed)            │
│ - Run /validate on latest draft                  │
│ - Create fact-check report                       │
│ - Apply corrections → draftN+1                   │
│ - Iterate until 90%+ accuracy                    │
└──────────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────────┐
│ STEP 4: Update Visual Content Files              │
│ - Review existing .content.md files              │
│ - Apply data corrections from validation         │
│ - Update .prompt.md with improvements            │
└──────────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────────┐
│ STEP 5: Regenerate Visuals                       │
│ - Generate new variants via gemini-generate      │
│ - Evaluate all variants                          │
│ - Select winners (90%+ target)                   │
└──────────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────────┐
│ STEP 6: Update Draft References                  │
│ - Update image references to new variants        │
│ - Verify captions match new visuals              │
│ - Create draftN+2 (final)                        │
└──────────────────────────────────────────────────┘
                    ↓
┌──────────────────────────────────────────────────┐
│ STEP 7: Generate Release Candidate               │
│ - Create formatted markdown (7" images)          │
│ - Generate DOCX via Pandoc                       │
│ - Apply justified text alignment                 │
│ → Output: {topic}.rcN.docx                       │
└──────────────────────────────────────────────────┘

Command Invocation

/section-revise docs/writing/{topic}/

Examples:

/section-revise docs/writing/2-education/
/section-revise docs/writing/5-analytics/

Detailed Steps

Step 0: Beads WBS Creation

Create epic for revision:

bd create --title="Section {N}: {Topic} - Revision + regeneration" \
  --type=epic \
  --priority=2 \
  --description="Revise existing section: archive old visuals, validate draft, regenerate infographics, create RC.

Starting state:
- Existing draft{N}.md (review + validate)
- Existing visuals (archive + regenerate)
- Existing .content.md/.prompt.md (reuse + update)

Success criteria:
- 90%+ data accuracy
- Regenerated visuals (90%+ scores)
- Release candidate ready

Core principle: Data accuracy MOST IMPORTANT"

Create tasks:

# Archive & Setup (P2)
bd create --title="Archive old visuals to archive/ folder" --type=task --priority=2
bd create --title="Copy .content.md and .prompt.md back" --type=task --priority=2
bd create --title="Review latest draft, identify revision needs" --type=task --priority=2

# Validation (P1)
bd create --title="Run /validate on latest draft" --type=task --priority=1
bd create --title="Apply correc