CLAUDE.md

1# CLAUDE.MD -- Academic Project Development with Claude Code
2 
3<!-- HOW TO USE: Replace [BRACKETED PLACEHOLDERS] with your project info.
4     Customize Beamer environments and CSS classes for your theme.
5     Keep this file under ~150 lines — Claude loads it every session.
6     See the guide at docs/workflow-guide.html for full documentation. -->
7 
8**Project:** [YOUR PROJECT NAME]
9**Institution:** [YOUR INSTITUTION]
10**Branch:** main
11 
12---
13 
14## Core Principles
15 
16- **Plan first** -- enter plan mode before non-trivial tasks; save plans to `quality_reports/plans/`
17- **Verify after** -- compile/render and confirm output at the end of every task
18- **Single source of truth** -- Beamer `.tex` is authoritative; Quarto `.qmd` derives from it
19- **Quality gates** -- nothing ships below 80/100
20- **[LEARN] tags** -- when corrected, save `[LEARN:category] wrong → right` to [MEMORY.md](MEMORY.md)
21 
22Cross-session context lives in [MEMORY.md](MEMORY.md); past plans, specs, and session logs are in [quality_reports/](quality_reports/).
23 
24---
25 
26## Folder Structure
27 
28```
29[YOUR-PROJECT]/
30├── CLAUDE.MD                    # This file
31├── .claude/                     # Rules, skills, agents, hooks
32├── Bibliography_base.bib        # Centralized bibliography
33├── Figures/                     # Figures and images
34├── Preambles/header.tex         # LaTeX headers
35├── Slides/                      # Beamer .tex files
36├── Quarto/                      # RevealJS .qmd files + theme
37├── docs/                        # GitHub Pages (auto-generated)
38├── scripts/                     # Utility scripts + R code
39├── quality_reports/             # Plans, session logs, merge reports, decision records
40├── explorations/                # Research sandbox (see rules)
41├── templates/                   # Session log, quality report templates
42└── master_supporting_docs/      # Papers and existing slides
43```
44 
45---
46 
47## Commands
48 
49```bash
50# LaTeX (3-pass, XeLaTeX only)
51cd Slides && TEXINPUTS=../Preambles:$TEXINPUTS xelatex -interaction=nonstopmode file.tex
52BIBINPUTS=..:$BIBINPUTS bibtex file
53TEXINPUTS=../Preambles:$TEXINPUTS xelatex -interaction=nonstopmode file.tex
54TEXINPUTS=../Preambles:$TEXINPUTS xelatex -interaction=nonstopmode file.tex
55 
56# Deploy Quarto to GitHub Pages
57./scripts/sync_to_docs.sh LectureN
58 
59# Quality score
60python scripts/quality_score.py Quarto/file.qmd
61 
62# Palette sync (LaTeX ↔ SCSS)
63./scripts/check-palette-sync.sh
64 
65# Surface-count sync (README ↔ CLAUDE.md ↔ guide ↔ landing page)
66./scripts/check-surface-sync.sh
67```
68 
69**Palette contract:** color names in `Preambles/header.tex` must match SCSS variables in `Quarto/theme-template.scss`. See [`Preambles/README.md`](Preambles/README.md).
70 
71---
72 
73## Quality Thresholds (advisory)
74 
75| Score | Checkpoint | Meaning |
76|-------|------|---------|
77| 80 | Commit | Good enough to save |
78| 90 | PR | Ready for deployment |
79| 95 | Excellence | Aspirational |
80 
81Enforced by `/commit` (halts + asks for override) **and** — once you run `./scripts/install-hooks.sh` — by a real git pre-commit hook (`.githooks/pre-commit`) that runs the surface-sync + quality (≥80) gates on every commit. Bypass sparingly with `SKIP_QUALITY_GATE=1` or `--no-verify`.
82 
83---
84 
85## Skills Quick Reference
86 
87The full table of all skills lives in [README.md](README.md#skills-claudeskills). Most-used, by workflow:
88 
89- **Slides / teaching:** `/create-lecture` `/compile-latex` `/deploy` `/qa-quarto` `/slide-excellence` `/syllabus` `/teach-from-paper` `/scaffold-exercises`
90- **Papers / review:** `/review-paper` (`--peer`) `/seven-pass-review` `/respond-to-referees` `/verify-claims` `/proofread` `/humanize` `/submission-disclosures`
91- **Data / reproducibility:** `/data-analysis` `/did-event-study` `/simulation-study` `/audit-reproducibility` `/diagnose` `/replication-package` `/capture-environment` `/power-analysis` `/disclosure-check`
92- **Research / writing:** `/interview-me` `/lit-review` `/research-ideation` `/preregister` `/grant-proposal` `/data-management-plan`
93- **Meta / workflow:** `/commit` `/learn` `/new-skill` `/checkpoint` `/context-status` `/deep-audit` `/coauthor-brief` `/triage-inbox`
94 
95Stata (`/stata-replication`), R packages (`/r-package-check`), TikZ (`/extract-tikz`, `/new-diagram`), and more — see the README for the complete index.
96 
97---
98 
99<!-- CUSTOMIZE: Replace placeholder rows ([your-env], [.your-class]) with your own.
100     Delete the rows marked "(example — delete)" once you've added yours. -->
101 
102## Beamer Custom Environments
103 
104| Environment | Effect | Use Case |
105| --- | --- | --- |
106| `[your-env]` | [Description] | [When to use] |
107| `keybox` | Gold background box | Key points *(example — delete)* |
108| `definitionbox[Title]` | Blue-bordered titled box | Formal definitions *(example — delete)* |
109 
110## Quarto CSS Classes
111 
112| Class | Effect | Use Case |
113| --- | --- | --- |
114| `[.your-class]` | [Description] | [When to use] |
115| `.smaller` | 85% font | Dense content *(example — delete)* |
116| `.positive` | Green bold | Good annotations *(example — delete)* |
117 
118---
119 
120## Current Project State
121 
122| Lecture | Beamer | Quarto | Key Content |
123| --- | --- | --- | --- |
124| HelloWorld *(sample — delete when ready)* | `HelloWorld.tex` | `HelloWorld.qmd` | Minimal deck to verify setup |
125| 1: [Topic] | `Lecture01_Topic.tex` | `Lecture1_Topic.qmd` | [Brief description] |
126