workshop-revise

What this skill does

**Announce:** "I'm using workshop-revise to apply changes to the workshop presentation."

## Shared Typst Constraints

Load ALL Typst conventions before touching any files:

!`uv run python3 ${CLAUDE_SKILL_DIR}/../../scripts/load-constraints.py workshop-revise`

**You MUST have these constraints loaded before any edits. No claiming you "remember" them.**

## Midpoint Entry — Self-Contained Constraint Loading

This skill may run in a new session. Load ALL needed context before touching any files.

### Session Resume Detection

Check if `.planning/HANDOFF.md` exists:
1. **If found:** Read it, show status, ask: "Resume from the recorded revision state, or start fresh?"
2. **If not found:** Proceed to Step 1.

### Iteration topology & flow

```
[Step 1: Load Context] → [Step 2: Diagnose]
        → [Step 3: Apply edits  (+ workshop-verify /goal loop, max 3 turns, for content/structure)]
        → [Step 4: Verify (compile + widow + check-all.py)]
              ├─ pass → report to user
              └─ unresolved after 3 cycles → ESCALATE to user
```

| Step | Topology | Exit condition |
|------|----------|----------------|
| Step 3 (content/structure change) | `serial` edit → `parallel` review (workshop-verify under `/goal`, **max 3 turns**) | `overallPass=true` → Step 4; else escalate |
| Step 3 (formatting-only fast path) | `one-shot` edit | edit applied → Step 4 |
| Step 4 (verify) | `serial` (compile → widow → check-all.py) | all pass; else fix (max 3 cycles) then escalate |

**The flow diagram above IS the authoritative spec for step order and gating. If prose below conflicts with it, the diagram wins.**

**After completing each step, IMMEDIATELY proceed to the next step.** Do NOT ask "should I continue?" between steps 1–4. Pausing between steps is procrastination: you lose context, the user loses momentum, and the verification gate gets skipped. Pause only at the explicit checkpoints below.

### Checkpoint types

| Point | Type | Behavior |
|-------|------|----------|
| R4 structural change detected | decision | STOP — present to user, get approval before re-entering Phase 3 |
| Step 3 artifact-review gate (content/structure) | human-verify | Auto-advanceable (independent workshop-verify reviewer) |
| Step 4 revision verified | human-verify | Auto-advanceable; report to user at end |

### Context Monitoring

A revision can itself be multi-turn and context-intensive (especially a content/structure change driving a `/goal` loop). Before starting Step 3 edits or any `/goal` loop, check context availability:

| Level | Remaining Context | Action |
|-------|------------------|--------|
| Normal | >35% | Proceed normally |
| Warning | 25–35% | Complete the current edit, then write `.planning/HANDOFF.md` and pause |
| Critical | ≤25% | Write `.planning/HANDOFF.md` immediately — do not start a new edit or `/goal` loop |

`HANDOFF.md` template (same schema as the workshop entry skill):
```yaml
---
workflow: workshop-revise
status: context_exhaustion
last_updated: [timestamp]
---
## Current State
[Which step; what edit is in progress]
## Completed Work
- [Edits applied so far, files touched]
## Remaining Work
- [Edits left + verification not yet run]
## Decisions Made
[User decisions captured during this revision]
## Rejected Approaches
[Edits tried and reverted, with reasons — so the resume does not retry them]
## Blockers
[Any unresolved blocker the next session must address, or "none"]
## Next Action
[Specific enough to resume immediately]
```

**Pushing through context exhaustion to "finish the revision" ships degraded edits the presenter debugs at the podium. Writing the handoff is the helpful move, not the slow one.**

### Step 1: Load Context

1. **Read `.planning/SOURCES.md`** — paper metadata (title, authors, affiliations)
2. **Read `.planning/OUTLINE.md`** — section structure and timing
3. **Constraints are already loaded** — the bang-invoked auto-loader at the top of this skill fires at skill-load time (no separate load needed). If you are resuming in a fresh session and skipped that, re-run it: `uv run python3 ${CLAUDE_SKILL_DIR}/../../scripts/load-constraints.py workshop-revise`
4. **Read existing `slides.typ`** — current slide content
5. **Read existing `notes.typ`** — current speaker notes

