workshop-revise

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:

If found: Read it, show status, ask: "Resume from the recorded revision state, or start fresh?"
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):

---
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

Read .planning/SOURCES.md — paper metadata (title, authors, affiliations)
Read .planning/OUTLINE.md — section structure and timing
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
Read existing slides.typ — current slide content
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

These apply to EVERY edit, no matter how small:

Blank lines between ALL bullet items (top-level AND sub-bullets) — no exceptions
Sub-bullets: two-space indent + - (NEVER -- as marker)
Heading hierarchy: = section / == subsection / === slide title
No cetz-plot — use #table() with inset: 10pt minimum
qr: none must remain in config-info
Slide titles must be complete sentences
No subtitle-body echo — === title must not repeat as first body line
Notes must be flowing prose, not bullet recaps
Images wrapped in #align(center)
Smart apostrophes: use \u{2019}s after ) or ]
No hardcoded calculations — use Typst calc module
#callout[] + 3+ #pause on same slide = overflow risk → split
CeTZ canvas: minimum length: 2em, requires // Storytelling: comment
Dollar signs escaped: \$ not $
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.

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 asset/template the edit depends on, font/package conflict surfaced by recompile	Fix blocker → verify proceeds → track `[R3]`	Auto
R4: Structural	The request implies reordering sections, changing proportions, or regenerating a whole part	STOP → present to user → on approval, re-enter workshop Phase 3 (which re-runs `workshop-verify`) → track `[R4]`	Ask user

Priority: R4 (STOP) > R1-R3 (auto) > unsure = R4. After applying changes, report: Total deviations: N auto-fixed (R1: X, R2: Y, R3: Z).

Artifact Review Gate (for content/structure changes — ultracode workflow)

For content or structural changes (NOT simple formatting fixes), the edited deck is reviewed by the workshop-verify ultracode workflow — the same per-slide fan-out + JS gate the workshop skill uses — scoped to the slides you touched:

Compile so slides.pdf reflects the edits: cd [presentation directory] && typst compile slides.typ && typst compile notes.typ

Invoke selectively (review only the changed slides; carry the rest forward):

Workflow(name="workshop-verify", args={
  "projectDir": "[absolute project root]",
  "pluginRoot": "${CLAUDE_SKILL_DIR}/../..",
  "onlyChecks": [<IDs of the slides you edited, e.g. "S4", "S5">]
})

(Omit onlyChecks to review the whole deck after a large change.)

Read the gate. If overallPass is false → /goal workshop-verify returns overallPass=true. Stop after 3 turns.; each turn fix the reported findings (main chat owns fixing — the workflow is read-only), recompile, re-invoke selectively, end the turn. If true → proceed to Step 4.

The workflow's reviewers are read-only by construction; the JS gate (overallPass) is authoritative. Do not hand-wave the gate to true — fix a finding and let the next run recompute.

Post-Subagent Enforcement

After workshop-verify returns, main chat stays on the verification side of this boundary:

Verification (main chat CAN do)	Investigation (main chat CANNOT do)
Read the workflow's `findings` / `scoreTable`	Re-read slides.typ/notes.typ to "double-check" the gate
Re-invoke the workflow (selectively, `onlyChecks`)	Override the JS gate ("the workflow was too strict")
Dispatch a fix subagent for reported `findings`	"Quick fix" an issue the workflow did not report
Proceed to Step 4 once `overallPass=true`	Declare the revision clean without a passing gate

The JS gate (overallPass) is authoritative. If you disagree with a result, fix a finding and let the next run recompute — never hand-wave the gate to true.

Topic-Change Protocol (mid-`/goal` loop)

If the user interjects with an off-topic request while the /goal workshop-verify loop is active:

Announce the pause: "Pausing the workshop-verify loop (turn N) to handle your request."
Handle the request.
Announce the resume: "Resuming the workshop-verify loop from turn N" and re-fire the /goal.

Never silently abandon the loop. An off-topic message is not permission to stop verifying.

Step 4: Verify

Compile both files:

cd [presentation directory] && typst compile slides.typ && typst compile notes.typ

Run PDF widow detection (mandatory after every compile):

DETECT_WIDOWS=$(command ls -d ~/.claude/plugins/cache/tinymist-plugin/tinymist/*/skills/typst-widow-orphan/scripts/detect_widows.py 2>/dev/null | sort -V | tail -1) && uv run python3 "$DETECT_WIDOWS" "[presentation directory]/slides.pdf"

Exit code 1 = widows found → fix → recompile → re-run
Exit code 0 = clean → proceed

Two-leg verification:

Leg 1 — Constraint checks (hard block):
```
cd [presentation directory] && uv run python3 ${CLAUDE_SKILL_DIR}/../../references/constraints/check-all.py .
```
- If any constraint fails → fix the violation → re-run (max 3 attempts)
- Hard block: ALL constraints must pass
Leg 2 — Convention review (judgment): For conventions listed by check-all.py (.md without .py), manually verify against the changed sections.
If compilation fails: Fix and recompile (max 3 attempts).
If convention violations persist after 3 fix-and-recheck cycles: Escalate to user.

Gate: Revision Verified

slides.typ compiles without errors
notes.typ compiles without errors
PDF widow detection passes (0 widows)
Overflow detection passes (no slides spill to next page)
All diagrams pass visual-verify (score >= 9.5) — if diagrams were created/modified
Source fidelity verified (claims traceable to paper) — if content was added/changed
qr: none present in config-info
No cetz-plot imports
No bullet spacing violations (top-level or sub-bullet)
No fake sub-bullets (-- as marker)
No subtitle-body echoes
No smart apostrophe issues ()'s / ]'s)
Tables have inset: 10pt minimum
Images centered with #align(center)
No hardcoded calculations (use calc module)
CeTZ canvas has length: 2em minimum + // Storytelling: comment (if used)
Dollar signs escaped (\$)
Notes are teleprompter-style prose (1-2 sentences per bullet, no fragments)
Notes sections match slide sections
Section transitions present (verbal bridges between topics)
Label-bullet spacing correct (blank line after *Label:* before bullets)
Verbatim quotes preserved from source (no paraphrasing)

Report changes to user:

Changes applied:
- [what was changed]
- slides.typ: [compiles ✓/✗]
- notes.typ: [compiles ✓/✗]
- Widow detection: [0 widows / N widows fixed]
- Overflow detection: [clean / N slides fixed]
- Visual-verify: [N diagrams verified / N/A]
- Source fidelity: [verified / N claims flagged]

Record the revision (state + review pattern)

The midpoint leaves a durable record so a later session can see what changed and so recurring preferences accumulate:

Append a revision record to .planning/LEARNINGS.md (create it if absent):

## Revision — [date]
- Request: [what the user asked to change]
- Files touched: [slides.typ / notes.typ / SOURCES.md / OUTLINE.md]
- Deviations: [R1: X, R2: Y, R3: Z]
- Gate: [overallPass / formatting-only fast path]
- Reviewed by: [how the user inspected the result — observe, don't infer]

Observe → record → offer: if the same kind of revision request recurs 3+ times across sessions (e.g. "shrink the results table" every time), offer to encode it as a default — but only after the pattern proves itself. Do NOT pre-build automation for a one-off.

Skill Dependencies

For structural changes requiring full regeneration, read and re-enter the workshop skill: Read ${CLAUDE_SKILL_DIR}/../workshop/SKILL.md Phase 3 for regeneration.