Session to PDF — Capture Architectural Insights into a PDF

# Session to PDF — Capture Architectural Insights into a PDF

Turn session learnings into documented architecture. Works with existing PDFs (append/edit) or creates fresh ones via the `/pdf` skill.

## Arguments

```
/session-to-pdf <mode> [pdf-context]
```

**mode** (required):
- `create` — No PDF exists. Invoke `/pdf` skill to create a fresh one from scratch.
- `append` — Add new sections to an existing PDF. Never modify existing content.
- `edit` — Modify existing sections in a PDF. Never add new sections.
- `append+edit` — Both add new sections and modify existing ones.

**pdf-context** (required for append/edit/append+edit):
- Path to the Python generator script (e.g., `generate_pdf.py`) or the PDF itself.
- If a `.py` generator script exists, always operate on that — it's the source of truth.

Examples:
- `/session-to-pdf create` — start a fresh system PDF
- `/session-to-pdf append generate_pdf.py` — add new sections only
- `/session-to-pdf edit generate_pdf.py` — modify existing sections only
- `/session-to-pdf append+edit generate_pdf.py` — full access

## Workflow

### Step 1: Validate Mode and Context

- If `create`: confirm no existing PDF/generator in the working directory. If one exists, warn and ask if the user meant `append` or `edit`.
- If `append`, `edit`, or `append+edit`: confirm the referenced file exists. Read it to understand current structure.

### Step 2: Gather Session Content

Ask the user (or infer from conversation context):
- **Topic**: What architectural insight or system evolution to document?
- **Key points**: What changed, what was learned, what's the new state?
- **Diagrams/tables**: Any flow diagrams, comparison tables, or matrices needed?

If the user provided context in the conversation (e.g., "add the channel decomposition we just discussed"), use that directly — don't ask again.

### Step 3: Execute Based on Mode

#### `create` mode
1. Invoke the `/pdf` skill
2. Build a complete PDF with title page, sections, and content
3. Use reportlab with the project's established style (see Style Reference below)
4. Generate the PDF

#### `append` mode
1. Read the generator script to find the last section number and the `doc.build(story)` line
2. Write new section(s) BEFORE the `doc.build(story)` call
3. Never modify any existing `story.append()` calls
4. Maintain consistent section numbering
5. Regenerate the PDF by running the script

#### `edit` mode
1. Read the generator script to understand current sections
2. Show the user which sections exist and ask which to modify (or infer from context)
3. Modify ONLY the specified sections
4. Never add new sections
5. Regenerate the PDF by running the script

#### `append+edit` mode
1. Read the generator script
2. Both add new sections and modify existing ones as needed
3. Show the user a summary of changes before writing: "Adding section X, modifying section Y"
4. Regenerate the PDF by running the script

### Step 4: Regenerate and Confirm

1. Run the generator script: `python3 <script_path>`
2. Confirm the PDF was generated successfully
3. Report: "Added section N: [title]" and/or "Modified section M: [title]"
4. Open the PDF for the user if possible

## Style Reference

When working with the garmin-to-code system PDF (`generate_pdf.py`), use these established styles:

- `title_style` — 24pt Helvetica-Bold, dark navy
- `h1_style` — 18pt Helvetica-Bold, section headers
- `h2_style` — 14pt Helvetica-Bold, subsection headers
- `body_style` — 11pt Helvetica, body text
- `code_style` — 9pt Courier, code blocks with gray background
- `bullet_style` — 11pt Helvetica, indented bullets
- `insight_style` — 10pt Helvetica-Oblique, yellow background callout boxes

Tables use `Table` with `TableStyle` — header row in dark background with white text, alternating row colors.

Flow diagrams use code_style with ASCII art or structured text.

## Rules

1. **Mode is mandatory.** Never assume a mode. If the user says "/session-to-pdf" with no mode, ask which mode they want.
2. **Append never edits.** In append mode, treat existing content as frozen. Add after it, never touch it.
3. **Edit never appends.** In edit mode, only modify existing sections. Don't sneak in new ones.
4. **Show before writing.** In edit and append+edit modes, summarize what you're about to change before doing it.
5. **Generator script is source of truth.** If a .py generator exists, always modify that — never edit the PDF directly.
6. **Regenerate after changes.** Always run the script to produce the updated PDF.
7. **Consistent numbering.** New sections continue the existing numbering sequence.
8. **Match existing style.** Use the same ParagraphStyles, table formats, and layout patterns already in the generator.