### Delete & Restart Rule

**If you edited slides.typ or notes.typ WITHOUT first completing Step 1 (loading SOURCES.md, OUTLINE.md, and constraints), DELETE your edits and restart from Step 1.** Edits made without context produce inconsistencies that are harder to fix than to redo.

### Step 2: Diagnose

Determine what needs to change based on user's request:

```
User request
    ↓
├─ Content change ("add a slide about X", "remove section Y")
│  → Modify slides.typ AND notes.typ → Step 3 → Step 4
│
├─ Style/formatting fix ("fix bullet spacing", "text too small")
│  → Modify affected file only → Step 4
│
├─ Structure change ("move section 2 before section 1", "split into more parts")
│  → Update OUTLINE.md → Regenerate affected sections → Step 3 → Step 4
│  → For full regeneration: Read `${CLAUDE_SKILL_DIR}/../workshop/SKILL.md` Phase 3
│
└─ Metadata fix ("wrong affiliation", "update venue name")
    → Update SOURCES.md → Fix in both files → Step 4
```

### Step 3: Apply Changes

<EXTREMELY-IMPORTANT>
## Typst Conventions — Enforced on ALL Edits

These apply to EVERY edit, no matter how small:

1. **Blank lines between ALL bullet items** (top-level AND sub-bullets) — no exceptions
2. **Sub-bullets:** two-space indent + `- ` (NEVER `--` as marker)
3. **Heading hierarchy:** `=` section / `==` subsection / `===` slide title
4. **No cetz-plot** — use `#table()` with `inset: 10pt` minimum
5. **`qr: none` must remain in config-info**
6. **Slide titles must be complete sentences**
7. **No subtitle-body echo** — `===` title must not repeat as first body line
8. **Notes must be flowing prose, not bullet recaps**
9. **Images wrapped in `#align(center)`**
10. **Smart apostrophes:** use `\u{2019}s` after `)` or `]`
11. **No hardcoded calculations** — use Typst `calc` module
12. **`#callout[]` + 3+ `#pause`** on same slide = overflow risk → split
13. **CeTZ canvas:** minimum `length: 2em`, requires `// Storytelling:` comment
14. **Dollar signs escaped:** `\$` not `$`
15. **Case names italic:** `_Case v. Party_`; em-dash `---`; en-dash for ranges `--`

**Shipping a "quick fix" with broken formatting means the presenter discovers it at the podium. That's not a fix — it's a trap you set for them.**
</EXTREMELY-IMPORTANT>

### Revision Edit Facts

- Widow positions shift with ANY content reflow — a text-only edit still requires widow detection after every compile. "Only text changed" is precisely the case the detector exists for.
- Formatting-only edits cascade into spacing and overflow violations that only the mechanical checks catch — the Step 4 verification runs regardless of how small the edit was. Declaring a small edit clean without it is an unverified claim.
- slides.typ and notes.typ are a synchronized pair: a slide content change without the matching notes update leaves the presenter reading stale notes at the podium. Editing one without checking the other is an incomplete edit, even when the user only mentioned slides.
- The theme import line and `qr: none` in config-info are load-bearing for the secreg theme — removing or "cleaning up" either breaks compilation.

### Deviation Rules (revision edits)

Unplanned issues surface mid-revision. Apply the same 4-rule system as the workshop generate phase, adapted to revision:

| Rule | Trigger | Action | Permission |
|------|---------|--------|------------|
| **R1: Bug** | Typst compile error, syntax error, broken import introduced by the edit | Fix → recompile → verify → track `[R1]` | Auto |
| **R2: Missing Critical** | Edit leaves notes out of sync, drops a `qr: none`, removes a required `#align(center)`, breaks bullet spacing | Add/restore → recompile → verify → track `[R2]` | Auto |
| **R3: Blocking** | Missing as