workshop

What this skill does

**Announce:** "I'm using workshop to create academic presentation slides and speaker notes."

## Shared Typst Constraints

Load ALL Typst conventions before any slide or notes work:

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

**You MUST have these constraints loaded before proceeding to Phase 3. No claiming you "remember" them.**

## Session Resume Detection

Check if `.planning/HANDOFF.md` exists:
1. **If found:** Read it, show status, ask: "Resume from handoff, or start fresh?"
2. **If not found:** Proceed normally

## Workflow Overview

```
Phase 1         Phase 2         Phase 3         Phase 4
gather       → structure     → generate      → verify
(sources)      (outline)       (slides+notes)   (compile+check)
    │              │               │               │
    ▼              ▼               ▼               ▼
  GATE:          GATE:           GATE:           GATE:
  Metadata       User            Both .typ       Both compile,
  extracted,     approves        files           metadata matches
  symlinks       outline         written         source paper
  created
```

**This diagram IS the authoritative spec for phase order and gating. If any prose below conflicts with it, the diagram wins.** Every gate is mandatory. Skipping a gate means the next phase operates on bad inputs.

### Iteration topology (per phase)

| Phase | Topology | Exit condition |
|-------|----------|----------------|
| Phase 1 (gather) | `one-shot` (sequential extraction + 1 read-only review subagent) | SOURCES.md reviewer returns APPROVED → SOURCES_VERIFIED.md written |
| Phase 2 (structure) | `one-shot` + decision gate (1 review subagent, then user approval) | OUTLINE reviewer APPROVED **and** user approves → OUTLINE_APPROVED.md written |
| Phase 3 (generate) | `serial` drafting → `parallel` review (workshop-verify fan-out under `/goal`, **max 3 turns**) | `overallPass=true` → SLIDES_REVIEWED.md written; else escalate after 3 turns |
| Phase 4 (verify) | `parallel` review (full workshop-verify under `/goal`, **max 3 turns**) | `overallPass=true` → VALIDATION.md written; else escalate after 3 turns |

`team` topology is not used — no phase needs concurrent role-specialized agents sharing state.

After completing each phase, IMMEDIATELY proceed to the next phase. Do not pause for user approval except where explicitly required (Phase 2: user approves outline).

**Smart Discuss:** If multiple questions arise in Phase 1 (e.g., paper path unclear, venue unknown, desired structure), batch them into a SINGLE user interaction. Do NOT ask one question, wait, ask another, wait. Present all ambiguities at once:
```
Before proceeding, I need to clarify:
1. Paper path: [what I found vs. what's unclear]
2. Venue/date: [known or unknown]
3. Structure preference: [default or ask]
Please answer all at once so we can proceed efficiently.
```

## Context Monitoring

Before starting each phase, check context availability:

| Level | Remaining Context | Action |
|-------|------------------|--------|
| Normal | >35% | Proceed normally |
| Warning | 25-35% | Complete current task, then write `.planning/HANDOFF.md` and pause |
| Critical | <=25% | Write `.planning/HANDOFF.md` immediately — no new phase |

**Phase 3 (generate) is the most context-intensive phase.** If context is at Warning level before Phase 3, write `.planning/HANDOFF.md`:
```yaml
---
workflow: workshop
phase: [current phase number]
phase_name: [current phase name]
status: context_exhaustion
last_updated: [timestamp]
---

## Current State
[What phase we're in, what's been completed in this phase]

## Completed Work
- Phase 1: [status — SOURCES.md path, inventory count]
- Phase 2: [status — OUTLINE.md path, section count]
- Phase 3: [status — slides written? notes written?]

## Remaining Work
[Specific tasks left in current phase + all subsequent phases]

## Decisions Made
[Any user decisions captured — structure proportions, venue, etc.]

## Rejected Approaches
[Approaches tried and discarded, with reasons — so the resume does not relitigate dead ends]

## Blockers
[Any unresolved blocker the next session must address before proceeding, or "none"]

## Next Action
[Specific enough to start immediately — e.g., "Write notes.typ sections 3-5 following OUTLINE.md"]
```

