Project Deck

Project Deck Generator

Generate Beamer decks as progress logs - visual, structured snapshots of project state.

Workflow

Phase 1: Context Discovery

1. Check for previous decks in ./deck/ to understand project history
2. Read CLAUDE.md, README.md if they exist
3. Scan project folder structure (identify data files, code, results, figures)
4. Read any markdown files for context
5. Auto-detect: Is this the first deck (no previous in ./deck/) or subsequent?

Phase 2: Gap Filling

If context is insufficient, ask targeted questions using AskUserQuestion:

For first deck (no previous exists):

• What is the research question?
• What data are you using?
• What is the identification strategy / methodology?
• Who are the authors?

For subsequent decks (previous exists):

• What was accomplished since the last deck?
• Any new results or figures?
• What's next?

Phase 3: Deck Generation

Generate complete Beamer .tex file following the rhetoric principles in references/deck.md.

Output location: ./deck/project-deck-YYYYMMDD.tex (create ./deck/ if needed)

Theme: Copy assets/beamerthemeProjectDeck.sty to ./deck/ on first use.

Deck Structure

\documentclass[aspectratio=169]{beamer}
\usetheme{ProjectDeck}

\title{Project Title}
\author{Authors}
\date{\today}

Slides to include:

1. Title slide - Project name, authors, date, status indicator (e.g., "Work in Progress")

2. Research Question - What we're trying to answer and why it matters

   • Title as assertion: "We ask whether X affects Y"
   • Brief motivation (2-3 bullet points max)

3. Context/Background - Key institutional details, prior work gap

   • Title as assertion: "Prior work ignores the Z margin"

4. Data - What data, where from, sample size, key numbers

   • Title as assertion: "We use N observations from Source"

5. Identification Strategy - How we establish causality / methodology

   • Title as assertion: "We exploit variation in X"

6. Results (if available) - Tables/figures with highlighted coefficients

   • Title as assertion: "Treatment increases Y by Z%"
   • Use \alert{} or color boxes to highlight key numbers

7. Directory Structure - What files exist and what they do

   • Use verbatim or listing environment
   • Annotate key files

8. What's Done - Completed work

   • Bullet list of accomplishments

9. What's Next - Open questions, next steps, blockers

   • Prioritized list

10. Key Decisions - Rationale for choices made (for future reference)

    • "We chose X because Y"

Phase 4: Output & Validation

1. Create ./deck/ folder if it doesn't exist
2. Write ./deck/project-deck-YYYYMMDD.tex with today's date
3. Copy theme file to ./deck/ if not already present
4. Attempt compilation:
   • Run pdflatex project-deck-YYYYMMDD.tex in ./deck/
   • If pdflatex is not available or fails completely → skip to step 6
5. If compilation succeeds, validate and fix:
   • Parse the .log file for overfull/underfull hbox/vbox warnings
   • For each warning, fix the corresponding issue in the .tex file:
     • Overfull hbox: reduce content, add line breaks, adjust column widths
     • Underfull hbox: adjust spacing or content
     • Overfull vbox: split content across slides, reduce vertical spacing
   • Recompile and repeat until no warnings remain
   • Confirm clean compile to user
6. If pdflatex unavailable:
   • Inform user that .tex file is ready
   • Provide manual compilation instructions:

     cd deck
     pdflatex project-deck-YYYYMMDD.tex
     

     Or: "Upload .tex and .sty files to Overleaf"

Key Principles

Decks as Logs

Each deck is a standalone snapshot of project state on that date. The ./deck/ folder accumulates a history of these snapshots.

"Future Self" Rhetoric

From the rhetoric principles - when making a deck for your future self:

• Be more explicit than for live presentation
• Include the "why" behind choices, not just the "what"
• Write in complete thoughts where necessary
• Date everything
• Assume you'll have forgotten the context

Slide Design

• One idea per slide - if you're saying "and also," you need another slide
• Titles are assertions, not labels - "Treatment increased distance by 61 miles" not "Results"
• Lead with conclusions - state the finding, then support it
• Visual hierarchy - what's big is important
• Highlight key numbers - use \alert{} or color boxes in tables

Beauty as Functional Rhetoric

Decks must be beautiful. Beauty captures attention, and attention enables learning. "Humans want to stare at beautiful things" - the goal is stare AND learn.

Unique design:

• Must not look like a recognizable Beamer theme (Metropolis, Madrid, etc.)
• If using a base theme, it should be unrecognizable
• Custom colors, fonts, and styling

Cognitive density:

• Too much density is not beautiful
• Prefer two slides over one crowded slide
• White space is valuable - let content breathe

Quantification:

• Brain needs numbers, tables, figures
• Visualize key results with beautiful charts
• Tables should be clean, highlighted, readable

TikZ for narrative:

• Use TikZ for functional, beautiful visualizations
• Examples: timelines, process flows, geographic maps, causal diagrams
• Must service the narrative, not just decorate

Directory structure:

• Use tree-style visualization:

  project/
  ├── data/
  │   └── raw.csv
  ├── code/
  │   └── analysis.do
  └── output/
  

• Not balloon/arrow diagrams

Clean compile (when pdflatex available):

• Compile the generated .tex file automatically
• Parse log file for ALL overfull/underfull hbox/vbox warnings
• Fix each issue in the source .tex file
• Recompile until log shows no warnings
• Only present final deck to user after clean compile

Fallback (when pdflatex unavailable):

• Output .tex file without compilation
• Provide manual compilation instructions