**Skipping handoff to "finish faster" means the last slides are garbage. The user debugs context-degraded output instead of resuming from a clean handoff. That is anti-helpful.**

## Checkpoint Types

| Phase | Gate | Type | Behavior |
|-------|------|------|----------|
| Phase 1 | Sources gathered | human-verify | Auto-advanceable |
| Phase 2 | Outline approved | decision | Pause for user input |
| Phase 3 | Slides reviewed | human-verify | Auto-advanceable (independent reviewer) |
| Phase 4 | Verified | human-verify | Auto-advanceable |

## Workflow Initialization

Create `.planning/ACTIVE_WORKFLOW.md`:
```yaml
---
workflow: workshop
phase: 1
phase_name: gather
started: [current timestamp]
project_root: [current directory]
implements: "4-phase workshop creation (gather → structure → generate → verify)"
requires: "source paper (PDF), user structure preferences"
provides: "slides.typ, notes.typ, slides.pdf, notes.pdf"
affects: "presentation/ directory"
---
```

**`.planning/ACTIVE_WORKFLOW.md` is the live state file** — update its `phase`/`phase_name` at every gate transition (Phase 1→2→3→4), not just at startup. A stale `phase: 1` after Phase 3 means a resuming session restarts from the wrong place. The per-phase gate artifacts (SOURCES_VERIFIED / OUTLINE_APPROVED / SLIDES_REVIEWED / VALIDATION) are the immutable completion records; ACTIVE_WORKFLOW.md is the moving cursor.

---

## Phase 1: Gather Sources

**Responsibility:** Collect ALL source materials and extract paper metadata.

<EXTREMELY-IMPORTANT>
## The Iron Law of Title Extraction

**NEVER hallucinate, infer, or guess the paper title, subtitle, authors, or affiliations. ALWAYS extract from the source document using look-at or Read.** This is not negotiable.

Inferring metadata from filenames is fabrication. The user got burned by hallucinated titles. Every title, every author name, every affiliation MUST come from reading the actual paper.

**Skipping extraction to "help faster" is anti-helpful — it ships wrong metadata that the user has to debug and fix. That's rework you created, not time you saved.**
</EXTREMELY-IMPORTANT>

### Title Extraction Facts

- Co-author lists change between drafts of the same paper — author names inferred from context or memory may match an older draft, so they must come from the title page of the PDF actually on disk.
- A title supplied by the user is often a paraphrase or shorthand — extract from the paper and confirm even when the user has stated the title. Putting an unverified title on the deck asserts a check that was never performed.
- A wrong title or author propagates into both slides.typ and notes.typ; deferring the fix doubles it.

### Steps

1. **Identify the source paper.** Ask the user if not obvious from context.

2. **Extract metadata** using look-at:
   ```bash
   uv run python3 "${CLAUDE_SKILL_DIR}/../look-at/scripts/look_at.py" \
       --file "/path/to/paper.pdf" \
       --goal "Extract: (1) full title, (2) subtitle if any, (3) all author names, (4) each author's affiliation/institution, (5) abstract summary in 2-3 sentences"
   ```

3. **Search for related teaching materials:**
   ```bash
   # Search ~/areas/ for topic keywords from the paper
   rg -l "keyword1|keyword2" ~/areas/
   ```

4. **Check for predecessor slides:**
   - Look for `gdrive` or `google-drive` symlinks in project directory
   - Check for existing `presentation/` directories

5. **Check Obsidian notes:**
   - Look for `notes` symlink in project directory
   - Search for topic-related notes

6. **Set up theme infrastructure:**
   ```bash
   # Create presentation directory if needed
   mkdir -p presentation/templates presentation/assets

   # Copy b