My Claude Code Setup

A Comprehensive Guide to AI-Assisted Academic Workflows: Slides, Papers, Analysis, and Beyond

Author

Pedro H. C. Sant’Anna

Published

August 24, 2026

Modified

August 24, 2026

1 Why This Workflow Exists

1.1 The Problem

If you’ve ever done serious academic work — built lecture slides, drafted a research paper, run a data analysis pipeline — you know the pain:

  • Context loss between sessions. You pick up where you left off, but Claude doesn’t remember why you chose that notation, what the instructor approved, or which bugs were fixed last time.
  • Quality is inconsistent. One slide has perfect spacing; the next overflows. One regression table has proper formatting; the next is missing standard errors. Citations compile in Overleaf but break locally.
  • Review is manual and exhausting. You proofread 140 slides by hand. You re-read your paper for the fifth time looking for the same kinds of errors. You miss a typo in an equation. A student or referee catches it.
  • No one checks the math. Grammar checkers catch “teh” but not a flipped sign in a decomposition theorem, a misspecified regression, or a broken replication.

This workflow solves all of these problems. You describe what you want — “translate Lecture 5 to Quarto,” “review my paper before submission,” or “analyze this dataset and produce publication-ready tables” — and Claude handles the rest: plans the approach, implements it, runs specialized reviewers, fixes issues, verifies quality, and presents results. Like a contractor who manages the entire job.

1.2 What Makes Claude Code Different

Claude Code runs on your computer with full access to your file system, terminal, and git. It works as a CLI tool, a VS Code extension, or through the Claude Desktop app — the same core workflow through different interfaces (permission modes and a few configuration keys genuinely differ by surface; check the permission-modes docs for yours). Here is what that enables:

Capability What It Means for You
Read & edit your files Surgical edits to .tex, .qmd, .R files in place
Run shell commands Compile LaTeX, run R scripts, render Quarto — directly
Access git history Commits, PRs, branches — all from the conversation
Persistent memory CLAUDE.md + MEMORY.md survive across sessions
Orchestrator runtime Specific skills (/qa-quarto, /review-paper --adversarial, /create-lecture, …) run a real fan-out → reduce → judge → loop-until-dry runtime internally
Multi-agent workflows 18 specialized agents for proofreading, layout, pedagogy, code review, fact-checking, AI-voice auditing, simulation + R-package review
Quality review Advisory scoring inside /commit (halt + ask to override); targets: 80 commit, 90 PR, 95 excellence
CLI/headless mode Run from scripts: claude -p "compile all lectures"
Browser bridge Continue sessions on your phone via /remote-control
TipCase Study: Econ 730 at Emory

This workflow was developed over 6+ sessions building a PhD course on Causal Panel Data. The result: 6 complete lectures (140+ slides each), with Beamer + Quarto versions, interactive Plotly charts, TikZ diagrams, and R replication scripts — all managed by the orchestrator and reviewed by a suite of specialized agents across 5 quality dimensions.

While this case study centers on slides, every component — agents, orchestrator, quality gates — works identically for research papers, data analysis, and proposals.

1.3 How It All Works Together

Before diving into setup, here is the key insight: skills hide most of the mechanics. You describe what you want in plain English, Claude figures out which skill fits, and the skill runs the right agents and checks. There is no repo-wide daemon watching for plan approvals — the work happens inside the skill you invoke.

1.3.1 What You Do vs What the Skill Does

You Do The Skill Does (once invoked)
Describe what you want Claude selects and runs the right skill
Approve plans The skill runs the orchestrator pattern internally
Review final output Hooks fire on events (edit, save, compact)
Say “commit” when ready Rules load based on files you touch

1.3.2 Example: “Fix my slides before tomorrow”

You: "Review my lecture slides and fix all issues before tomorrow's class"
     ↓
Claude invokes /slide-excellence, which internally:
  → Runs /proofread (grammar, typos, consistency)
  → Runs /visual-audit (overflow, layout, spacing)
  → Runs /pedagogy-review (narrative flow, notation clarity)
  → Synthesizes findings into prioritized fix list
  → Applies fixes (critical → major → minor)
  → Re-verifies everything compiles
  → Scores against quality gates
     ↓
You see: "Done. Fixed 12 issues. Score: 88/100. Ready to commit?"
You: "Yes"
     ↓
Claude runs /commit (only because you explicitly approved)

One skill (/slide-excellence) runs the loop. There is no repo-wide orchestrator picking sub-skills à la carte; the orchestration lives inside the invoked skill.

You: "Review my paper draft and prepare it for submission"
     ↓
Claude invokes /review-paper, which internally:
  → Runs the substantive review (argument structure, methods, citations)
  → Spawns /proofread (grammar, consistency, formatting)
  → Spawns /validate-bib (cross-reference citations)
  → Synthesizes findings into prioritized fix list
  → Applies fixes (critical → major → minor)
  → Re-verifies everything compiles
  → Scores against quality gates
     ↓
You see: "Done. Fixed 18 issues. Score: 91/100. Ready to commit?"
You: "Analyze this dataset and produce publication-ready output"
     ↓
Claude invokes /data-analysis, which internally:
  → Explores, models, builds tables and figures
  → Spawns /review-r (code quality, reproducibility)
  → Produces R script, tables, and figures
  → Scores against quality gates
     ↓
You see: "Analysis complete. 3 tables, 4 figures. Score: 85/100."

1.3.3 What You Never Touch Directly

  • Agents — Specialized reviewers called by skills, not by you
  • Hooks — Fire automatically on events (you never run them)
  • Rules — Load automatically based on file paths

1.3.4 Skills: The Only Commands You Might Type

Skills like /proofread or /compile-latex can be invoked two ways:

  1. Explicitly — You type /proofread MySlides.tex
  2. Automatically — Claude invokes them when relevant to your request

Most of the time, you just describe what you want and Claude handles the rest. Explicit skill invocation is there when you want precise control.

ImportantThe Bottom Line

You talk, Claude orchestrates. The 18 agents, 60 skills, and 37 rules exist so you don’t have to think about them. Describe your goal, approve the plan, and let the system work.

NoteYou Don’t Need All of This on Day One

This guide describes the full system — 18 agents, 60 skills, 37 rules. That is the ceiling, not the floor. Start with just CLAUDE.md and 2–3 skills (/compile-latex, /proofread, /commit). Add rules and agents as you discover what you need. The template is designed for progressive adoption: fork it, fill in the placeholders, and start working. Everything else is there when you’re ready.

NoteHow to read claims in this guide

Not every declarative sentence here has the same standing. Five kinds appear, and the wording tells you which:

  • Platform feature — Claude Code behavior, verified against official docs with an as-of date where it could drift.
  • Template implementation — what this repo’s shipped code actually does (checkable in the file named).
  • Measured in this repo — a number with a date and, where the qualification ledger covers it, a recorded row.
  • Heuristic — our practice from real projects, flagged as such (“in our use…”); not a benchmark.
  • Policy requirement — a journal’s or funder’s rule, stated with its actual strength (“required” vs “strongly encouraged”).

When a claim matters to you, the label tells you how to check it — and if you catch one drifting, that is a bug: open an issue.

2 Getting Started

You need four things: install Claude Code, fork the repo, run ./scripts/install-hooks.sh once (this wires the real pre-commit gate — until you run it, the hook file sits inert), and paste a prompt. Claude handles everything else. (The gate scripts need Python 3, which macOS and most Linux distros already ship.)

2.1 Prerequisites

Requirement What It Is How to Get It
Claude Code The AI tool that powers this workflow curl -fsSL https://claude.ai/install.sh | bash (docs)
Node.js 18+ Only for the npm install route — the recommended native installer bundles its own runtime nodejs.org
Claude account Authentication for Claude Claude Pro or Max subscription or Anthropic API key (pay per token)
git Version control (for fork/clone) Pre-installed on Mac; brew install git or git-scm.com

Optional (install only what your project uses):

Tool Required For Install
XeLaTeX LaTeX slides TeX Live or MacTeX
Quarto Web slides quarto.org/docs/get-started
R Figures & data analysis r-project.org
gh CLI PR workflow brew install gh (macOS)
NoteWhat Does This Cost?

Claude Pro or Max subscription: Includes Claude Code usage with generous limits. Check claude.ai for current pricing and tier details. Best for most academics.

API access (pay per token): For heavy users or CI/CD. Use effort levels and the multi-model strategy to control costs.

Claude Code itself is free to install (the source is public on GitHub, but under Anthropic’s commercial terms — not an open-source license). You pay only for the Claude model usage.

TipDay 1 Checklist

That’s it. Everything else — agents, hooks, rules — runs automatically in the background (the commit gate from the moment you’ve run install-hooks.sh).

“command not found: claude”: Install Claude Code first: curl -fsSL https://claude.ai/install.sh | bash (the native installer — no Node.js needed; only the npm route requires Node 18+).

Claude seems to ignore the configuration files: Make sure you ran claude from inside the project directory (not a parent folder). Claude reads .claude/ and CLAUDE.md from the current working directory.

Hooks not firing (no notifications, no reminders): Check that Python 3 is installed (python3 --version) and hook files are executable (chmod +x .claude/hooks/*).

“What does plan approval look like?” Claude presents a numbered plan and asks for your input. Say “approved”, “looks good”, or “revise step 3”. That’s it — no special commands needed.

For more, see Troubleshooting in the Appendix.

The fastest way to believe the verification layer is to watch it catch you. From a fresh clone:

./scripts/backtest.sh          # all ten gates green on a clean tree
sed -i '' 's/60 skills/61 skills/' README.md   # plant a lie (Linux: sed -i without '')
./scripts/backtest.sh          # surface-sync goes RED: claim says 61, disk says 60
git checkout -- README.md      # undo
./scripts/backtest.sh          # green again

That loop — green, seeded defect, red, restore, green — is the whole philosophy in four commands. Every gate in this repo has been through it; the results live in quality_reports/qualification/LEDGER.md.

2.2 Step 1: Fork & Clone

# Fork this repo on GitHub (click "Fork" on the repo page), then:
git clone https://github.com/YOUR_USERNAME/claude-code-my-workflow.git my-project
cd my-project

Replace YOUR_USERNAME with your GitHub username.

2.3 Step 2: Start Claude Code and Paste This Prompt

Open your terminal in the project directory, run claude, and paste the following. Fill in the bolded placeholders with your project details:

Everything in this guide works the same in any Claude Code interface. In VS Code, open the Claude Code panel (click the Claude icon in the sidebar or press Cmd+Shift+P → “Claude Code: Open”). In Claude Desktop, open your project folder and start a local session. Then paste the starter prompt below.

The guide shows terminal commands because they are the most universal way to explain things, but every skill, agent, hook, and rule works identically regardless of which interface you use.

TipStarter Prompt

I am starting to work on [PROJECT NAME] in this repo. [Describe your project in 2–3 sentences — what you’re building, who it’s for, what tools you use (e.g., LaTeX/Beamer, R, Quarto).]

I want our collaboration to be structured, precise, and rigorous — even if it takes more time. When creating visuals, everything must be polished and publication-ready. I don’t want to repeat myself, so our workflow should be smart about remembering decisions and learning from corrections.

I’ve set up the Claude Code academic workflow (forked from pedrohcgs/claude-code-my-workflow). The configuration files are already in this repo (.claude/, CLAUDE.md, templates, scripts). Please read them, understand the workflow, and then update all configuration files to fit my project — fill in placeholders in CLAUDE.md, adjust rules if needed, and propose any customizations specific to my use case.

After that, use the plan-first workflow for all non-trivial tasks. Once I approve a plan, switch to contractor mode — coordinate everything autonomously and only come back to me when there’s ambiguity or a decision to make. For our first few sessions, check in with me a bit more often so I can learn how the workflow operates.

Enter plan mode and start by adapting the workflow configuration for this project.

What this does: Claude will read CLAUDE.md and all the rules, fill in your project name, institution, Beamer environments, CSS classes, and project state table, then propose any rule adjustments for your specific use case. You approve the plan, and Claude handles the rest. From there, you just describe what you want to build.

2.4 Optional: Manual Setup

If you prefer to configure things yourself instead of letting Claude handle it:

Customize CLAUDE.md — Open CLAUDE.md and replace all [BRACKETED PLACEHOLDERS]:

  1. Project name and institution
  2. Folder structure (adjust to your layout)
  3. Current project state (your lectures/papers)
  4. Beamer environments (your custom LaTeX environments)
  5. CSS classes (your Quarto theme classes)

Create your knowledge base — Open .claude/rules/knowledge-base-template.md and fill in:

  1. Notation registry — every symbol you use, where it’s introduced, and anti-patterns
  2. Applications database — datasets, papers, and R packages you reference
  3. Design principles — what you’ve approved and what you’ve overridden

Configure permissions — Review .claude/settings.json. The template includes permissions for git, LaTeX, Quarto, R, and utility scripts. Add any additional tools you use.

Test it:

# In Claude Code, type:
/compile-latex MyFirstLecture
/proofread Slides/MyFirstLecture.tex
python scripts/quality_score.py Slides/MyFirstLecture.tex

You don’t need to fill everything in upfront. Start with 5–10 notation entries and add more as you develop lectures. The starter prompt will set up the essentials — you can always refine later.

2.5 Requirements Specification (For Complex Tasks)

For complex or ambiguous tasks, Claude may ask 3-5 clarifying questions to create a requirements specification before planning. This catches ambiguity early and reduces rework.

You: "Improve my lecture on hypothesis testing"

Claude: "Let me clarify:
1. What needs improvement (clarity, examples, pacing)?
2. Any student feedback to address?
3. Constraints (time, notation changes)?
4. Update which outputs (slides, web version, both)?"

[Creates spec with MUST/SHOULD/MAY priorities]
[You approve]
[Then enters plan mode]
You: "Analyze the survey data"

Claude: "Let me clarify:
1. What's the research question?
2. Expected output format (tables, plots, report)?
3. Any replication targets or baselines?
4. Computational constraints (runtime, memory)?"
You: "Clean up my analysis scripts"

Claude: "Let me clarify:
1. What's the pain point (speed, readability, bugs)?
2. Breaking changes okay or preserve compatibility?
3. Testing infrastructure available?
4. Refactor scope (one file, whole project)?"

After 3-5 questions, Claude creates a specification document in quality_reports/specs/ with:

  • MUST have (non-negotiable requirements)
  • SHOULD have (preferred features)
  • MAY have (optional enhancements)
  • Clarity status (CLEAR/ASSUMED/BLOCKED for each aspect)

You approve the spec, then Claude plans implementation. This reduces mid-plan pivots by 30-50%.

Template: templates/requirements-spec.md

2.6 The Adoption Ladder

You do not need all of this on day one — and adopting it all at once is the classic way to bounce off. Each level below is a stable place to live; “you may stop here” is written into every rung deliberately.

Level You use You get Stop here if…
0 — One safe task plain prompts; read the diff before accepting a feel for what Claude does to your files you mainly want an occasional assistant
1 — Repeatability a customized CLAUDE.md + 2–3 skills you actually repeat the same quality every time, without re-explaining your work is mostly writing and slides
2 — Mechanical gates install-hooks.sh, the backtest suite, compile/render checks commits that cannot silently drift from reality you work solo and trust your own review
3 — Adversarial review fresh-context reviewers, /vaccinate, review loops findings from readers who never saw your reasoning your stakes are internal (teaching, drafts)
4 — Submission credibility numeric-claim passports, /seven-pass-review, the external oracle an audit trail a referee or replicator can walk — this is the top

Climb when a level’s failure mode actually bites you, not before. The rest of this guide teaches every rung; the pattern pathways map which patterns belong to which kind of work.

3 The System in Action

With setup covered, here is what the system actually does. This section walks through the three core mechanisms that make the workflow powerful: specialized agents, adversarial QA, and automatic quality scoring.

3.1 Why Specialized Agents Beat One-Size-Fits-All

Consider proofreading a 140-slide lecture deck. You could ask Claude:

“Review these slides for grammar, layout, math correctness, code quality, and pedagogical flow.”

Claude will skim everything and catch some issues. But it will miss:

  • The equation on slide 42 where a subscript changed from \(m_t^{d=0}\) to \(m_t^0\)
  • The TikZ diagram where two labels overlap at presentation resolution
  • The R script that uses k=10 covariates but the slide says k=5

Now compare with specialized agents:

Agent Focus What It Catches
proofreader Grammar only “principle” vs “principal”
slide-auditor Layout only Text overflow on slide 37
pedagogy-reviewer Flow only Missing framing sentence before Theorem 3.1
r-reviewer Code only Missing set.seed()
domain-reviewer Substance Slide says 10,000 MC reps, code runs 1,000

Each agent reads the same file but examines a different dimension with full attention. The /slide-excellence skill runs them all in parallel.

3.2 The Adversarial Pattern: Critic + Fixer

The single most powerful pattern in this system is the adversarial QA loop:

+------------------+
|  quarto-critic   |  "I found 12 issues. 3 Critical."
|  (READ-ONLY)     |
+--------+---------+
         |
    +----v----+
    | Verdict |
    +----+----+
     /       \
APPROVED   NEEDS WORK
    |          |
  Done    +----v---------+
          | quarto-fixer |  "Fixed 12/12 issues."
          | (READ-WRITE) |
          +----+---------+
               |
          +----v----------+
          | quarto-critic |  "Re-audit: 2 remaining."
          | (Round 2)     |
          +----+----------+
               |
          ... (loop-until-dry: converge after 2 dry rounds; 5-round cap is a fallback)

Why it works: The critic can’t fix files (read-only), so it has no incentive to downplay issues. The fixer can’t approve itself (the critic re-audits). This prevents the common failure of Claude saying “looks good” about its own work.

TipReal Example

In Econ 730 Lecture 6, the critic caught that the Quarto version used \cdots (a placeholder) where the Beamer version had the full Hajek weight formula. The fixer replaced it. On re-audit, the critic found 8 more instances of missing (X) arguments on outcome models. After 4 rounds, the Quarto slides matched the Beamer source exactly.

NoteClosing the visual loop with Computer Use (research preview, Apr 2026)

The critic-fixer loop above is text-only — it compares LaTeX source to Quarto source. It can’t see the rendered slides. Anthropic’s Computer Use (research preview, Mar/Apr 2026 Week 14) lets Claude open a PDF/HTML in a real viewer, click through, and verify visually. If you want closed-loop visual QA — “does the rendered slide actually look right?” — Computer Use closes the gap.

Optional, not required: /qa-quarto and /visual-audit already catch most issues without it. Treat Computer Use as an extra rung when text-level audits aren’t enough (e.g., suspecting a TikZ render glitch that the source code looks fine for).

3.3 The Orchestrator: A Runtime, Not a Daemon

Individual agents are specialists. Skills like /slide-excellence and /qa-quarto coordinate a few agents for specific tasks. In day-to-day work, you don’t have to think about which agents to run — the right skill runs the right agents for you.

The orchestrator protocol (.claude/rules/orchestrator-protocol.md) is a real runtime, built on the Agent subagent primitive every Claude Code session has: skills fan out to forked reviewers, reduce their typed findings through a deterministic gate, judge with a post-judge hallucination guard, and loop until dry. What is not automatic is the trigger: nothing launches this loop on its own, and there is no background daemon — plan approval does NOT auto-trigger it. You invoke a skill (e.g., /create-lecture, /qa-quarto, /review-paper --adversarial) and the skill runs the runtime within its own scope. The human is the auditor of the disagreements the loop surfaces; this is explicitly not an autonomous daemon.

What’s mechanically implemented today: /commit (verifier + quality_score), /qa-quarto (critic-fixer loop), /review-paper --adversarial (critic-fixer loop), /slide-excellence (multi-agent fanout), /review-paper --peer (editor + 2 referees + cross-artifact). See Pattern 2 for the complete workflow.

3.4 Quality Review: The 80/90/95 System

The quality-gates rule (quality-gates.md) defines scoring thresholds that /commit and review skills apply. Thresholds are advisory — enforced inside specific skills and, once you run ./scripts/install-hooks.sh, by a real git pre-commit hook (.githooks/pre-commit) that runs the full backtest gate suite plus the quality (≥80) gate on every commit. Bypass it sparingly with SKIP_QUALITY_GATE=1 or --no-verify. Every substantive artifact (.tex, .qmd, .R) gets a quality score from 0 to 100:

Score Threshold Meaning Action
80+ Commit Safe to save progress git commit allowed
90+ PR Ready for deployment gh pr create encouraged
95+ Excellence Exceptional quality Aspirational target
< 80 Blocked Critical issues exist Must fix before committing

3.4.1 How Scores Are Calculated

Points are deducted for issues:

Issue Deduction Why Critical
Equation overflow -20 Math cut off = unusable
Broken citation -15 Academic integrity
Equation typo -10 Teaches wrong content
Text overflow -5 Content cut off
Label overlap -5 Diagram illegible
Notation inconsistency -3 Student confusion

3.4.2 Mandatory Verification

The verification protocol (.claude/rules/verification-protocol.md) requires that Claude compile, render, or otherwise verify every output before reporting a task as complete. Skills that implement the orchestrator pattern enforce this as Step 2: VERIFY. This means Claude cannot say “done” from within those skills without actually checking the output. One honest caveat: the mechanical quality gate is static analysis plus a best-effort render — when Quarto or XeLaTeX is unavailable or times out, it records UNVERIFIED rather than failing. Treat UNVERIFIED notes as not cleared, and rely on the verifier agent (which actually compiles) for execution-level assurance.

WarningWhat Is Actually Enforced (and how)

A skeptical reader should distinguish “Claude was told to check” from “a deterministic process ran and left evidence.” Here is the honest map:

Check Mechanism Scope Fail behavior Bypass Evidence left
Backtest (10 gates) scripts, pre-commit + CI repo-wide consistency/currency, plus the gate layer itself — ledger coverage and hook wiring (gate 9), the guard hooks re-fired against their target failures (gate 10) closed — commit blocked --no-verify gate output, CI log
Quality score ≥ 80 script, pre-commit staged .tex/.qmd/.R closed; render checks best-effort → UNVERIFIED noted, not failed SKIP_QUALITY_GATE=1 score report
Destructive-git guard PreToolUse hook git commands in-session closed — call blocked run it yourself in a terminal hook message
Numeric-claim passport script + skill claims declared per paper FAIL/STALE = must-fix at /commit named override, recorded passport.yaml rows
/verify-claims forked verifier agent citations, numbers in a draft HIGH-WARN = must-fix explicit --no-fail-closed verification report
Review agents / referees model reviewers manuscripts, slides, code advisory — reports, never auto-gates n/a report files
/humanize, proofread model auditors prose advisory, detect-only n/a report files

Two design rules behind this table: everything closed is deterministic (scripts, not model judgment), and model judgment is never a gate — it produces reports a human adjudicates. And deliberately, this template does not pile on session-time enforcement hooks beyond the git guard: each one slows every single interaction, and the cost lands on you every minute you work.

3.5 Don’t Skip Verification

In Econ 730, verification caught unverified TikZ diagrams that would have deployed with overlapping labels, broken SVGs in Quarto slides that wouldn’t display, and R scripts with missing intercept terms that produced silently wrong estimates.

NoteModel quality can regress — verification is the only durable defence

Anthropic publicly acknowledged a model-quality regression in their Apr 23, 2026 engineering post “An update on recent Claude Code quality reports”. The post identifies three contributing changes and is unusually candid about the limits of internal evals. Implication for our workflow: do not treat any given model checkpoint as a stable baseline.

The defences in this template all assume model quality drifts:

  • /verify-claims with the Chain-of-Verification forked-verifier (the verifier cannot self-confirm even if the orchestrator’s checkpoint regressed).
  • /audit-reproducibility with passport.yaml (numeric claims are anchored to specific script output values, not to the model’s recall of the values).
  • The cross-artifact review rule (a paper’s claims are checked against the code that produced them, not against the model’s intuition about whether they’re “plausible”).
  • HIGH-WARN gate-refuse on /commit (Pass 3A I) — a fabricated citation or numerical contradiction blocks the commit even if the model “feels confident.”

Anthropic’s post is also a useful reminder that running /review-paper --variance N (Pass 2C E) is the empirical answer to “should I trust this output?” — a single point estimate of model quality on a single task hides variance that the template’s adversarial-review patterns surface.

3.6 When the AI checks the math, what checks the AI?

The problem at the top of this guide was “no one checks the math.” Adding checkers answers it — and immediately raises the sequel. Every check above is itself a piece of software or a model doing a job, and neither announces when it has stopped working.

ImportantTwenty planted bugs, and a clean bill of health

Twenty bugs were deliberately planted in a working codebase, and the review agents were asked to check it again. They reported everything was fine. Recall: 0 out of 20. (A working-session incident from this template’s own development, June 2026 — it predates the qualification ledger, and it is the reason the ledger exists: gate results now come with a recorded, replayable row.)

Nothing in the output distinguished that from a genuinely clean run. The reviewers were confident, fluent, and completely wrong — and there was no way to tell from reading the report.

Think of it as a vaccine: a small, controlled dose of error that strengthens the whole system. The rule that follows is the one this template treats as non-negotiable:

An unqualified check is not weak evidence. It is none.

“It passed” is compatible with: the check never ran; it ran on a stale copy; it silently skipped what it could not reconcile; its tolerance was widened after the comparison; or it simply cannot detect the failure it was written for. The number of checks is not a measure of rigour.

3.6.1 Qualifying a check takes about ten minutes

/vaccinate does it as a protocol:

  1. Name the failure. “Catches problems” is not a class. “Detects a coefficient in the text that no longer matches its table” is.
  2. Seed it into a copy — plus at least one clean control.
  3. Run the checker blind, one variant per run, in a fresh context.
  4. Score recall and false-positive rate. A finding on the clean control counts against the checker only when it is factually wrong, not merely unwelcome.
  5. Compare against a simpler baseline. A five-agent panel that scores no better than grep -n has not earned its cost.
  6. Write a ledger row. A checker with no row in quality_reports/qualification/LEDGER.md is unqualified, and its green light means nothing.

Two things sit beside the qualification run and are easy to skip. A noise floor — how often the check fires on a control where nothing is wrong — makes a recall number interpretable rather than impressive. And a run label: pre-specified, confirmatory, or exploratory. Written before the run, the label is what stops an exploratory sweep from being reported later as a confirmation.

3.6.2 What happens when the bound is missed

A qualification bound only means something if failing it costs something. When a measured campaign misses a bound that was fixed in advance, the disposition is WITHDRAW: the thing that failed is demoted to explicit opt-in, and the bound is never widened. A bound moved after seeing the number is not a bound — it is a description of the result, and every claim that later cites it is circular. Demotion rather than deletion keeps the thing usable by someone who has read the number and accepted it, while deletion destroys the trail. The withdrawal is finished only when the failing number, the bound it missed, and the disposition are published where users read (release notes and the verdict artifact), the failing campaign is preserved as negative calibration evidence, and every adjacent surface is listed as affected or explicitly not.

A constructed illustration, not a logged incident — the mechanism is real, the numbers are chosen to make it concrete.

An R package for assay analysis ships an automatic baseline-correction routine as its default. The maintainers wrote the bound before running anything, and wrote what would count as missing it: over the preregistered holdout of 300 spike-in samples of known concentration, the nominal 95% intervals must cover the true concentration at 94% or better, counted as missed only if the measurement falls below that by more than two standard errors, and confirmed by one pre-committed re-run on fresh seeds at the same budget before any disposition fires. The campaign runs. Measured coverage: 267 of 300 = 89.0%, with a standard error of 1.8 percentage points — not a near miss, and not noise. The confirming re-run misses too.

The tempting move is to widen. 89% is usable, the shortfall is concentrated in the noisiest plates, and the bound was, after all, chosen by the same people now looking at the result. The maintainers instead demote the routine: still available, still documented, now baseline = "auto" rather than the default. NEWS for that release carries the number and the bound it missed, verbatim, next to the disposition. Both campaigns are kept in the repository. What the preregistration forbids is the other order — re-rolling a failed campaign after the disposition until some draw clears the bound. Two downstream functions inherited the default; both are listed, one affected, one explicitly not and why.

What made this a real bound was not its value. It was that missing it had a consequence written down in advance.

NoteThis is not hypothetical — it caught a live bug in this repo

While building v2.5 we ran the repo’s own consistency gates against a seeded defect: the sentence This template has NN skills. — with a count that did not match disk — was added to README.md.

Every gate then in the suite stayed green. The count patterns are deliberately compound — they require several categories on one line — so that they do not fire on ordinary prose like “start with 2–3 skills”. A count carrying only a template verb fell straight through the gap.

The gate had been green and wrong, and only a seeded defect could tell the difference. It was fixed and then re-qualified in both directions: 3 of 3 seeded drifts caught, 0 of 3 false alarms on legitimate prose.

3.6.3 Where the verification discipline is written down

These references carry it, loaded on demand rather than living in every session’s context:

Reference Read when
verification-ladder.md you want the seven rungs end to end — qualify the checker, deterministic gates, the four-layer artifact ladder, independence, analytic verification, the ledger, the external oracle
external-oracle-process.md you are sending a paper or proof to an external frontier model and need the prompt contract, the coverage manifest, and the adjudication protocol
provenance-and-ground-truth.md you are porting, replicating, or upgrading, and “the numbers match” is about to license a claim
release-engineering.md you are shipping software rather than results — a package, an .ado, a versioned replication artifact — and need the message and silent-resolution censuses, a frozen feature matrix for a port, hash-claimed inherited tests, and downstream pinning by commit

And one command runs the mechanical half of all of it:

./scripts/backtest.sh    # ten gates: consistency, skill integrity, currency, links, spec, staleness,
                         # hygiene, derived counts, ledger coverage, hook battery

The final pair check the checking layer rather than the content. Ledger coverage reads the qualification ledger and the set of checks that actually run, and requires them to agree in both directions: a registered check with no ledger row fails the build, a row naming a checker that no longer exists fails the build, and a row parked under Not yet qualified warns — visible debt rather than silence. It also verifies that every hook registered in .claude/settings.json points at a file that exists, is invocable, and is tracked in git. The hook battery then fires each active guard hook with synthetic events and requires it to still go red on the failure it was written for, alongside clean controls that must stay green. Gate 9 proves a hook is wired; gate 10 proves it still acts.

Findings themselves are machine-checked rather than described: reviewers emit a JSON array validated against finding-schema.json by scripts/validate-findings.py. Every finding must cite the rule it violates (a finding citing no rule is an opinion) and give a failing case — a concrete configuration that breaks the claim, not “this could be clearer”. Finding ids are deterministic, so deduplication across review rounds is exact rather than fuzzy.

3.6.4 The five credibility questions

The most common way AI-assisted empirical work goes wrong is not a wrong number. It is evidence for one question being read as evidence for another.

Question Answered by Does not establish
Reproducibility — does the code run and produce the reported numbers? /audit-reproducibility, the passport that the estimator is right
Implementation fidelity — does the code implement the estimator it claims? /differential-audit against a pinned reference that the estimator performs well
Statistical performance — does it behave in finite samples? /simulation-study, coverage against truth that the measure is valid
Measurement validity — does the variable capture the construct? domain review, data documentation that the causal claim holds
Identification — is the causal claim warranted? design, /challenge, falsification anything about the code

Evidence for one never clears another. A green reproducibility check tells you the arithmetic is faithful to the script. It says nothing about whether the script identifies anything. When an agent reports “all checks pass”, it is almost always speaking about rung one and being heard about rung five.

3.6.5 And review does not substitute for robustness

In a controlled study (Gao & Xiao 2026, “Nonstandard Errors in AI Agents”, arXiv:2603.16744 — a preprint studying six market-quality hypotheses on NYSE TAQ data, so evidence from one empirical-finance setting, not all of social science), 150 autonomous agents were given the same data and the same questions. Effect-size interquartile ranges reached about 10.7 %/yr, and the spread concentrated in discrete measure-choice forks — dollar versus share volume, trade-level versus Amihud — not in estimation noise. Within a measure family, agents agreed to about 0.25 %/yr.

Two results from that study are load-bearing for how this template is designed:

  • AI peer review left the spread essentially unchanged. Review catches errors. It does not reduce analytical-choice variance. A clean referee report is not robustness.
  • Exposure to exemplar papers collapsed the spread by 80–99 % — convergence by imitation, not by correctness. Herding is not agreement.

That is why /challenge exists and why it is a separate rung: the spread has to be measured, not reviewed away.

3.6.6 Submission-readiness: stacking the verification lenses

For a paper headed to a journal, four orthogonal lenses run together — each catches a different class of failure:

Lens Skill What it catches Block-/commit on failure?
Grammar / overflow /proofread typos, search-and-replace artifacts, overfull \hbox, citation-format inconsistency No (advisory)
AI-voice tells (v1.9.0) /humanize boilerplate transitions (“Moreover”, “It is important to note”), AI-cliché lexicon (“delve”, “navigate the complexities”), hedging stacking, sycophancy No (advisory; author edits manually)
Factual claims /verify-claims fabricated citations, numerical contradictions, directional contradictions Must-fix — resolve HIGH-WARN before committing (v1.9.0)
Numeric provenance /audit-reproducibility manuscript value ≠ script output value within tolerance Must-fix via passport.yaml status (v1.9.0)

These are complementary, not redundant. A paper can pass /proofread (clean grammar) and fail /humanize (the prose reads as AI-drafted). It can pass /humanize (your own voice) and fail /verify-claims (citation fabricated). It can pass /verify-claims (citations real) and fail /audit-reproducibility (Table 2 doesn’t match the code). Run all four before submission; reach for /review-paper --variance N for the simulated peer-review verdict on top.

/humanize design choice: detect-only, no --rewrite mode. Auto-rewriting AI tells degrades prose quality (cross-vendor research finding) and introduces new tells. The author reads the report and edits — that manual step is the price of preserving voice. If the report flags 8+ HIGH-severity tells per 1000 words, rewrite the affected paragraph from scratch rather than patching tell-by-tell.

3.7 Creating Your Own Domain Reviewer

The template includes domain-reviewer.md — a skeleton for building a substance reviewer specific to your field. The class of defect it exists to catch: a slide asserts a stronger property than the cited paper actually proves — a subtle but critical distinction that no grammar or layout checker would flag.

3.7.1 The 5-Lens Framework

Every domain can benefit from these five review lenses:

Lens What It Checks Example (Economics) Example (Political Science) Example (Physics)
Assumption Audit Are stated assumptions sufficient? Is overlap required for ATT? Is ignorability defensible given the observed covariates? Is the adiabatic approximation valid here?
Derivation Check Does the math check out? Do decomposition terms sum? Do conjoint AMCEs identify under Hainmueller–Hopkins–Yamamoto assumptions? Do the units balance?
Citation Fidelity Do slides match cited papers? Is the theorem from the right paper? Is the manipulation-check threshold cited from the original validation study? Is the experimental setup correctly described?
Code-Theory Alignment Does code implement the formula? R script matches the slide equation? cjoint/survey::svyglm weights match the design? Simulation parameters match theory?
Logic Chain Does the reasoning flow? Can a PhD student follow backwards? Does the causal claim survive the standard counterfactual challenge? Are prerequisites established?

The template ships two concrete domain-reviewer customizations in .claude/agents/domain-reviewer.md: an econometrics example (assumptions, identification, R/Stata code-theory alignment) and a political-science example (ignorability, conjoint AMCEs, cjoint/survey package defaults). Both follow the 5-lens structure; either is a viable starting point for your own field.

To customize, open .claude/agents/domain-reviewer.md and fill in:

  1. Your domain’s common assumption types
  2. Typical derivation patterns to verify
  3. Key papers and their correct attributions
  4. Code-theory alignment checks for your tools
  5. Logic chain requirements for your audience

4 The Building Blocks

Understanding the configuration layers helps you customize the workflow and debug when things go wrong. Claude Code’s power comes from five configuration layers that work together — think of them as the operating system for your academic project.

4.1 CLAUDE.md — Your Project’s Constitution

CLAUDE.md is the single most important file. Claude reads it at the start of every session. But here is the critical insight: Claude reliably follows about 100–150 custom instructions. Your system prompt already uses ~50, leaving ~100–150 for your project. CLAUDE.md and always-on rules share this budget.

This means CLAUDE.md should be a slim constitution — short directives and pointers, not comprehensive documentation. Aim for ~120 lines:

  • Core principles — 4–5 bullets (plan-first, verify-after, quality gates, LEARN tags)
  • Folder structure — where everything lives
  • Commands — compilation, deployment, key tools
  • Customization tables — Beamer environments, CSS classes
  • Current state — what’s done, what’s in progress
  • Skill quick reference — table of available slash commands

Move everything else into .claude/rules/ files (with path-scoping so they only load when relevant).

# CLAUDE.MD --- My Course Development

**Project:** Econ 730 --- Causal Panel Data
**Institution:** Emory University

## Core Principles
1. **Plan-first** — enter plan mode before non-trivial tasks
2. **Verify-after** — compile/render and check before reporting done
3. **Quality gates** — 80 to commit, 90 for PR, 95 for excellence
4. **LEARN tags** — persist corrections in MEMORY.md
5. **Single source of truth** — Beamer is authoritative; derive, don't duplicate

## Quick Reference
| Command | What It Does |
|---------|-------------|
| `/compile-latex [file]` | 3-pass XeLaTeX compilation |
| `/proofread [file]` | Grammar/typo review |
| `/deploy [Lecture]` | Render and deploy to GitHub Pages |
ImportantKeep It Lean

CLAUDE.md loads every session. Keep it lean — official guidance suggests staying under ~200 lines, and adherence degrades as it grows (overloaded files lose rules silently). Put detailed standards in path-scoped rules (.claude/rules/) instead — they only load when Claude works on matching files, so they don’t compete for attention.

4.2 Rules — Domain Knowledge That Auto-Loads

Rules are markdown files in .claude/rules/ that Claude loads automatically. They encode your project’s standards. The key design principle is path-scoping: rules with a paths: YAML frontmatter only load when Claude works on matching files.

Always-on rules (no paths: frontmatter) load every session. Keep these few and focused:

.claude/rules/
├── plan-first-workflow.md       # ~83 lines — plan before you build
├── orchestrator-protocol.md     # ~119 lines — review-fix runtime (fan-out → reduce → judge → loop-until-dry)
├── session-logging.md           # ~23 lines — three logging triggers
├── prompt-shaping.md            # ~32 lines — shape informal asks (ambient; replaces /prompt)
├── progress-reports.md          # ~92 lines — GitHub as memory: issues, reports, MEMORY.md
├── repo-hygiene.md              # ~74 lines — scratch must not become main
└── meta-governance.md           # ~277 lines — template vs working project

Path-scoped rules load only when relevant:

.claude/rules/
├── r-code-conventions.md        # paths: ["**/*.R"] — R standards
├── quality-gates.md             # paths: ["*.tex", "*.qmd", "*.R"] — scoring
├── verification-protocol.md     # paths: ["*.tex", "*.qmd", "docs/"] — verify before done
├── replication-protocol.md      # paths: ["scripts/**/*.R"] — replicate first
├── exploration-folder-protocol.md  # paths: ["explorations/**"] — sandbox rules
├── orchestrator-research.md     # paths: ["scripts/**/*.R", "explorations/**"] — simple loop
└── ...29 path-scoped rules total

The always-on rules are deliberately compact — together they fit well within the budget Claude reads reliably each session. meta-governance is a reference document for the template’s dual nature (working project vs. public template) and loads passively. Path-scoped rules add rich, domain-specific guidance exactly when Claude needs it.

Sync vs. translate: The beamer-quarto-sync rule handles incremental edits — fix a typo in Beamer, same fix goes to Quarto. The /translate-to-quarto skill is for full initial translation of a new lecture. Translate once, sync thereafter.

Why rules matter: Without them, Claude will use generic defaults. With them, Claude follows your standards consistently across sessions.

4.2.1 Example: Path-Scoped R Code Conventions Rule

---
paths:
  - "**/*.R"
  - "Figures/**/*.R"
  - "scripts/**/*.R"
---
# R Code Standards

## Reproducibility
- set.seed() called ONCE at top (YYYYMMDD format)
- All packages loaded at top via library()
- All paths relative to repository root

## Visual Identity
primary_blue  <- "#012169"
primary_gold  <- "#f2a900"

The paths: block means this rule only loads when Claude reads or edits an .R file. When Claude works on a .tex file, this rule doesn’t consume any of the instruction budget.

4.3 Constitutional Governance (Optional)

As your project grows, some decisions become non-negotiable (to maintain quality, reproducibility, or collaboration standards). Others remain flexible.

The templates/constitutional-governance.md template helps you distinguish between:

  • Immutable principles (Articles I-V): Non-negotiable rules that ensure consistency
  • User preferences: Flexible patterns that can vary by context

4.3.1 Example Articles You Might Define

  • Article I: Primary Artifact — Which file is authoritative (e.g., .tex vs .qmd, .Rmd vs .html, notebook vs script)
  • Article II: Plan-First Threshold — When to enter plan mode (e.g., >3 files, >30 min, multi-step workflows)
  • Article III: Quality Gate — Minimum score to commit (e.g., 80/100, all tests passing)
  • Article IV: Verification Standard — What must pass before commit (e.g., compile, tests, render)
  • Article V: File Organization — Where different file types live (prevents scattering)

The template includes examples for LaTeX, R, Python, Jupyter, and multi-language workflows.

Use constitutional governance after you’ve established 3-7 recurring patterns that you want to enforce consistently. Don’t create it on day one — let patterns emerge first, then codify them. Skip it for solo projects with evolving standards, or when you prefer case-by-case decisions.

Template: templates/constitutional-governance.md

4.4 Skills — Reusable Slash Commands

Skills are multi-step workflows invoked with /command. Each skill lives in .claude/skills/[name]/SKILL.md:

---
name: compile-latex
description: Compile LaTeX with 3-pass XeLaTeX + bibtex
argument-hint: "[filename without .tex extension]"
---

# Steps:
1. cd to Slides/
2. Run xelatex pass 1
3. Run bibtex
4. Run xelatex pass 2
5. Run xelatex pass 3
6. Check for errors
7. Report results

Skills you get in the template:

Skill Purpose When to Use
/compile-latex Build PDF from .tex After any Beamer edit
/deploy Render Quarto + sync to docs/ Before pushing to GitHub Pages
/proofread Grammar and consistency check Before every commit
/qa-quarto Adversarial Quarto QA After translating Beamer to Quarto
/slide-excellence Full multi-agent review Before major milestones
/create-lecture New lecture from scratch Starting a new topic
/commit Stage, commit, PR, merge After any completed task
NoteBuilt-In Skills

Claude Code ships with built-in skills beyond this template’s 60 (as of Aug 2026): /batch orchestrates parallel refactoring across your codebase (using git worktrees for isolation), /simplify reviews recent changes for simplification opportunities, and /debug helps troubleshoot sessions. These complement the academic skills above.

4.5 Agents — Specialized Reviewers

Agents are the real power of this system. Each agent is an expert in one dimension of quality:

.claude/agents/
+-- proofreader.md        # Grammar, typos, consistency
+-- slide-auditor.md      # Visual layout, overflow, spacing
+-- pedagogy-reviewer.md  # Narrative arc, notation clarity, pacing
+-- r-reviewer.md         # R code quality and reproducibility
+-- tikz-reviewer.md      # TikZ diagram visual quality
+-- quarto-critic.md      # Adversarial Quarto vs Beamer comparison
+-- quarto-fixer.md       # Applies critic's fixes
+-- beamer-translator.md  # Beamer -> Quarto translation
+-- verifier.md           # Task completion verification
+-- domain-reviewer.md    # YOUR domain-specific substance review

4.5.1 Agent Anatomy

Each agent file has YAML frontmatter + detailed instructions:

---
name: proofreader
description: Reviews slides for grammar, typos, and consistency
---

# Proofreader Agent

## Role
You are an expert academic proofreader reviewing lecture slides.

## What to Check
1. Grammar and spelling errors
2. Inconsistent notation
3. Missing or broken citations
4. Content overflow (text exceeding slide bounds)

## Report Format
Save findings to: quality_reports/[FILENAME]_report.md

## Severity Levels
- **Critical:** Math errors, broken citations
- **Major:** Grammar errors, overflow
- **Minor:** Style inconsistencies
NoteWhy Specialized Agents?

A single Claude prompt trying to check grammar, layout, math, and code simultaneously will do a mediocre job at all of them. Specialized agents focus on one dimension and do it thoroughly. The /slide-excellence skill runs them all in parallel, then synthesizes results.

Claude Code also offers experimental Agent Teams — multiple independent sessions that coordinate, share findings, and challenge each other’s approaches. This is a research preview feature (as of Aug 2026); the orchestrator + subagent pattern described here is more mature for academic workflows.

4.5.2 Multi-Model Strategy: Cost vs. Quality

NoteCurrent Anthropic lineup (re-verified 2026-08-21; expiry-gated via the model SSoT)

Fable 5 (claude-fable-5, alias fable) is the most capable Claude Code model — opt-in via /model fable or the best alias, built for tasks larger than a single sitting; it investigates before acting and verifies its own work more often than smaller models. It is not the default on any account type and may bill to usage credits. Opus is the high-judgment tier and what this template routes referees, editors, and verifiers to. Sonnet is the workhorse mid-tier; Haiku is the fast/mechanical tier.

Alias resolution is provider-dependent, and point versions move faster than any guide can. The single source of truth is model-versions.md, which carries the current versions, the per-provider alias table, and a verified_on date with an expiry — scripts/check-staleness.py fails the build when that expiry passes, and scripts/check-model-versions.sh catches any superseded version presented as current. Do not hard-code a point version here.

Retired (2026-06-15): Sonnet 4 and the original Opus 4 are gone. If your environment still pins one (ANTHROPIC_MODEL env, hard-coded model strings), requests fail — migrate to the current tiers in the SSoT.

Not all agents need the same model. Each agent file has a model: field in its YAML frontmatter. In v2.0 all 18 agents are pinned to an explicit model + effort tier (no longer inherit), following the 70/20/10 routing pattern below. You can re-tune any agent to optimize cost:

Task Type Recommended Model Why Examples
Adversarial comparison / high-judgment review model: opus Needs deep understanding of both artifacts at once quarto-critic, tikz-reviewer, editor
Fast, constrained work model: sonnet Speed matters more than depth beamer-translator, r-reviewer, quarto-fixer, proofreader, slide-auditor
Mechanical default model: haiku Bounded, fast work promote-memory-council

The principle: Use Opus for tasks that require holding two large documents in mind simultaneously (adversarial comparison, refereeing). Use Sonnet for tasks with clear, bounded scope (fix these 12 issues, check this R script). Use Haiku for mechanical work. In v2.0 every agent is pinned explicitly rather than inheriting — see agent-fleet.md for the full fleet + tiers.

To change an agent’s model, edit its YAML frontmatter:

---
name: quarto-critic
model: opus   # pinned per agent-fleet.md (v2.0: no agent inherits)
---
TipCost Savings

If you configure model-per-agent, a typical Beamer-to-Quarto translation runs the critic on Opus (2–4 rounds) while the fixer runs on Sonnet (same rounds). In our use this saves roughly 40–60% compared to running everything on Opus, without observed quality loss on the fixing step — a routing heuristic from our own projects, not a benchmarked guarantee.

4.5.3 Advanced Agent Configuration

Beyond model selection, agent definitions support several configuration fields:

Field Purpose Example
model Force a specific model haiku, sonnet, opus
maxTurns Limit agent iterations 10 (prevents runaway loops)
isolation Run in a git worktree worktree (see Pattern 12)
effort Override reasoning effort high
permissionMode Restrict permissions plan (read-only agent)
tools Whitelist specific tools ["Read", "Grep", "Glob"]
disallowedTools Blacklist specific tools ["Write", "Edit"]
skills Make specific skills available ["compile-latex"]
background Run concurrently true

Example: a read-only proofreader that can’t edit files:

---
name: proofreader
model: sonnet
maxTurns: 15
tools: ["Read", "Grep", "Glob"]
---

Use maxTurns to prevent review agents from looping indefinitely, and tools to enforce read-only behavior for agents that should only produce reports.

4.5.4 Cost-Conscious Composition: Caching, Routing, and Diagnostics

Cost is invisible until you look at the monthly invoice. Three levers, in order of impact:

1. Prompt caching. Anthropic’s prompt cache lets repeated prefix tokens (system prompt, CLAUDE.md, large context blobs) hit a cached path at a fraction of the input price. Two things forkers should know:

  • The default TTL dropped from 60 min to 5 min in early 2026. A long /review-paper --peer pipeline that took 12 minutes between turns now starts the second turn with a cold cache. For long pipelines on API / Bedrock / Vertex / Foundry plans, the opt-in ENABLE_PROMPT_CACHING_1H environment variable restores 1-hour TTL. On Claude Pro / Max subscriptions, Claude Code requests the 1-hour TTL automatically at no extra cost.
  • cache_miss_reason (Anthropic public beta, 2026-05-13) is now exposed on Messages requests. Use it to diagnose why a long-running pipeline isn’t getting cache hits (most often: a hook injected a timestamp that broke the prefix; or system-prompt drift between turns).

The Apr 2026 TTL change cost analysis estimates a 30–60% effective cost increase for long-running pipelines that don’t opt into the 1-hour TTL. Worth a Saturday hour to instrument your most expensive skill (/review-paper --peer is typically the worst offender).

2. Per-agent model routing. The Multi-Model Strategy table above lists the principle; the 70/20/10 pattern is the operational form:

Model Share of subagent calls Use for
Haiku 4.5 ~70% Mechanical work: TikZ extraction, citation reformatting, bib validation, proofread fixes, simple file lookups
Sonnet tier ~20% Review and critique: r-reviewer, slide-auditor, proofreader, quarto-fixer
Opus tier ~10% High-judgment work: editor, domain-referee, methods-referee, claim-verifier, manuscript review

Set per-agent via model: in .claude/agents/<name>.md frontmatter. Typical savings vs. all-Opus in our use: 50–80% on routed skills, with no quality loss observed on the mechanical tier (heuristic, not a benchmark). The community-converged ratio is documented in Augment Code’s routing data and aligns with Aider’s architect/editor split; we cite Anthropic’s Apr 8 2026 “Decoupling brain from hands” as the primary-source endorsement of the pattern.

3. Effort budgeting. The Effort Levels section earlier covered the low | medium | high | xhigh | max ladder. the current Opus tier defaults to high — and its high does roughly what 4.7’s xhigh did, for fewer tokens. So: let high be the default; drop to medium/low to save cost on mechanical work; reach for xhigh only for extended exploration (deep search, big refactors, the hardest /review-paper runs); ultracode (xhigh + dynamic workflows) for repo-scale autonomous tasks.

TipMonitoring: /cost and /usage
  • /cost (Apr 2026 Week 15) — current session breakdown by model and cache hit-rate.
  • /usage (Apr 2026 Week 16) — month-to-date totals + per-plan-tier remaining quota.

Run /cost after any /review-paper --peer pipeline. If your cache hit-rate is under 60% for the second/third turn, you’re almost certainly being bitten by the 5-min TTL.

WarningAgent SDK credit-pool split — 2026-06-15

Starting 2026-06-15, claude -p headless subprocess calls (used by /coarse-review and any script that calls Claude Code in -p mode) draw from a separate monthly Agent SDK credit pool, decoupled from interactive credits. If /coarse-review starts failing after the cutover with credit-exhaustion errors even though your interactive session works, the Agent SDK pool is what’s empty. See TROUBLESHOOTING.md for the migration details.

4.6 Settings — Permissions and Hooks

.claude/settings.json controls what Claude is allowed to do. Here is a simplified excerpt — the template includes additional permission entries for git, GitHub CLI, PDF tools, and more:

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(xelatex *)",
      "Bash(Rscript *)",
      "Bash(quarto render *)",
      "Bash(./scripts/sync_to_docs.sh *)"
    ]
  },
  "hooks": {
    "Stop": [
      {
        "hooks": [{
          "type": "command",
          "command": "python3 \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/log-reminder.py",
          "timeout": 10
        }]
      }
    ]
  }
}

Permission modes. Claude Code has five permission modes that control how much autonomy Claude gets:

Mode Internal Name Behavior When to Use
Normal default Asks before risky actions Day-to-day work — approve each edit
Auto-accept edits acceptEdits Auto-approves file edits Trusted batch operations (rename across 20 files)
Don’t ask dontAsk Auto-denies tools unless pre-approved in allowlist Restricted environments where only allowlisted tools run
Plan plan Read-only — no edits allowed Exploring code, reviewing before acting
Auto auto Classifier-gated; everything runs unless flagged risky. Since 2026-08-14 this is the default starting mode for new interactive terminal and VS Code sessions on Pro, Max, and Team, and it needs no opt-in flag on Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry Long autonomous tasks with safety net — the recommended mode for trusted repos when bypass is too permissive
Bypass bypassPermissions Skips all permission prompts and safety checks — including writes to protected paths (.git, .vscode, .idea, .husky, .claude). Anthropic’s docs advise reserving it for isolated environments CI/CD, headless scripts, and — eyes open — trusted-repo daily driving: nothing prompts, so pair it with plan-first and the shipped git-guardrails hook — which narrows the common accidents rather than replacing the prompt you turned off

Set via CLI flag (claude --permission-mode plan), the /config command, or permissions.defaultMode in settings.json.

4.6.1 The Six-Layer Permission Stack

Permission mode is not resolved from a single file. Claude Code honors six layers, with later layers overriding earlier ones:

# Layer Location Key
1 VSCode user ~/Library/Application Support/Code/User/settings.json (macOS), ~/.config/Code/User/settings.json (Linux), %APPDATA%/Code/User/settings.json (Windows) claudeCode.initialPermissionMode
2 VSCode workspace <repo>/.vscode/settings.json claudeCode.initialPermissionMode
3 CLI user ~/.claude/settings.json permissions.defaultMode
4 CLI project <repo>/.claude/settings.json permissions.defaultMode
5 CLI project-local (gitignored) <repo>/.claude/settings.local.json permissions.defaultMode
6 In-session runtime (ephemeral) toggled via Shift+Tab / /permission-mode

Layer 6 is authoritative and catches most users off-guard. initialPermissionMode only fires at session start — if you (or Shift+Tab) change modes mid-session, every file-level layer is ignored until the session ends.

4.6.2 Troubleshooting: Prompts Fire Despite bypassPermissions

This is the single most common source of confusion. Work through the checklist in order:

  1. Look at the status line at the top of the Claude Code panel. With this repo’s statusLine configured, it prints [BYPASS], [PLAN], [AUTO-EDIT], or [PROMPT] for the four standard modes. Any other mode Claude Code reports (e.g., dontAsk) is shown as a bracketed raw name like [dontAsk]. If it doesn’t say [BYPASS], you have an in-session override — press Shift+Tab to cycle modes until you land on bypass.
  2. Run /permission-check to see every layer’s value, the resolved merged state, and any drift (e.g., project says bypass but project-local says default).
  3. Check for stale sessions. If settings changed recently but the session predates the change, it still runs under the old mode. Reload the window (Cmd+Shift+P → “Developer: Reload Window”) and start a new session.
  4. Check deny lists. A match in any layer’s deny blocks the tool regardless of allow entries elsewhere.
  5. VSCode vs CLI split. If the VSCode layers say bypass but no CLI layer does, a terminal-launched Claude Code will still prompt. Align them.

4.6.4 Session Management

A handful of recent Mar–Apr 2026 commands cut friction in the actual editing loop. Worth knowing before you reach for them in a panic:

Command / shortcut What it does When to reach for it
/btw <question> Asks a side question whose answer appears in a dismissible overlay — never enters conversation history Quick “what does X do?” / “is this version compatible?” questions you don’t want bloating context
Esc Esc or /rewind Opens the rewind menu — restore conversation, code, or both to a prior checkpoint Tried something risky, want to undo cleanly without git reset (checkpoints are NOT git — only Claude-made changes are tracked)
/clear Resets the conversation context entirely Switching to an unrelated task; long session with cluttered context
/compact <instruction> Guided summarization of the current conversation “Compact, focusing on the API changes” — selective preservation before continuing on the same task
Ctrl+G (in plan mode) Opens the in-progress plan file in $EDITOR for direct editing before approval You want to surgically tweak the plan without typing instructions back to Claude
claude --continue / claude --resume Resume the most recent conversation (--continue) or pick from recent (--resume); rename with /rename Picking up a multi-day project — treat sessions like branches
/checkpoint <slug> Writes a structured state snapshot to quality_reports/checkpoints/ (this template, not Anthropic’s) Before stopping or handing off — companion to the narrative session log
/goal <verifiable condition> Sets an end-state condition; Claude keeps working across turns until a fast model confirms it holds (May 2026 Week 20, v2.1.139) “All R scripts pass without errors”, “Figure 3 renders to PDF without overflow” — pair with /commit quality gates for verified-end-state runs

Three patterns that compose well:

  • Side question without polluting context: /btw why does Quarto need ::: for callouts? — get the answer, dismiss, keep working.
  • Long session, want to switch tasks: /checkpoint current-work then /clear then start the new task. Resume the first with claude --resume.
  • Plan mid-edit: During plan mode, Ctrl+G to edit the plan file directly — faster than dictating revisions back to Claude.
WarningPlans Directory

By default, Claude saves plans to a global directory (~/.claude/plans/), not your project. To keep plans with your project (and in git), add this to .claude/settings.json:

{
  "plansDirectory": "quality_reports/plans"
}

The Stop hook runs a fast Python script after every response. No LLM call, no latency. It checks whether the session log is current and reminds Claude to update it if not. Behavioral rules like verification and Beamer-Quarto sync are enforced via auto-loaded rules in .claude/rules/, which is the right tool for nuanced judgment that Claude can evaluate in-context.

4.7 Effort Levels — Cost vs. Thoroughness

Claude Code lets you control how deeply it reasons about each task. Higher effort means more “thinking tokens” and better results — but higher cost. On the current Opus tier the default is high — its high reasoning now delivers what 4.7’s xhigh did, so you rarely need to bump up (see Cost-Conscious Composition).

Level Thinking Budget Academic Use Case Relative Cost
low Minimal Quick formatting, grep, file renames $
medium Standard Mechanical work; drop here from high to save cost \[ | | `high` | ~10k tokens | Complex derivations, paper reviews (**Opus-tier default**) | \]$
xhigh ~20k tokens Extended exploration / hardest runs; the current Opus tier defaults to high, so reserve xhigh for genuinely hard work (introduced Apr 2026 Week 16) $\[$ | | `max` / ultrathink | ~32k tokens | Deep proofs, multi-step analysis | \]$$$

How to set effort:

  • Per-session: Type /effort high (the current Opus default) or /effort xhigh for the hardest runs. Typing /effort on its own opens an interactive slider (Apr 2026 Week 16).
  • Per-skill: Add effort: high to skill frontmatter (see Skill Frontmatter Reference)
  • Keyboard toggle: Option+T (Mac) / Alt+T (Windows/Linux) toggles extended thinking
  • In prompts: Include “ultrathink” in your prompt to enable extended thinking for that turn. Note: phrases like “think hard” are treated as regular instructions and do not allocate extra thinking tokens
  • Environment variable: CLAUDE_CODE_EFFORT_LEVEL=high for all sessions
  • Hooks can read it: As of Apr 2026 Week 19, hook input includes effort.level and $CLAUDE_EFFORT is set in Bash subprocess env — useful for skipping expensive verification on low-effort runs
TipComposing Effort with Model Choice

Effort levels compose with model selection for fine-grained cost control. For example, Haiku + high effort costs less than Opus + low effort but may produce comparable results for bounded tasks like formatting. Use Opus + max only for tasks that genuinely require deep multi-step reasoning — complex proofs, intricate data pipeline debugging, or comprehensive paper critique.

4.8 Memory — Cross-Session Persistence

Claude Code has an auto-memory system at ~/.claude/projects/[project]/memory/MEMORY.md. This file persists across sessions and is loaded into every conversation.

Use it for: - Key project facts that never change - Corrections you don’t want repeated ([LEARN:tag] format) - Current plan status

# Auto Memory

## Key Facts
- Project uses XeLaTeX, not pdflatex
- Bibliography file: Bibliography_base.bib

## Corrections Log
- [LEARN:r-code] Package X drops obs silently when covariate is missing
- [LEARN:citation] Post-LASSO is Belloni (2013), NOT Belloni (2014)
- [LEARN:workflow] Every Beamer edit must auto-sync to Quarto

4.8.0.1 Two-tier memory architecture (MEMORY.md vs native auto memory)

The template splits memory into two tiers (see meta-governance.md):

  • MEMORY.md (committed, ≤ 200 lines) — generic learnings that help all forkers: workflow patterns, design principles, documentation standards, quality thresholds that transfer across domains.
  • Native auto memory (~/.claude/projects/<project>/memory/, machine-local, never committed) — machine-specific and user-specific learnings: TeX install quirks, file paths, personal effort preferences, tool-version workarounds.

When a fork user does git clone, they get the generic MEMORY.md. Their own auto memory builds up locally as they work.

4.8.0.2 /promote-memory — graduating learnings (v1.9.0)

The two-tier split poses one question: who decides which [LEARN] entries graduate from native auto memory to MEMORY.md? The answer is a five-critic council.

/promote-memory [filter] runs five critics in parallel, each reviewing one dimension:

  1. Generality — would a non-econ forker benefit?
  2. Staleness — does this contradict current code (grep the referenced files)?
  3. Redundancy — is it already in MEMORY.md, CLAUDE.md, or a rule?
  4. Evidence — does it cite the originating incident / file / why?
  5. Format — does it follow [LEARN:category] wrong → right?

Majority (3+ of 5 YES) recommends promotion; the user approves the final move. Critics run in isolated forked contexts — they cannot see each other’s votes — so dimensions are reviewed independently, no groupthink. Critics use Haiku (per model-routing.md) since the review is mechanical-ish.

When to run: monthly as memory-maintenance, before sharing a fork, after a paper or course cycle ships, or wired as a /loop task.

4.8.1 Plans — Compression-Resistant Task Memory

While MEMORY.md stores long-lived project facts, plans store task-specific strategy. Every non-trivial plan is saved to quality_reports/plans/ with a timestamp. This means:

  • Plans survive auto-compression (they are on disk, not just in context)
  • Plans survive session boundaries (readable in any future session)
  • Plans create an audit trail of design decisions

See Pattern 1 in Workflow Patterns for the full protocol.

4.8.2 Session Logs — Why-Not-Just-What History (auto-written)

Git commits record what changed, but not why. Session logs fill this gap. Claude writes to quality_reports/session_logs/ at three points: right after plan approval, incrementally during implementation (as decisions happen), and at session end. This means the log can capture reasoning as it happens, before auto-compression can discard it — when the incremental-logging habit is followed.

Because relying on instructions alone is fragile (Claude forgets during long sessions), a Stop hook (.claude/hooks/log-reminder.py) fires after every response. In v2.0 it no longer merely nags — it auto-writes a session-log scaffold (changed files, active plan, timestamp) for every meaningful change-set, so a log always exists. The why — decisions, rejected alternatives — is appended incrementally per the session-logging rule; the hook guarantees the file, not the reasoning.

New sessions can read these logs to understand not just the current state of the project, but the reasoning behind it. See Pattern 1 in Workflow Patterns for the full protocol.

4.8.3 How It All Fits Together

With CLAUDE.md, MEMORY.md, plans, and session logs, the system has four distinct memory layers. Here is what each one does and when it matters:

Layer File Survives Compression? Updated When Purpose
Project context CLAUDE.md Yes (on disk) Rarely Project rules, folder structure, commands
Corrections MEMORY.md Yes (on disk) On [LEARN] tag Prevent repeating past mistakes
Task strategy quality_reports/plans/ Yes (on disk) Once per task Plan survives planning-to-implementation handoff
Decision reasoning quality_reports/session_logs/ Yes (on disk) Incrementally Record why decisions were made
Conversation Claude’s context window No (compressed) Every response Current working memory

The first four layers are your safety net. Anything written to disk survives indefinitely. The conversation context is ephemeral — auto-compression will eventually discard details. The workflow’s design ensures that anything worth keeping is written to one of the four persistent layers before compression can erase it.

4.8.4 Hooks — Automated Enforcement

The session log reminder above is one example of a broader pattern: using hooks to enforce rules that Claude might otherwise forget during long sessions. Rules live in context and can be compressed away. Hooks live in .claude/settings.json and fire every time, regardless of context state.

The template includes 8 hooks for logging, notifications, context survival, git safety, and protection of the configuration that defines the gates (plus a real git pre-commit hook, .githooks/pre-commit, installed via ./scripts/install-hooks.sh):

Hook Event What It Does
Session log reminder Stop Reminds about session logs after every response
Desktop notification Notification Desktop alert when Claude needs attention (macOS/Linux)
Context state capture PreCompact Saves plan state before auto-compaction
Context restoration SessionStart[compact|resume] Restores context after compaction or resume
Context monitor PostToolUse[Bash|Agent|Task] Progressive warnings at 40%/55%/65%/80%/90% context
Git guardrails PreToolUse[Bash] Blocks destructive git (reset --hard, clean -f, push --force, add -A), and refuses a merge, rebase, or pull while the tree is dirty — including chains that would clean it first
Claim reconcile PostToolUse[Write|Edit|MultiEdit] Flags stale numeric claims when analysis scripts change
Root-of-trust guard PreToolUse[Bash] A tripwire, not a lock: denies silent shell writes into .claude/settings*.json, .claude/hooks/, and .githooks/ — the files that define every other gate — and applies the destructive-git deny list to bash -c / env -S payloads. Edit/Write, a branch switch, or a bug in the hook can still replace them

Two of these deserve a note, because both encode a lesson rather than a preference. Git guardrails refuses a merge, rebase, or pull while the working tree is dirty: the operation either aborts mid-way or quietly folds uncommitted work into the result, and neither outcome announces itself. Stash with a label first, or set ALLOW_DIRTY_MERGE=1 if you mean it. --abort and --continue are exempt outright — they are how you get out of a dirty in-progress operation. --autostash is not: it is allowed only when git status --porcelain reports no untracked entry, because git stash does not stash untracked files, so an autostash over a ?? line leaves that line exactly where it was.

It refuses even when the same command line would have cleaned the tree first — git stash push -m wip && git merge is denied, and you run the two steps separately instead. That looks pedantic until you see what the alternative cost. The check originally tried to predict, from the text of a chained command, whether the tree would still be dirty by the time the merge ran. Round after round of adversarial review found one more thing the prediction got wrong — stash flags, then stash subcommands, then intervening segments, then output redirection, then command substitution, and finally the plain fact that git stash does not stash untracked files at all, so even a correctly-parsed “this cleans the tree” was sometimes false. The rule now reads the tree as it actually is and refuses.

The reading has to be earned, though, and that is rule 0: standalone or nothing. A PreToolUse hook decides before bash runs the line, so a reading taken now says nothing about the tree the op will actually start from — printf '\n# note\n' >> analysis.R && git merge main reads clean at hook time and executes dirty. So an identified merge, rebase, or pull reaches the tree reading only as a standalone simple command. A second shell segment, a pipeline, a redirection, a command or process substitution in its arguments, a grouping, a cd, or a variable assignment on the same line is denied outright, without the tree being read at all. That closes every write-then-op ordering by construction instead of by enumeration, and it also denies ordinary trailing conveniences — git pull | tail -5, git pull > log 2>&1, git merge x && npm install. Deleting the prediction took the whole class of defect with it — at the cost of one extra tool call, with its own hook cycle and agent round trip.

The hook did not end up smaller, and the reason is the useful part of the lesson. What replaced the prediction was parsing — working out which part of a command line is a git invocation, and whether a flag is really a flag or just a word inside a message. That is a harder-looking job that is nonetheless finite and checkable: shell grammar can be read correctly, and when the reading is wrong a test says so. Predicting what a command will do to the working tree has no such floor. Trading an unbounded problem for a bounded one is worth paying code for; the mistake was ever being on the unbounded side.

What it still cannot see is written down rather than implied away. Its docstring enumerates the forms it has been probed against — a git merge carried inside bash -c, an interpreter, an alias, a script, or a Makefile; and a write by another process in the milliseconds between the reading and git starting — and then says plainly that the list reports where the parser has been probed, not where it is complete. One form sits under that catch-all rather than on the list, and is worth naming because it is easy to assume covered: an op hidden inside a command substitution — echo $(git merge main), x=$(git merge main), the backtick spelling — never reaches the parser as a segment at all, so the hook is silent on it where the bare spelling denies (measured against the shipped hook on a dirty fixture, 2026-08-23). Rule 0 denies a substitution in an identified op’s arguments; one that carries the op is never identified, which is a different thing. A cd into a different repository was on the docstring’s list until rule 0 arrived and denied it, along with every other multi-segment form — which is also what closes the case of the same command line doing the dirtying. The second hook — the file is root-of-trust-guard.py, and the honest description is a silent-shell-write tripwire — exists because the settings file and the hook directory decide whether any other gate runs at all: a shell one-liner can disable every gate in the repo in a single redirect, and nothing in the transcript looks unusual afterwards. Reads pass, and Edit / Write stay allowed so a change to a gate arrives as a reviewable diff rather than an invisible overwrite; the hatch is ALLOW_ROOT_OF_TRUST_WRITE=1.

Because that hook already unwraps bash -c and env -S payloads to find writes hidden inside them, it now hands the unwrapped payload to git-guardrails’ own destructive-git deny list as well — imported, not copied, so the two hooks cannot drift apart on what counts as destructive. That closes a gap the two of them had left open between each other: bash -c 'git reset --hard' and bash -c 'git clean -fdx' named no protected path for the first hook to test and looked like one opaque word to the second, so neither denied them, while the unwrapped spellings had been denied all along. The clean-tree check is not shared, so bash -c 'git merge main' on a dirty tree is still seen by neither.

Now the part the name gets wrong. A repo-local, mutable, fail-open textual scan is not a root of trust, and the file name is a filename rather than a claim. The scan reads the command line as text, so it catches the direct forms — redirects, tee, cp/mv/rm, in-place edits — and the payload carriers it knows about, including behind common wrappers. It cannot see inside an interpreter it does not read (python3 -c, perl -e), a path piped into a deleter, or an execution form nobody has enumerated yet. More to the point, the files it watches stay replaceable through four channels the template deliberately allows, none of which trips it: an Edit / Write / MultiEdit on those same files — including one that deletes the hook’s own registration from .claude/settings.json; an ordinary git switch onto a branch whose tree carries different hooks; a clean merge or pull that imports the same change; and a bug in the hook itself, which fails open and becomes a no-op.

So state its value exactly: it changes the channel a modification arrives through — a reviewable diff instead of an invisible overwrite — and nothing more. It is not a lock, and in a fresh fork there may be no other control behind it: a visible diff is retrospective visibility rather than authorisation, choosing bypassPermissions is a posture rather than a control, and a machine-wide hook in ~/.claude/hooks/ is optional and lives outside the repository. If you want a real one, it has to sit outside the worktree — a non-empty deny list in the permission system, or a machine-level hook — and it has to cover Edit/Write and branch transitions too. Note also what the audit trail is not: the transcript records that a loss happened, and git reflog / ORIG_HEAD recover a moved commit pointer, but neither holds the bytes of an uncommitted edit, an untracked file, or an ignored one — which is exactly what reset --hard and clean -fdx destroy. A guard whose advertised coverage exceeds its actual coverage is worse than none, because you stop looking.

There is a further lesson here, and it is the one most likely to transfer to whatever you are guarding. A path can be written many ways that all reach the same file — a glob, a different case on a case-insensitive filesystem, a quote or a backslash sitting inside the name, a variable, a command substitution. Successive review rounds each turned up another one. That is simply what a text scan over shell syntax is: useful for the direct forms, and not a closed set. So the practical advice is not to give up on the guard — it still costs an accident a denial — but to be honest in the docstring about which forms it has actually been tested against, and to say that there are others. If you need a guarantee rather than a speed bump, the mechanism has to stop being a text scan: a real deny rule in the permission system, or a wrapper the operation cannot go around.

One distinction inside that is worth keeping, because it changes what a fix can even do. Most of those forms are just text — the information is in the command line, so a scanner can be taught to read it, and another round of parsing is a reasonable answer. A symbolic link is not: it is a fact about the filesystem, and reading the command line cannot recover it. A link named anything at all, pointing at the directory you protect, is invisible to a text scan while the shell writes straight through it. That one is written down as out of reach rather than chased — and when you build your own guard, the same question tells you which gaps are worth more parsing and which mean the mechanism is the wrong shape for the guarantee you wanted.

Verification and Beamer-Quarto sync are enforced via auto-loaded rules, which are the right tool for nuanced judgment. Hooks are reserved for enforcement that must survive context compression.

A constructed illustration, not a logged incident — the failure mode is real, the scenario is invented to make it concrete.

Picture a lab’s shared template that registers a guard hook to refuse writes to its instrument-calibration files. Someone reorganises the hooks directory and updates settings.json to match, but types .claude/hooks/calibration_guard.py where the file on disk is calibration-guard.py.

What is lost is the guarding, and the symptom that replaces it is never legible as a hook is misconfigured. Which symptom you get depends on how the hook was registered, and both are bad in their own way. This template registers all but one of its hooks as python3 <path>; a path Python cannot open exits 2, and exit 2 from a PreToolUse hook means BLOCK (the handler table below states that contract). So a typo on one of the guards would deny every matching call, and the reason handed back is an interpreter error about a missing file — the loudest possible failure, and still not one a reader parses as a settings typo. Registered as a bare path instead, the missing file exits 127 (126 if it exists but is not executable): a non-blocking error that scrolls past while the session continues, tools are allowed, and the only thing that changed is the one thing nobody was watching. That is the lab’s case. The guard is in the settings file, in the README, and in the onboarding doc. It is not in the process. Weeks later a calibration file is overwritten by an agent that the hook had been written to stop.

Gate 9, ledger coverage, is the check that would have caught it: it opens every hook registered in .claude/settings.json and requires the file to exist, be invocable, and be tracked in git. Nothing else in the repo reads the settings file against the disk, so a hook can be wired to nothing while every gate in the suite stays green — the failure has no detector of its own. That is what Gate 9 is worth: a mistyped path fails the build the moment it is committed, instead of waiting for the day the guard was supposed to fire.

But a wired hook is not yet a working hook. A guard can keep its path, keep firing, and stop denying — an over-broad exception, a regex loosened during a debugging session, an early return allow left in. Gate 10, the hook battery, drives each active guard with synthetic events and requires it to still go red on the failure it was written for, and to stay green on the clean controls. 234 cases, and it finishes in seconds.

Hook handler types. The examples above use command hooks (shell scripts), but Claude Code supports five handler types:

Type How It Works Best For
command Runs a shell script. Exit 0 = allow, exit 2 = block (PreToolUse only) File protection, state capture, notifications
prompt Injects text into Claude’s conversation — no script needed Soft reminders: “Check that equations compile before saving”
http POSTs to an external endpoint CI/CD integration, logging to external services
agent Spawns a subagent that can use tools to verify conditions Complex validation requiring multi-step checks
mcp_tool Invokes a tool on a connected MCP server Zotero / Stata / database integrations without shell or HTTP wrappers

PreToolUse input modification. PreToolUse hooks can now modify tool inputs, not just block or allow. Your hook script can return modified JSON to rewrite parameters before the tool executes — for example, auto-correcting file paths or enforcing naming conventions.

TipHook Design Principle

Use command hooks for fast, mechanical checks (file exists? counter threshold?). Use prompt hooks for soft guidance that doesn’t need a script. Use rules for nuanced judgment (did Claude verify correctly?). Avoid prompt hooks that fire on high-frequency events — the injected text adds up in context.

4.8.5 Context Survival System (Advanced)

When context compaction happens, Claude loses working memory. The context survival system ensures you can recover seamlessly.

4.8.5.1 How It Works

Two hooks work together to preserve and restore state:

Session running → context fills up → PreCompact fires
                                           ↓
                                    pre-compact.py saves:
                                    • Active plan path
                                    • Current task
                                    • Recent decisions
                                           ↓
                                    Auto-compaction happens
                                           ↓
                                    SessionStart(compact|resume) fires
                                           ↓
                                    post-compact-restore.py:
                                    • Reads saved state
                                    • Prints context summary
                                    • Claude knows where it left off

4.8.5.2 What Gets Saved

State Location Purpose
Plan path Session cache So Claude can read the plan file
Current task Session cache First unchecked - [ ] item
Recent decisions Session cache Last 3 decision-like entries from session log
Compaction note Session log Timestamp marker for reference

4.8.5.3 Context Monitoring

The context-monitor.py hook tracks approximate context usage and provides progressive warnings:

Threshold Message Purpose
40%, 55%, 65% Suggest /learn Capture non-obvious discoveries before compaction
80% Info message Auto-compact approaching, no rush
90% Caution Complete current task with full quality

Use /context-status to check current session health at any time.

Note: the monitor uses tool call count as a proxy for context usage, so warnings may appear earlier or later than actual compaction.

4.8.5.4 Recovery After Compaction

If compaction happens mid-task, Claude will automatically see:

  1. Restoration message — what plan was active, what task was in progress
  2. Recovery actions — read the plan, check git status, continue

You can also manually point Claude to the right context:

“We just had compaction. Read quality_reports/plans/2026-02-06_translate-lecture5.md and continue from where we left off.”

4.8.5.5 Distil before compaction: /compress-session (v1.9.0)

Auto-compaction is lossy — it keeps recent turns and drops earlier ones, with no preservation of what was decided mid-session. For long pipelines (long debug sessions, multi-decision refactors, end-of-working-day handoffs), /compress-session is the distil-not-truncate alternative: structured note with Active state, Decisions made, Files touched, Open questions, Next actions, and explicitly Discarded as noise (failed hypotheses that should NOT carry forward).

/compress-session and /checkpoint are companions, not substitutes:

/checkpoint /compress-session
When Natural stop-points (end of day, model switch, collaborator handoff) Forced compression (long pipeline, accumulated noise, approaching auto-compact)
What’s preserved Active plan, decisions, file pointers, next actions Same, plus explicit “discarded as noise” line
Output quality_reports/checkpoints/ quality_reports/session_logs/YYYY-MM-DD_compression_<slug>.md
[LEARN] proposals Optional Always proposes (distillation is when lessons surface)

The “Discarded as noise” section is the novel contribution: failed hypotheses and dead-end debugging paths are listed explicitly so they do NOT ghost-haunt future sessions. This defends against Drew Breunig’s “context poisoning” failure mode — hallucinated or wrong content from early turns getting quoted by later turns.

Note2026 Feature Coverage

Now that you understand the building blocks, here’s what’s new: Claude Code has added effort levels for cost control, expanded hook events, skill frontmatter fields for fine-grained skill configuration, permission modes for controlling Claude’s autonomy, advanced agent configuration, plugins, /batch for parallel refactoring, and headless CLI mode. Each is covered in its respective section above.

5 Workflow Patterns

The first two patterns are meta-patterns — they govern how every task flows. Learn these first, then the specific workflows make more sense.

Choose your path. Nineteen patterns is a reference shelf, not a syllabus. Four worked sequences cover the common kinds of academic work — each starts from Pattern 1 (plan first) and ends at a verification rung:

Your work Follow, in order
A lecture 1 → 3 (new lecture) → 4 (Beamer→Quarto) → 6 (multi-agent review) → 14 (deck rhetoric)
A paper / R&R 1 → 2 (contractor mode) → 15 (adversarial audits) → 16 (preregistration & submission) → 18 (external oracle)
Data & replication 1 → 5 (replication-first) → 10 (exploration) → 13 (compliance) → 19 (challenge the result)
A simulation study 1 → 5 → 9 (parallel agents) → 17 (vaccinate the checks) → 19

Patterns 7–8, 11–12 are power-ups you add to any path once the base sequence feels natural.

5.1 Pattern 1: Plan-First Development

The plan-first pattern ensures that non-trivial tasks begin with thinking, not typing.

5.1.1 Why Planning Matters

The most common failure mode in AI-assisted development is not bad code — it is solving the wrong problem, or solving the right problem in a fragile order. Plan-first development forces an explicit design step before any file is touched. Plans are saved to quality_reports/plans/ on disk, so they survive context compaction.

Without a plan:

  • Claude starts editing immediately, discovers a dependency on slide 3 that changes the approach, and has to undo work
  • Context compression discards the reasoning behind a design choice, and Claude makes a contradictory decision later
  • The user and Claude have different mental models of what “done” looks like

With a plan:

  • The approach is agreed upon before any edits happen
  • The plan is saved to disk, so it survives compression and session boundaries
  • Implementation has a checklist to follow, reducing drift

5.1.2 The Protocol

Non-trivial task arrives
  |
  +-- Step 1: Claude enters plan mode (automatic, or say "plan this first")
  +-- Step 2: Draft plan (approach, files, verification)
  +-- Step 3: Save to quality_reports/plans/YYYY-MM-DD_description.md
  +-- Step 4: Present plan to user
  +-- Step 5: User approves (or revises)
  +-- Step 6: Save initial session log (capture context while fresh)
  +-- Step 7: You invoke the implementing skill; the orchestrator runs inside it (see Pattern 2)
  +-- Step 8: Update session log + plan status to COMPLETED

5.1.3 Context Preservation

Plans are saved to disk specifically so they survive context compression. The rule: avoid /clear — prefer auto-compression. Use /clear only when context is genuinely polluted.

For details on how the system automatically preserves and restores context during compaction, see Context Survival System in the Building Blocks section.

5.1.4 Session Logging

Session logs (quality_reports/session_logs/YYYY-MM-DD_description.md) are a running record of why things happened. They have three distinct behaviors, each solving a different problem:

After plan approval — create the log with the goal, plan summary, and rationale for the chosen approach (including rejected alternatives). This captures decisions while context is richest. If you wait, auto-compression may discard the reasoning.

During implementation — append to the log as you work. Every time a design decision is made, a problem is discovered, or the approach deviates from the plan, write a 1-3 line entry immediately. This is the most important behavior: context gets compressed as the session progresses, and decisions that live only in the conversation will be lost.

At session end — add a final section with what was accomplished, open questions, and unresolved issues.

Git records what; session logs record why. A commit message says “Update Lecture 5 TikZ diagrams.” A session log says “Redesigned the TWFE decomposition diagram because the DA challenge revealed students couldn’t trace the path from weights to bias. Considered a table format but chose a flow diagram because it shows directionality.”

Incremental logging is the key. A 4-hour session that only logs at the start and end loses everything in the middle. Appending decisions as they happen means auto-compression can never erase them — they are already on disk.

Claude writes all three log entries automatically — no need to ask.

For multi-project academics, start each week by asking Claude to read all session logs from the past week and synthesize a status report with priorities and open questions. The session log infrastructure already captures what you need — the weekly review is just a synthesis prompt: “Read all session logs from this week. Summarize: what was accomplished, what’s blocked, what should I prioritize next?”

5.2 Pattern 2: Contractor Mode (Orchestrator)

Once a plan is approved and you invoke the implementing skill, the orchestrator takes over inside that skill. It is the natural continuation of Pattern 1: the plan says what, the orchestrator handles how — autonomously within the skill’s scope (plan approval alone triggers nothing; see “A Runtime, Not a Daemon”).

5.2.1 The Mental Model

Think of the orchestrator as a general contractor. You are the client. You describe what you want. The plan-first protocol is the blueprint phase. Once you approve the blueprint, the contractor takes over: hires the right specialists (agents), inspects their work (verification), sends them back to fix issues (review-fix loop), and only calls you when the job passes inspection (quality gates).

5.2.2 The Loop

User: "Translate Lecture 5 to Quarto"
  |
  |-- Plan-first (Pattern 1): draft plan, save to disk, get approval
  |
  |-- User: "Approved"
  |
  +-- Orchestrator activates (inside the invoked skill):
        |
        Step 1: IMPLEMENT
        |  Execute plan steps (create QMD, translate content, etc.)
        |
        Step 2: VERIFY
        |  Run verifier: render Quarto, check HTML output
        |  If render fails -> fix -> re-render
        |
        Step 3: REVIEW (agents selected by file type)
        |  +--- proofreader ------+
        |  +--- slide-auditor ----+  (parallel)
        |  +--- pedagogy-reviewer +
        |  +--- quarto-critic ----+  (needs others first)
        |
        Step 4: FIX
        |  Apply fixes: Critical -> Major -> Minor
        |  For quarto-critic issues: invoke quarto-fixer
        |
        Step 5: RE-VERIFY
        |  Render again, confirm fixes are clean
        |
        Step 6: SCORE
        |  Apply quality-gates rubric
        |
        +-- Converged? (a round adds 0 new Critical/Major)
              YES -> Present summary to user
              NO  -> Loop to Step 3 in fresh context
                     (loop-until-dry; 5-round cap is a fallback only)

5.2.3 Agent Selection

The orchestrator selects agents based on which files were touched:

Files Modified Agents Selected
.tex only proofreader + slide-auditor + pedagogy-reviewer
.qmd only proofreader + slide-auditor + pedagogy-reviewer
.qmd with matching .tex Above + quarto-critic (parity check)
.R scripts r-reviewer
TikZ diagrams present tikz-reviewer
Domain content domain-reviewer (if configured)
Multiple formats verifier for cross-format parity

Agents that are independent of each other run in parallel. The quarto-critic runs after other agents because it may need their context.

5.2.4 “Just Do It” Mode

Sometimes you do not want to approve the final result — you just want it done:

“Translate Lecture 5 to Quarto. Just do it.”

In this mode, the orchestrator still runs the full fan-out → reduce → judge → loop-until-dry runtime (quality is non-negotiable) and skips the final approval pause for the current skill. It does not auto-commit: “just do it” is never commit authorization — commits require an explicit /commit or unambiguous request. It still presents the summary so you can see what was done.

5.2.5 Relationship to Existing Skills

The orchestrator does NOT replace skills. It coordinates them:

  • /qa-quarto remains available as a standalone adversarial QA loop
  • /slide-excellence remains available for comprehensive multi-agent review
  • /create-lecture remains available as a guided creation workflow

The difference: when you invoke a skill directly, it runs its specific workflow. The orchestrator runtime lives inside each skill — there is no repo-wide orchestrator that activates on its own or chains skills together. A skill is always user- or skill-initiated; nothing fires the runtime unattended.

Natural-language task → Claude picks a skill: “Translate Lecture 5 to Quarto” → Claude invokes /translate-to-quarto, and that skill runs the orchestrator pattern (translate → verify → review → fix → score) internally.

Explicit skill call: /qa-quarto Lecture5 — you specifically want the adversarial critic-fixer loop, nothing else.

Both are valid. The natural-language path is the “I trust you, pick the skill” path. Explicit skill calls are the “I know exactly which loop I want” path. Either way, the orchestrator pattern runs inside the invoked skill — there is no auto-trigger outside a skill.

5.3 Pattern 3: Creating a New Lecture

The /create-lecture skill guides you through a structured lecture creation workflow — from gathering source material to deploying polished slides:

/create-lecture
  |
  +-- Phase 1: Gather materials (papers, outlines)
  +-- Phase 2: Design slide structure
  +-- Phase 3: Draft Beamer slides
  +-- Phase 4: Generate R figures
  +-- Phase 5: Polish and verify
  |     +-- /slide-excellence (domain + visual + pedagogy)
  |     +-- /proofread (grammar/typos)
  |     +-- /visual-audit (layout)
  +-- Phase 6: Deploy
        +-- /translate-to-quarto (optional)
        +-- /deploy
TipTikZ diagrams: start from the gallery, not from scratch

Writing TikZ from a blank page reliably produces label-over-arrow collisions because the compiler doesn’t warn about them. The template ships three reinforcing layers:

  • templates/tikz-snippets/ — 8 production-ready standalone diagrams (DAG basic, DAG mediation, two-period DiD, event study, timeline, regression scatter, 3-step flowchart, supply-demand). Each embeds the prevention rules (explicit node dimensions, coordinate map, directional edge labels) by construction.
  • Rules tikz-prevention.md + tikz-measurement.md — Upstream authoring rules (P1–P6) and the six-pass collision protocol with formulas (Bézier depth, character widths, 0.4 cm boundary clearance). Adapted from Scott Cunningham’s MixtapeTools.
  • /new-diagram skill — Scaffolds from the gallery, runs the P3/P4 grep pre-check before compiling, invokes tikz-reviewer with measurement citations, loops until APPROVED.

For existing diagrams in a Beamer deck, /extract-tikz runs the same pre-check plus the SVG pipeline.

5.4 Pattern 4: Translating Beamer to Quarto

Translation preserves all content while adapting format, converting TikZ to SVG and ggplot to interactive Plotly charts:

/translate-to-quarto Lecture5_Topic.tex
  |
  +-- Phase 1-3: Environment mapping + content translation
  +-- Phase 4-5: Figure conversion (TikZ -> SVG)
  +-- Phase 6-7: Interactive charts (ggplot -> plotly)
  +-- Phase 8-9: Render + verify
  +-- Phase 10-11: /qa-quarto adversarial QA
        +-- Critic: finds issues
        +-- Fixer: applies fixes
        +-- Critic: re-audits
        +-- ... (loop-until-dry: converge after 2 dry rounds; 5-round cap is a fallback)

5.5 Pattern 5: Replication-First Coding

When working with papers that have replication packages:

Phase 1: Inventory original code
  +-- Record "gold standard" numbers (Table X, Column Y = Z.ZZ)

Phase 2: Translate (e.g., Stata -> R)
  +-- Match original specification EXACTLY (same covariates, same clustering)

Phase 3: Verify match
  +-- Compare every target: paper value vs. our value
  +-- Tolerance: per-claim, typed — |x−y| ≤ atol + rtol·|reported|, with units and
  |   display rounding declared per claim (see replication-protocol.md; a bare
  |   absolute threshold is meaningless across probabilities, dollars, and logs)
  +-- If mismatch: STOP. Investigate before proceeding.

Phase 4: Only then extend
  +-- New estimators, new specifications, course-specific figures
ImportantNever Skip Replication

In one course, we discovered that a widely-used R package silently produced incorrect estimates due to a subtle specification issue. This bug was caught 3 times in different scripts. Without the replication-first protocol, these wrong numbers would have been taught to PhD students.

Source-language coverage: The pattern is language-agnostic. The template ships /data-analysis for R-first projects and /stata-replication (v1.9.0) for Stata-first projects (mirrors /data-analysis exactly; same numbered-pipeline shape, different language; executes via the stata-mcp MCP server). Python-first projects follow the same convention with the path scripts/python/_outputs/. For Stata users, stata-code-conventions.md (v1.9.0) codifies the header (version 18, clear all, set seed/set sortseed), numbered pipeline (00–99), esttab for \input{} tables, clustering discipline (reghdfe), balance via iebaltab, and AEA Data Editor compliance.

NoteClaims provenance via passport.yaml (v1.9.0)

Replication-first verifies the current state. A separate question: how do we keep manuscript and code in sync over the lifetime of a paper, especially during R&R?

The answer is a per-paper quality_reports/passports/<paper-slug>.yaml that records, for each numeric claim in the manuscript, the script + line + output that produced it. Schema includes appears_in, tolerance, last_verified_on, status (PASS / FAIL / EXPLAINED / STALE / UNVERIFIED). /audit-reproducibility reads and rewrites the passport in place; a FAIL or STALE on a load-bearing claim is a must-fix before you commit.

The vertical check and the horizontal one. The fields above verify a claim vertically — the number in the paper against the output that produced it. That leaves untouched the failure a multi-artifact project produces most reliably: the analysis is rerun, the manuscript table is regenerated, and the deck, the supplement, or the poster quoting the same number is not. Every vertical check still passes, and the artifact an audience sees is the stale one.

appears_in closes that gap by making the second and third display of a number declared rather than remembered. Each entry names a path, a locator (where in that file the number sits), and a display_precision. The audit then does three things:

  1. Opens every declared display and reads the value at its locator.
  2. Compares pairwise at the coarser precision — a deck showing 0.34 where the paper shows 0.342 agrees, because the coarser side governs; a deck showing 0.29 does not. This separates a rounding choice from a value difference without anyone having to argue the case.
  3. Resolves a display it cannot find to FAIL, never to “skipped”. A locator that has quietly stopped matching is exactly the state a stale number hides in.

STALE widened to match: a claim goes stale when the source script, the output file, or any declared appears_in path is modified after last_verified_on. A touched display is as much a reason to re-check as a touched script — it is the edit that puts two artifacts out of step. Three surfaces act on this: the claim-reconcile hook nudges when a display is edited, nightly-repro-check marks display-touches STALE, and /commit triggers the passport check on display diffs rather than only on script diffs.

A constructed illustration, not a logged incident — the mechanism is real, the scenario is invented to make it concrete.

A structural-biology group revises a methods paper. A reviewer asks for a different background correction; the pipeline is rerun, and the reported binding-affinity shift moves from 0.42 to 0.38 log units. The manuscript and the supplement are both generated from the output files, so both update on the next build. The vertical audit is entirely green: every number in the paper traces to the script and line that produced it, within tolerance.

The lab’s graduate methods course has a slide that quotes the same figure. It was typed by hand in March, it is not generated from anything, and it still says 0.42. Before appears_in, nothing in the paper’s audit would have touched it — the audit’s scope was the manuscript.

The number had a declared appears_in entry for the deck. The horizontal check opens Slides/Methods_Binding.tex at the recorded locator, reads 0.42 against the manuscript’s 0.38 at the coarser of the two precisions, and fails the claim. One line in a YAML file was the difference between catching it and teaching it for a semester.

Starter file: templates/passport-template.yaml. Copy once per paper. Pattern attributed to Imbad0202/academic-research-skills “Material Passport” concept (scope-reduced for this template: numeric claims only).

5.6 Pattern 6: Multi-Agent Review

The /slide-excellence skill runs up to 7 specialized agents in parallel:

/slide-excellence Lecture5_Topic.tex
  |
  +-- Agent 1: Visual Audit (slide-auditor)
  +-- Agent 2: Pedagogical Review (pedagogy-reviewer)
  +-- Agent 3: Proofreading (proofreader)
  +-- Agent 4: TikZ Review (tikz-reviewer, if applicable)
  +-- Agent 5: Content Parity (if Quarto version exists)
  +-- Agent 6: R Code Review (r-reviewer, if the deck embeds R code)
  +-- Agent 7: Substance Review (domain-reviewer)
  |
  +-- Synthesize: Combined quality score + prioritized fix list

5.7 Pattern 7: Self-Improvement Loop

There are two levels of self-improvement: quick corrections via [LEARN] tags and full skill extraction via /learn.

5.7.1 Quick Corrections: [LEARN] Tags

Every correction gets tagged for future reference in MEMORY.md:

## Corrections Log
- [LEARN:notation] T_t = 1{t=2} is deterministic -> use T_i in {1,2}
- [LEARN:citation] Post-LASSO is Belloni (2013), NOT Belloni (2014)
- [LEARN:r-code] Package X: ALWAYS include intercept in design matrix
- [LEARN:workflow] Every Beamer edit must auto-sync to Quarto

These tags are searchable and persist across sessions. When Claude encounters a similar situation, it checks memory first.

5.7.2 Automated Skill Capture: /learn

For discoveries that deserve more than a one-line tag, use /learn to create a full skill:

/learn fixest-missing-covariate-handling

The /learn skill guides you through a 4-phase workflow:

Phase 1: EVALUATE
  "Was this non-obvious? Would future-me benefit?"
  → If YES to any, continue
         ↓
Phase 2: CHECK EXISTING
  Search .claude/skills/ for related skills
  → Nothing related? Create new. Overlap? Update existing.
         ↓
Phase 3: CREATE SKILL
  Write to .claude/skills/[name]/SKILL.md
  • Problem statement
  • Trigger conditions (exact errors, symptoms)
  • Step-by-step solution
  • Verification steps
         ↓
Phase 4: QUALITY GATE
  • Description has specific triggers?
  • Solution verified to work?
  • Specific enough to be actionable?
  • General enough to be reusable?

5.7.2.1 When to Use /learn

The context monitor suggests /learn at 40%, 55%, and 65% context usage. Consider extracting a skill when you encounter:

Trigger Example
Non-obvious debugging 10+ minute investigation not in docs
Misleading errors Error message was wrong, found real cause
Workarounds Found limitation with creative solution
Undocumented APIs Tool integration not in official docs
Trial-and-error Multiple attempts before success
Repeatable workflows Multi-step task you’d do again

5.7.2.2 Skill vs. [LEARN] Tag

Situation Use
One-liner fix [LEARN:category] tag in MEMORY.md
Multi-step workflow /learn to create full skill
Error + root cause + solution /learn if reusable, [LEARN] if not
Package quirk /learn if affects multiple projects

Skills saved to .claude/skills/ survive compaction and session boundaries — if you discover something valuable late in a session, extract it with /learn before compaction erases the details.

5.8 Pattern 8: Devil’s Advocate

At any design decision, invoke the Devil’s Advocate:

“Create a Devil’s Advocate. Have it challenge this slide design with 5-7 specific pedagogical questions. Work through each challenge and tell me what survives.”

This catches:

  • Unstated assumptions
  • Alternative orderings that might work better
  • Notation that could confuse students
  • Missing intuition before formalism
  • Cognitive load issues

A stronger variant: when Claude reviews its own work in the same conversation, it suffers confirmation bias — it has internalized its own reasoning and will systematically find the work acceptable. The fix: spawn a new agent via the Task tool with NO access to the original conversation. Give it only the artifact and a critique prompt. The fresh agent has no sunk cost in the work and will be ruthless.

“Spawn a new agent. Have it read only my paper draft — not our conversation. Ask it to find the 5 weakest points and suggest how a hostile referee would attack each one.”

Like handing your draft to a colleague who wasn’t in the room when you wrote it.

5.8.0.1 Fresh context is not a fresh environment

A forked reviewer is independent in context. It is not independent in filesystem. It still holds the repository checkout, and that checkout contains the previous round’s review reports, the judge’s verdict, the passport recording every number the paper claims, the ledger of what each checker has been shown to detect, and the render stamp saying what the current build came from. Telling an agent to “review this independently” while it can grep for the answer is an honour system with a search tool attached.

review-fencing.md (v2.5.1, path-scoped to agent and skill definitions) states the rule as a question to ask before dispatch: what would this reviewer’s environment reveal if it looked — and then remove that, rather than instructing it not to look. In practice that means a copy of the artifact placed outside the checkout under a neutral filename (artifact-a.tex, not paper_round3_after_referee_fixes.tex — a filename announcing the round has already reported what was found last time), prior verdicts withheld, and the reviewer’s own reading recorded before it is shown anyone else’s findings. Fencing is for reviews whose output is about to be compared against something; an in-repo review is right when the repository context is the point, as in cross-artifact traversal from paper to table to output to script.

A constructed illustration, not a logged incident — the failure mode is real, the scenario is invented to make it concrete.

-0.07314, in nine seconds. Correct to the last printed digit. That is what a team qualifying its reproduction agent got back from a positive control — reproduce a pinned coefficient from a published analysis and report it.

The transcript shows what happened. The agent never opened the analysis script. It ran one grep across the checkout, hit the claim’s row in passports/marsh-carbon.yaml — where the verified value is recorded, because that is what a passport is for — and reported it. The run demonstrated that grep works.

Re-run fenced: the analysis code and the input data copied into a scratch directory outside the repository, no passport, no ledger, no reports, no stamp. Four minutes. The value comes back -0.07319, differing from the pinned figure in the fifth decimal — a real, small, and entirely explicable difference in an iterative estimator’s convergence-tolerance default, which is exactly the kind of thing a positive control exists to surface, and exactly what the first run’s perfect answer had hidden.

The passport, the ledger, and the render stamp are this template’s own answer keys. They exist to be authoritative, which is precisely why an independence-critical reviewer must not be standing next to them.

5.9 Research Workflows

Patterns 1–8 apply broadly, with course materials as the primary example. The next four patterns are designed for research projects — papers, simulations, and empirical analysis — where the rhythm is different: ideas are uncertain, experiments may fail, and code is often written to answer a question rather than to ship. Patterns 13–14 then extend the foundation to reproducibility standards and presentation rhetoric, and Patterns 15–19 build the credibility layer: independent adversarial audits, preregistration, reviewer vaccination, the external oracle, and the assumption blast radius.

5.9.1 Pattern 9: Parallel Agents for Research Tasks

Claude Code can spawn multiple agents simultaneously using the Task tool. This is not limited to review — you can use it for any research or analysis task where independent subtasks can run at the same time.

5.9.1.1 When to Use Parallel Agents

Scenario Sequential (slow) Parallel (fast)
Reviewing a lecture Run proofreader, then auditor, then pedagogy Run all 3 simultaneously
Analyzing 3 papers for a new lecture Read paper 1, then 2, then 3 Spawn 3 agents, each reading one paper
Generating figures Create plot 1, then plot 2, then plot 3 Spawn agents for independent plots
Comparing estimators Run simulation 1, then 2, then 3 Spawn agents for each simulation
Debating research design Consider DiD, then SC, then RDD 3 agents, each advocating one approach

5.9.1.2 How It Works

You do not need to manage this manually. Skills that implement the orchestrator pattern (/create-lecture, /review-paper --peer, /slide-excellence, etc.) can recognize independent subtasks within their scope and spawn parallel subagents via context: fork — both during implementation (Step 1) and review (Step 3). For example, when /slide-excellence runs on a deck, it spawns the visual / pedagogy / proofread agents in parallel; when /review-paper --peer runs, it spawns the two referees in parallel. The parallelism is built into the skill’s logic, not into a repo-wide daemon.

You can also request parallelism explicitly:

“Read these three papers in parallel. For each, extract the key identification assumption, the main estimator, and whether they have a replication package. Summarize in a table.”

Either way, Claude spawns up to 3 Task agents, each processing one paper simultaneously, then synthesizes the results.

5.9.1.3 Long-running tasks: the Monitor tool (Apr 2026)

For genuinely long jobs — a 30-minute R fit, a /audit-reproducibility batch over many tables, a Quarto render of a 200-slide deck — the Monitor tool (Apr 2026 Week 15) lets Claude tail a background process’s stdout in real time and react when something interesting happens. The pattern: launch the long job in the background (Bash with run_in_background: true), then ask Claude to monitor until a condition fires (error, milestone, finish). No polling loop, no sleep cycles. Useful inside /data-analysis for the regression step and inside /audit-reproducibility when re-running the whole script suite.

5.9.1.4 Watching parallel agents: claude agents (May 2026)

When several review agents run in parallel (the /review-paper --peer editor + 2 referees, or /slide-excellence’s visual + pedagogy + proofread fan-out), use claude agents (Week 20, v2.1.139) to watch them on a single screen. Replaces the old workflow of opening one terminal per agent. See the Anthropic Utilities section below for the full description.

5.9.1.5 Agent Debates

A powerful variant: give each parallel agent a distinct methodological perspective and have them argue. Instead of asking “which estimator should I use?”, spawn 3 agents — one advocates for DiD, one for synthetic control, one for RDD — each arguing why their approach fits your research question best and critiquing the others. Synthesize the debate into a decision matrix. This produces genuinely diverse perspectives that a single conversation cannot, because each agent commits fully to its position.

5.9.1.6 What a delegated agent needs before it starts

Parallelism multiplies whatever you hand out, including vagueness. Two templates exist because the same instruction gets written badly in the same two ways.

templates/executor-contract.md is the shape of a dispatchable task: the goal, the acceptance bar that decides done, the exact paths to touch, the gates the work must pass, the output contract it must return, and the mechanisms it is allowed to refuse. An agent that does not know the bar will report success, because from inside the task there is nothing else to report.

templates/screening-rubric.md covers the other case — deciding which candidates survive, whether they are papers, datasets, specifications, or findings. It makes the default verdict a declared decision rather than a constant: a precision-first shortlist defaults to EXCLUDE, so a candidate is out unless a written criterion admits it, while a recall-first sweep must not, because a wrong exclusion leaves no trace for anything downstream to catch. Either way the evidence is recorded per candidate. It ends in an adjudication table and a dispatcher spot-check of a few decisions, because the person who wrote the rubric is the only one who can tell whether it was applied or merely cited. And a fan-out is adjudicated as a whole wave — bank every return, reconcile them together, then decide — rather than acting on whichever agent finished first.

A constructed illustration, not a logged incident — the failure mode is real, the scenario is invented to make it concrete.

A doctoral student delegates a first-pass screen of twenty candidate papers for a methods review: “read each one and tell me which are relevant to measurement error in self-reported exposure.” The agents come back fast and agreeable. Nineteen are marked relevant. The summaries are fluent, each one names a plausible connection, and the shortlist is useless — it is the original list with one paper missing.

“Relevant” was never defined, so each agent supplied its own definition, and any paper can be connected to any topic by a sufficiently generous reading. INCLUDE was the path of least resistance and there was no criterion pushing the other way.

The screen is re-run under a written rubric: default EXCLUDE, four inclusion criteria stated in advance, and a requirement that each verdict quote the sentence in the paper that satisfies the criterion — a quotation, not a paraphrase. Six survive. Eleven of the exclusions cite the same criterion (the paper measures a construct, but never validates the measure against an external source), which is itself a finding about the literature that the first pass could not have produced. The dispatcher then re-reads three candidates by hand — one included, one excluded, one borderline — and agrees with all three, which is what licenses trusting the other seventeen.

5.9.1.7 Practical Limits

  • 3 agents is the sweet spot. More than that increases overhead without proportional speedup.
  • Agents are independent — they cannot see each other’s work. If task B depends on task A’s output, they must run sequentially.
  • Each agent consumes its own context window. For very large files, sequential processing may be more reliable.
TipCost-Conscious Parallelism

Parallel agents multiply token usage. For cost-sensitive tasks, run the expensive work (Opus agents) sequentially and the cheap work (Sonnet agents) in parallel. The orchestrator already does this: it runs Sonnet-level reviewers in parallel, then the Opus-level critic sequentially.

5.9.2 Pattern 10: Research Exploration Workflow

The exploration workflow provides a structured sandbox for experimental work.

5.9.2.1 The Problem

Without structure, experimental code scatters across the repository: analysis scripts in scripts/, test files in root, comparison documents in quality_reports/. After a week of exploration, the repo is cluttered with files that may or may not be useful, and nobody remembers which version was the good one.

5.9.2.2 The Solution: Exploration Folder

All experimental work goes into explorations/ first:

explorations/
├── [active-project]/
│   ├── README.md           # Goal, hypotheses, status
│   ├── R/                  # Code iterations (_v1, _v2)
│   ├── scripts/            # Test scripts
│   └── output/             # Results
└── ARCHIVE/
    ├── completed_[name]/   # Graduated to production
    └── abandoned_[name]/   # Documented why stopped

5.9.2.3 Fast-Track vs. Plan-First

The decision tree is simple:

Question Answer Workflow
“Will this ship?” YES Plan-First (80/100 quality)
“Am I testing an idea?” YES Fast-Track (60/100 quality)
“Does this improve the project?” NO Don’t build it

Fast-Track explorations skip formal planning. Instead, a 2-minute research value check gates the work: “Does this improve the paper/slides/analysis?” If the answer is “maybe”, explore. If “no”, skip. If “yes”, use Plan-First rigor.

5.9.2.4 The Lifecycle

Research value check (2 min)
  ↓
Create explorations/[project]/ (5 min)
  ↓
Code without overhead (60/100 quality)
  ↓
Decision point (1-2 hours):
  ├── Graduate → Move to R/, scripts/, tests/ (upgrade to 80/100)
  ├── Keep exploring → Stay in explorations/
  └── Abandon → Archive with brief explanation

The kill switch is explicit: at any point, you can stop, archive with a one-paragraph explanation, and move on. No guilt, no sunk cost. See .claude/rules/exploration-folder-protocol.md and .claude/rules/exploration-fast-track.md for the full protocols.

5.9.2.5 Simplified Orchestrator for Research

The full orchestrator (Pattern 2) is designed for course materials with multi-agent review loops. For research projects, the simple variant strips this down to: implement → verify → score → done. No multi-round reviews, no parallel agent spawning. This lives in its own path-scoped rule (.claude/rules/orchestrator-research.md) that loads only when working on R scripts or explorations.

5.9.2.6 Merge-Only Quality Reporting

In research projects, commits are frequent and incremental. Generating a quality report for each commit creates noise. Instead, quality reports are generated only at merge time — a permanent snapshot of what was merged and why. Session logs capture the ongoing reasoning. See .claude/rules/session-logging.md.

5.9.3 Pattern 11: Research Skills

Five skills support the research workflow beyond slide development:

Skill What It Does When to Use
/lit-review [topic] Search, synthesize, and identify gaps in the literature Starting a new project or section
/research-ideation [topic] Generate research questions, hypotheses, and empirical strategies Brainstorming phase
/interview-me [topic] Interactive interview to formalize a vague idea into a concrete specification When you have an intuition but not a plan
/review-paper [file] Full manuscript review with referee objections Before submission or after a draft
/data-analysis [data] End-to-end R analysis: explore, regress, produce publication-ready output Empirical analysis phase

These skills produce structured reports saved to quality_reports/. The /data-analysis skill also generates R scripts (saved to scripts/R/) and runs the r-reviewer agent automatically.

Note/review-paper --peer [journal] — simulated peer review pipeline

For submission-ready manuscripts, /review-paper --peer <journal> runs an editor + two dispositioned referees + editorial decision, calibrated to the target journal. Editor calibration reads .claude/references/journal-profiles.md; the template ships profiles for AER, QJE, JPE, ECMA, ReStud (econ) and APSR, AJPS, JOP (poli-sci). Other fields: add a profile, ~40 lines each.

The methods-referee is paper-type-aware — the same skill picks different sanity checks based on what kind of paper this is:

Paper type Methods-referee tilts toward Sanity checks include
reduced-form identification credibility, robustness range sign, magnitude, clustering level, sample construction
structural model identification, counterfactual credibility, fit moment-matching, sensitivity to functional form, out-of-sample
theory+empirics model-data correspondence does the empirical estimand identify the theoretical object?
descriptive measurement validity, generalisability sampling frame, missingness, comparator choice
formal-theory (v1.8.0) model originality, comparative-static sharpness equilibrium existence, assumption tractability, robustness to relaxation
survey-experiment (v1.8.0) design, sampling, attrition + manipulation checks balance, manipulation-check pass rate, attrition asymmetry, sampling-frame validity

R&R continuation is built in: --r2 / --r3 for response-to-referees rounds; --stress for a hostile-editor stress test. See .claude/references/discipline-cards.md for econ + poli-sci defaults (paper-type frequency, dominant journals, preregistration norms, code conventions). Forkers extend for psych / sociology / public-health.

5.9.3.1 The Research Lifecycle as a Dependency Graph

A research project is not a waterfall — it is a dependency graph. Some phases run in parallel; others are strictly sequential:

/research-ideation ─────┐
                        ├──→ /lit-review ──→ /data-analysis ──→ /review-paper
/interview-me ──────────┘         ↑               ↑
                                  │               │
                          (can run in parallel)   │
                                                  │
                          (enter mid-pipeline: ───┘
                           start with data and
                           work backwards)

Enter mid-pipeline. You do not have to start from ideation. If you already have data, start with /data-analysis and work backwards to the research question. If you already have a draft, start with /review-paper. The skills are modular — use what you need, skip what you don’t.

For a production-grade paper pipeline, a dedicated fork takes these same skills and wraps them in full research infrastructure: 6 worker-critic agent pairs plus specialized agents (data-engineer, referees, verifier), simulated blind peer review, weighted aggregate scoring, journal targeting, and R&R response routing. If your primary output is research papers, see The Ecosystem for details.

5.9.4 Pattern 12: Branch Isolation with Git Worktrees (Advanced)

NoteAdvanced Pattern

This pattern is optional and primarily useful for major translations, risky refactors, or multi-day projects. Most day-to-day work doesn’t need it.

Strong statisticians hit these six walls more than any others; each has a one-line diagnosis:

  1. “Which directory am I in?” — pwd. Worktrees mean the same repo exists in two places; every git command acts on the one you are standing in.
  2. “What branch is checked out where?” — git worktree list shows every directory and its branch.
  3. “What is staged?” — git status; only the green (staged) files enter the next commit.
  4. “Why did git checkout main fail?” — a branch can be checked out in only ONE worktree at a time; cd back to the primary worktree instead.
  5. “Why does git branch -d refuse after my squash merge?” — a squash merge copies the changes but not the ancestry, so git can’t see the branch as merged; use -D once the squash commit is in.
  6. “How do I undo without reset --hard?” — git checkout -- <file> for one file, git stash to shelve everything; the template’s git guard blocks the destructive forms for exactly this reason.

Git worktrees create a separate working directory linked to the same repository. Each directory has its own branch but shares commit history. Subagents can use worktrees via the isolation: worktree field (see Advanced Agent Configuration).

your-project/                     ← main branch (stays clean)
.worktrees/lecture-06-quarto/     ← isolated branch (Claude works here)

5.9.4.1 Why Use Worktrees?

Benefit Example
Safe experimentation Translate Lecture 6 to Quarto — if it fails, main is untouched
Clean history 50 intermediate commits squash into one clean commit
Easy discard Wrong approach? Delete worktree, no trace in main
Multi-session work Resume worktree next day, no context loss
Parallel work Work on slides (main) while Claude translates (worktree)

5.9.4.2 The Workflow

1. CREATE WORKTREE
   git worktree add .worktrees/lecture-06-quarto -b quarto/lecture-06
   cd .worktrees/lecture-06-quarto
         ↓
2. IMPLEMENT
   All changes happen in the worktree
   Commit frequently (intermediate commits are OK)
         ↓
3. VERIFY
   Run tests, render, review against worktree only
         ↓
4. SYNC TO MAIN (when ready)
   cd ../..                # back to the primary worktree (main is checked out THERE;
                           # `git checkout main` inside the secondary worktree fails)
   git status --porcelain  # git-guardrails denies a merge into a dirty tree, and
                           # "kept working on main" is the whole point of a worktree,
                           # so expect this NOT to be empty — clear it first
   git stash push -u -m "pre-merge: in-flight edits"   # skip if porcelain was empty
   git merge --squash quarto/lecture-06
   git commit -m "feat: add Lecture 6 Quarto version"
   git stash pop                                       # only if you stashed above
         ↓
5. CLEANUP
   git worktree remove .worktrees/lecture-06-quarto
   git branch -D quarto/lecture-06   # -D: after a squash merge, git does not see the
                                     # branch as ancestrally merged, so -d refuses

5.9.4.3 Commands Reference

# Create a worktree with new branch
git worktree add .worktrees/[name] -b [branch-name]

# List active worktrees
git worktree list

# Remove a worktree (after merging or abandoning)
git worktree remove .worktrees/[name]

# Delete the branch (after removal)
git branch -D [branch-name]   # -D needed after --squash (no merge ancestry)

# Squash-merge into main
cd [primary-worktree]         # main lives in the primary worktree
git status --porcelain        # empty, or the merge is denied — clear it first (below)
git merge --squash [branch-name]
git commit -m "feat: description of changes"

# ...if the primary worktree is dirty, either stash around the merge:
git stash push -u -m "pre-merge: in-flight edits"   # -u, or untracked files stay behind
git merge --squash [branch-name]
git commit -m "feat: description of changes"
git stash pop

# ...or, ONLY if porcelain shows no `??` lines, let git stash the tracked changes:
git status --porcelain        # no `??` entries, or --autostash is denied too
git merge --squash --autostash [branch-name]
git commit -m "feat: description of changes"

The primary worktree is normally dirty when you reach the sync step, and that is the pattern working, not failing. You used a worktree so you could keep editing on main while the other branch ran; those edits are still sitting there. The git-guardrails hook denies git merge on a non-empty git status --porcelain, so the merge is refused exactly when the pattern did its job. Clear the tree first — stash with a label, merge, pop. That sequence works whatever porcelain shows, which is why it is the recipe above rather than the fallback. --autostash is the shorter route on a tree whose dirt is only tracked: the hook reads porcelain and allows it when there is no ?? entry, and denies it when there is, because git stash does not stash untracked files — so an autostash over a ?? line would start the merge on the same dirty tree the check exists to refuse. Two consequences follow. When porcelain is free of ?? lines, --autostash is allowed and the merge result comes back staged while your restored in-flight edits are unstaged, so the plain git commit above records the merge and leaves your work alone. When porcelain shows any ?? line — the ordinary case for a worktree you have been editing in — use the explicit -u stash; git’s own behaviour agrees, since a branch that adds a file at a path you are holding untracked aborts with “untracked working tree files would be overwritten” after the autostash has already been taken. Both forms have to be standalone commands either way: chaining the stash and the merge onto one line is denied under rule 0, whichever route you pick.

Noteworktree.baseRef (Apr 2026 Week 19)

Claude Code’s EnterWorktree tool branches fresh worktrees from a configurable base ref via the worktree.baseRef setting in .claude/settings.json:

  • fresh (default) — branch from the remote default branch (typically origin/main). Safest for clean experimentation.
  • head — branch from local HEAD. Use when you have uncommitted local work the worktree should inherit.

The default surprises users with uncommitted in-flight edits: a fresh worktree won’t see those changes. If your workflow assumes “branch off whatever I’m looking at now,” set "worktree.baseRef": "head".

5.9.4.4 When to Use

Situation Use Worktree?
Quick fix to one file No — just edit main
New lecture creation Maybe — if multi-session
Beamer → Quarto translation Yes — many intermediate states
Major refactor Yes — safe rollback
Experimenting with new approach Yes — easy discard

For example, translating Lecture 5 from Beamer to Quarto involves extracting TikZ diagrams, converting ggplot to plotly, and rewriting environments — dozens of intermediate files over multiple sessions. A worktree keeps main clean while you iterate.

5.9.4.5 Complexity Cost

  • Adds ~3 commands to learn
  • Adds mental model: “Where am I working?”
  • Requires discipline to sync/discard, not leave orphan worktrees

For most novice users, working directly on main with frequent commits is simpler and sufficient. Use worktrees when the benefits of isolation outweigh the added complexity.

5.10 Advanced Patterns: Reproducibility and Presentation Design

The patterns above use slides as the primary example, but the infrastructure is domain-agnostic. The next two patterns address dimensions no existing pattern covers: reproducibility standards and presentation rhetoric.

5.10.1 Pattern 13: Reproducibility & Replication Compliance

Pattern 5 covers matching someone else’s results before extending them. This pattern is the complement: packaging your own work so that others — and journal data editors — can verify it.

5.10.1.1 The AEA Data Editor Standard

The Template README for Social Science Replication Packages is the de-facto standard across the AEA, Review of Economic Studies, Economic Journal, and other major journals — the AEA’s policy states its use is “strongly encouraged” (not required), while the underlying information it organizes is required. It defines eight structured sections:

Section What It Covers
Overview What the code does, data sources, software, runtime
Data Availability Statements Provenance, access rights, redistribution permissions for every data source
Dataset List Every data file: source, format, whether provided
Computational Requirements Software versions, packages, random seeds, memory, runtime
Description of Programs Directory structure, execution order, dependencies
Instructions to Replicators Numbered steps — ideally one command
Table/Figure Mapping Every exhibit mapped to the specific program and line that generates it
References Proper bibliographic citations for all data sources

The Table/Figure Mapping row is exactly what passport.yaml (v1.9.0) machine-encodes: each numeric claim → script + line + output file + tolerance + verified-on timestamp. The Data Editor’s template asks for the spreadsheet-style version; the passport is the programmatic version. They’re complementary — generate the AEA spreadsheet from the passport when you submit.

The passport carries one field the AEA mapping does not ask for, and it is the one that protects the deposit from going quietly out of date: appears_in (v2.5.1) declares every artifact that displays a number, not only the exhibit that generates it. Displays are compared pairwise at the coarser display_precision, a declared display that cannot be located resolves to FAIL rather than being skipped, and STALE now fires when any declared display is edited after the last verification — not only when the script or its output changes. A deposit whose tables regenerate while a slide, a poster, or an abstract still quotes the previous revision passes the vertical mapping and fails the horizontal one, which is the correct outcome.

5.10.1.2 Which data license? Five questions, in order

  1. Did you create the data? If not, you cannot choose its license — the provider’s terms travel with it (AEA policy: authors convey inherited permissions and restrictions).
  2. Do any third-party terms govern a component? (commercial feeds, admin records, DUAs) → those components ship as access instructions, not files.
  3. May you redistribute publicly? Only then is an open license (e.g. CC-BY) on the table — for the parts you own.
  4. Privacy / IRB / contractual constraints? → restricted-access or synthetic-data route; document it in the Data Availability Statement.
  5. What does the venue actually require? Distinguish required policy (a complete deposit, a DAS) from recommended template from repository default — and when genuinely unsure, that’s a question for the data provider or counsel, not a guess.

5.10.1.3 Pre-Submission Checklist

Documentation:

Code:

Data:

Verification:

5.10.2 Pattern 14: The Rhetoric of Decks

The slide-auditor checks technical quality (overflow, spacing). The pedagogy-reviewer checks teaching quality (notation density, prerequisites). Neither addresses rhetorical quality — whether the slides persuade, whether the argument flows, whether beauty serves function.

The Rhetoric of Decks framework fills this gap.

5.10.2.1 The Three Laws

Law 1: Beauty is function. Beautiful slides are not decorated slides. Beauty is clarity made visible. Every element earns its presence. Nothing distracts from the point. “Decoration without function is noise.”

Law 2: Cognitive load is the enemy. One idea per slide. ONE. This is not a guideline — this is the law. The audience has limited working memory. Every unnecessary word, data point, or “just in case” inclusion steals bandwidth from the actual message.

Law 3: The slide serves the spoken word. “If your slides can be understood without you speaking, you have written a document and called it a presentation.” The slide is a visual anchor for speech — a focal point for attention, a memory hook for retention.

5.10.2.2 The MB/MC Equivalence

The most original contribution of this framework — applying marginal analysis to slide design:

Optimal rhetoric equalizes the marginal benefit to marginal cost ratio across all slides: MB₁/MC₁ = MB₂/MC₂ = … = MBₙ/MCₙ

What this means in practice:

  • Overloaded slides (MB/MC too low): text running into footer, competing ideas, audience gives up
  • Underloaded slides (MB/MC too high): wasted opportunity, attention captured but unused
  • The goal is smoothness — consistent cognitive load throughout — not maximum density
  • Exception: deliberate “jump scares” — intentional spikes for rhetorical effect (a striking statistic, a provocative claim)

5.10.2.3 Actionable Principles

Principle Why Anti-Pattern
Titles are assertions “Treatment increased distance by 61 miles” carries the argument “Results” tells the audience nothing
Bullets are defeat A list says “I couldn’t find the structure” Find the sequence, contrast, hierarchy, or causal chain
White space signals confidence Crowded slides signal fear — fear of silence, fear of forgetting Filling every pixel with text
Direct labels, not legends Legends force the eye to travel; labels stay with the data Color-coded legends requiring a key
One message per chart If you can’t explain it in one sentence, it’s too complex Multi-panel figures with competing stories
Min 24pt body, max 2 fonts Sans-serif for projection; test from the back row 12pt text, decorative fonts

5.10.2.4 How Existing Agents Support This

The /slide-excellence skill already invokes the pedagogy-reviewer and slide-auditor, which enforce many of these principles automatically. To enforce all of them — including title-as-assertion and MB/MC smoothness — customize the domain-reviewer agent (.claude/agents/domain-reviewer.md) with rhetoric-of-decks lenses. The orchestrator will then apply them during every review cycle without manual invocation.

For the complete philosophical treatment — from Aristotle’s three modes of persuasion through neuroaesthetics and the Netflix analogy — see The Rhetoric of Decks. The repository includes a full essay, example Beamer decks with professional color palettes, a theme_rhetoric() ggplot2 theme, and a tested deck generation prompt for Claude Code.

5.10.3 Pattern 15: Sequential Adversarial Audits

Principle: Run N independent audit passes, each focused on ONE dimension. Each auditor sees only the artifact — not previous audits — to prevent groupthink and anchoring bias.

This pattern differs from the multi-agent review in Pattern 6 in what carries the independence: each audit is a forked, single-lens review that cannot see the others’ reports. The shipped /seven-pass-review runs the seven lenses as parallel forked reviewers (isolation, not ordering, is what keeps a citation auditor uninfluenced by the prose auditor); running them one at a time by hand remains useful when you want to read one report before commissioning the next.

5.10.3.1 The Seven-Audit Protocol (for Papers)

Inspired by ClaudeCodeTools “The Editor”, this protocol runs seven independent passes before submission:

  1. Abstract audit — Does the abstract accurately reflect findings? Is it a compelling “storefront”?
  2. Introduction structure — Does the intro follow a recognized template (classic, puzzle-first, contribution-first)?
  3. Section-by-section audit — Data description, identification, results, robustness — each checked independently
  4. Argumentation audit — Logical gaps, alternative explanations, missing qualifications
  5. Prose quality — Passive voice, hedging, jargon density, paragraph flow
  6. Citation fidelity — Every claim has a citation? Every citation is real and correctly referenced?
  7. “So What” test — Five questions: What’s the question? Why does it matter? What did you find? How do you know? What does it mean?

5.10.3.2 How to Implement

Use /review-paper for a comprehensive single-pass review. When you need deeper, independent audits (e.g., before journal submission), run each audit as a separate skill invocation with context: fork to ensure isolation:

You: "Run the seven-audit protocol on my paper"
Claude: [Runs 7 parallel forked reviews, each blind to the others]
       → Produces 7 independent reports
       → Synthesizes into prioritized revision checklist

Adapting for other artifacts: The same principle works for replication packages (7 passes: code, data, documentation, licensing, runtime, outputs, README) or grant proposals (significance, approach, innovation, environment, budget).

For the R&R stage (after referee comments arrive): Use /respond-to-referees [report] [revised-manuscript]. It parses each concern, classifies coverage (addressed / partially / deferred / disagreement), points to specific revisions, and drafts the response document using templates/response-to-referees.md.

5.10.4 Pattern 16: Preregistration and Submission Discipline

Principle: Lock in your hypotheses, design, and analysis plan before you see the realised data. Preregistration is the strongest defence against p-hacking, HARKing, and forking-paths, and it’s increasingly mandatory for credibility in social-science venues. Pair it with /checkpoint for a session-side record of what you committed to and when — and for anything dispute-grade (a real preregistration), a committed artifact or registry entry: the checkpoint file itself is gitignored session state, not evidence.

5.10.4.1 When preregistration matters

  • Before launching an experiment (lab, field, or survey) — the canonical case.
  • Before analysing observational data on a target population for a specific RQ. “I have the data but haven’t looked at the outcome variable yet” is the right moment.
  • During R&R when a referee asks for a written preanalysis plan covering robustness specifications.
  • Funding — NSF, NIH, OSF, AEA grants increasingly require a PAP at submission.

5.10.4.2 Choosing a registry

The template ships three styles via /preregister --style:

Registry Style flag Field Length Editable later?
OSF (osf.io/registries) osf Broad social science (default for psych, poli-sci, sociology) Long-form, ~10–20 pages Yes, with versioning
AsPredicted (aspredicted.org) aspredicted Behavioural / experimental short-form 9 questions, ~2 pages Locked once submitted
AEA RCT Registry (socialscienceregistry.org) aea-rct Economics field experiments (mandatory for AEA journals since 2018) Structured fields, ~3–5 pages Limited fields editable

For public health / clinical trials, use ClinicalTrials.gov or ISRCTN directly — this template’s /preregister doesn’t cover those formats. They’re on the v2.0-backlog.

5.10.4.3 The workflow

/interview-me                       /preregister --style osf
   ↓                                   ↓
research-spec.md  ─────────────→  preregistration-draft.md
   ↓                                   ↓
(quality_reports/specs/)         (quality_reports/preregistrations/)
                                       ↓
                                  user reviews,
                                  uploads to OSF,
                                  receives registration ID
                                       ↓
                                  /checkpoint preregistration-submitted
                                       ↓
                                  data collection begins

/preregister reads your /interview-me spec frontmatter (the paper_type: field flows in from there if you set it) and produces a registry-formatted draft with MUST / SHOULD / MAY annotations on every section. Pre-flight checks: directional hypothesis declared, named estimator, ex-ante exclusion rules, sample-size stopping rule.

5.10.4.4 Mandatory fields per registry style

The --style flag determines the mandatory section list. The template enforces these via the pre-flight check:

Field OSF AsPredicted AEA RCT
Directional hypothesis (with sign) MUST MUST MUST
Sampling frame + recruitment MUST SHOULD MUST
Sample-size / stopping rule MUST MUST MUST
Named primary estimator MUST MUST MUST
Pre-specified covariate set SHOULD MAY MUST
Multiple-comparison adjustment plan SHOULD SHOULD MUST
Ex-ante exclusion rules MUST MUST MUST
Robustness specifications (named in advance) SHOULD MAY SHOULD
Data-sharing plan SHOULD MAY MUST
Intervention description (RCTs) — — MUST

/preregister refuses to draft a “retrospective preregistration” — if your description contains realised results or post-hoc reasoning, the skill halts and explains why. That refusal is the point.

5.10.4.5 Pairing with /checkpoint

/checkpoint is the structured companion to the narrative session-log workflow. For preregistration specifically:

  • Before submitting to the registry: /checkpoint preregistration-pre-submit snapshots the draft state, the spec it derives from, and the next-action (“upload to OSF and record registration ID”).
  • After submission: /checkpoint preregistration-submitted [registration-id] records the registry ID and the date in the structured snapshot. The plan and session log link to it.
  • On data arrival: /checkpoint data-arrived marks the boundary between “things I could legitimately commit to” and “things I learned from looking.” Anything that follows is exploratory unless explicitly anchored in the preregistered plan.

/checkpoint files live at quality_reports/checkpoints/YYYY-MM-DD_<slug>.md (gitignored — they’re session-state, not version-controlled artifacts). Optional --no-memory flag suppresses the auto-proposal of [LEARN] entries to MEMORY.md.

5.10.4.6 Post-flight verification

Any cited literature in the preregistration runs through /verify-claims (Chain-of-Verification, forked-verifier context, fresh) before the draft is considered ready. Hallucinated citations are the most common preregistration failure mode and the hardest to fix after submission — gate-refusing them at draft time pays back many-fold.

5.10.4.7 What this pattern protects against

  • HARKing (Hypothesising After Results are Known) — the preregistered hypothesis pins the directional claim before observation.
  • p-hacking — the named estimator + named multiple-comparison plan removes the discretion that produces inflated false-positive rates.
  • Forking paths — every data-dependent choice is either declared MUST or disclosed as exploratory.
  • Selective reporting — the data-sharing plan + named robustness specifications make selective reporting visible to referees.

For econometrics, see Christensen & Miguel (2018) on transparency in development economics. For political science, see Monogan (2015) on the political-science case. For psychology, see the OSF Preregistration Guide.

5.10.5 Pattern 17: Vaccinate Your Reviewers

The problem. You have built a review pipeline. It reports findings, it looks thorough, and you have no idea whether it works. Twenty planted bugs once produced a clean bill of health from a review fleet — and nothing in the output distinguished that from a genuinely clean run.

The pattern. Before a check or reviewer is allowed to clear anything, show it a defect you planted and confirm it goes red.

/vaccinate check-model-versions.sh
  1. Name the failure class. “Catches problems” is not a class.
  2. Seed it into a copy, plus at least one clean control.
  3. Run the checker blind, one variant per run, fresh context.
  4. Score recall and false-positive rate. A finding on the clean control counts against the checker only when it is factually wrong, not merely unwelcome.
  5. Beat a simpler baseline, or the complexity is cost rather than assurance.
  6. Write the ledger row.

Two failure modes worth knowing before you try it. A seed the artifact already permits creates no defect, so the checker correctly passes and looks broken. And a gate tuned only for detection over-fires — always qualify in both directions.

When to reach for it. Before a referee simulation informs a submission decision; after changing any checker; on a schedule for gates guarding load-bearing claims.

5.10.6 Pattern 18: The External Oracle

The problem. Your reviewers share your model’s blind spots. A forked subagent is independent in context, not in training — it fails the way you fail.

The pattern. Bring in a different vendor’s frontier model as a referee, and treat what it returns as candidates, never verdicts.

  • Brief first — question, scope, what is HELD (standing rulings not to relitigate), completion criteria, required evidence, escalation triggers.
  • Assign coverage — a statement inventory and a cross-round ledger, so union coverage reaches 100% instead of drifting toward whatever is easiest to read.
  • Force evidence — every objection carries a location, a one-sentence defect, and a failing case. Classify it; say which credibility question it concerns; compute what is computable.
  • Adjudicate — CONFIRMED / REFUTED / DOWNGRADED, mechanical checks first.
  • Batch the fixes, then run at most one confirmation round.

The limit, stated as loudly as the appeal: agreement is not confirmation. Different models correlate on the same wrong answer. An external oracle is advisory; a mechanical check outranks it.

Run exhaustive in-house coverage first, so the oracle is confirmation, not discovery — cheaper, and the answers are sharper.

Archive the transcript. An oracle round is an input to a decision, so the decision is not reconstructable without it. Transcripts go to quality_reports/oracle_audits/YYYY-MM-DD_topic/ — archived external-oracle transcripts, committed (like qualification/ and passports/), unlike the session-log and plan subdirectories, which are gitignored. The asymmetry is deliberate: a plan or a session log is scaffolding, while the exchange that produced a REFUTED verdict is evidence, and evidence that lives only in a chat window is the same as no evidence.

5.10.7 Pattern 19: Challenge Your Own Result

The problem. A single specification is one draw from a distribution you never looked at. And review will not save you here: in a controlled study, AI peer review left cross-analyst variance essentially unchanged. Review catches errors; robustness is a different question.

The pattern. Enumerate the forks a competent analyst could have taken before running anything, run the grid, and report the distribution.

/challenge scripts/R/03_analyze.R --forks 64 --dry-run
  • Label each fork estimand or estimate. Some choices change what is being estimated, not just the estimate — averaging over them is meaningless. Record estimand forks separately and say so in the report.
  • A fork belongs in the grid only if you would defend either branch in a seminar. Padding with indefensible alternatives dilutes the fragile cells.
  • Report which fork drives the spread. “Robust except to the choice between dollar and share volume” is worth more than a robustness paragraph.
  • Then attack the identifying assumption with a named, computable statistic — E-value, Cinelli–Hazlett RV, Oster δ.
  • Pre-commit the interpretation. Write what would support and what would weaken the claim before the grid runs.

A wide curve is a finding, not a failure. Publish it and say what drives it. The strongest sentence in a robustness section is usually the one that retires your own preferred reading.

6 The Ecosystem: What Others Have Built

This repository provides the foundation — the infrastructure patterns (plan-first, orchestrator, quality gates, adversarial review, context survival) that work for any academic task. Others have taken these patterns further, building specialized workflows for specific needs. Here are the principles these projects share and how to apply them:

Principle Source How to Implement Here
Adversarial review (not self-review) All Use fresh-context critique (Pattern 8) or worker-critic pairs
Structured intermediate files Xu & Yang Save every computed object to disk; agents communicate via files
Phase-appropriate rigor clo-author Light review for exploration (60/100), full adversarial for submission (95/100)
Voice preservation claudeblattman Maintain a reference doc with your writing style; load as context
Template-executor separation Xu & Yang Spec = what to measure, orchestrator = how to execute
Self-improving configuration claudeblattman Use /learn to capture discoveries; review MEMORY.md periodically
Human judgment, AI execution Xu & Yang You design the diagnostic; Claude runs it
Beauty is function MixtapeTools Every visual element earns its presence; decoration without function is noise
Constraint-based autonomy autoresearch Define boundaries in Markdown (what CAN/CANNOT change); let Claude explore within
Sequential independent audits ClaudeCodeTools Run N blind audit passes; independence prevents groupthink (Pattern 15)
TipWhich Ecosystem Project Should I Start With?

If you write papers: start with clo-author (adversarial review pairs) or ClaudeCodeTools (seven-audit protocol, see Pattern 15). If you give presentations: MixtapeTools. If you run computational experiments: autoresearch. If you’re a non-technical academic: claudeblattman. All of them build on the same foundation patterns from this template — the orchestrator, quality gates, and adversarial review.

Here is what each project does and when you should use it.

6.1 clo-author: Paper-Centric Research Workflows

Repository: hugosantanna/clo-author Author: Hugo Sant’Anna (UAB) Built on: Fork of this repository

clo-author reorients the entire workflow from slides to research papers. The paper (Paper/main.tex) becomes the single source of truth; talks and supplements derive from it. The key architectural innovation is adversarial worker-critic agent pairs: every creative agent is paired with a dedicated critic agent, with strict separation of powers (critics never create, creators never self-score).

What it adds:

  • 17 specialized agents organized as 6 worker-critic pairs (Librarian, Explorer, Strategist, Coder, Writer, Storyteller — each with a dedicated critic) plus standalone agents (data-engineer, domain-referee, methods-referee, orchestrator, verifier)
  • Phase-based severity gradient — critics are encouraging during Discovery, constructive during Strategy, strict during Execution, and adversarial during Peer Review
  • Weighted aggregate scoring with component minimums: Literature 10%, Data 10%, Identification 25%, Code 15%, Paper 25%, Polish 10%, Replication 5%. Submission gate (≥ 95) requires every component independently ≥ 80
  • Simulated blind peer review — two independent Referee agents plus an Editor making an editorial decision (Accept / Minor / Major / Reject)
  • Humanizer pass — identifies and strips 24 AI writing patterns across four categories (structural tics, lexical tells, rhetorical patterns, formatting tells)
  • Domain profile system — configurable field-specific calibration file read by all agents
  • Full submission pipeline — journal targeting, R&R response routing (classifies referee comments as NEW ANALYSIS / CLARIFICATION / DISAGREE / MINOR), AEA replication compliance, pre-analysis plans, cover letter generation

When to use it: Your primary output is research papers and you want production-grade infrastructure for the full lifecycle — from literature review through journal submission and revise-and-resubmit.

Noteclo-author v26.05 (May 2026)

clo-author has shipped substantial post-v4 architecture. The current release (v26.05, 2026-05-10) adds:

  • MAS v2 — second-generation multi-agent system with clearer worker/critic boundaries and phase-aware severity gradients
  • Skill-Centric Restructure — repository reorganised around 13 skills + 18 agents (up from 17 in the v4.x line)
  • HTML Dashboard — self-contained visual interface for tracking pipeline state across phases (no server required)

Patterns like /checkpoint (originally adapted with permission from clo-author v4.2.0) trace to the earlier line; if you’re forking clo-author directly today, you get the MAS v2 / skill-centric layout.

6.2 claudeblattman: Workflows for Non-Technical Academics

Website: claudeblattman.com Repository: chrisblattman/claudeblattman Author: Chris Blattman (University of Chicago)

claudeblattman is a comprehensive guide for academics who do not write code, built by a political economist who describes himself as someone who “has never written a line of code.” It demonstrates that Claude Code workflows extend far beyond technical tasks into daily academic life.

What it adds:

  • Executive assistant workflows — morning briefings (weather, calendar, inbox, VIP tracking), smart email triage with 14 phases, daily check-in ritual, schedule queries, todo management
  • Proposal writing — donor profiles, voice packs (maintain consistent writing style across documents), template gates, resubmission handling with reviewer comment categorization
  • Fresh-context critique — the intellectual centerpiece: spin up a fresh-context agent to review your work without self-bias (see Pattern 8)
  • Agent debates — multiple agents with distinct identities argue about research design, producing genuinely novel perspectives (see Pattern 9)
  • Tips pipeline — self-improving system: capture tips by emailing yourself, /tips-curate quality-filters them, /tips-integrate converts them into concrete configuration changes
  • Depth calibration — Light/Standard/Deep thoroughness levels that prevent over-engineering simple requests
  • Graceful degradation — every skill works with partial infrastructure. Missing MCP integrations produce explanations, not errors
  • Writing style rules — numbers over adjectives, topic sentences make claims, no throat-clearing, hedge only with a reason or number

When to use it: You are new to Claude Code, want practical daily workflows beyond coding, or want to see how an academic non-programmer built a sophisticated system.

6.3 Xu & Yang (2026): Reproducibility as Architecture

Paper: Yiqing Xu (Stanford) and Leo Yang Yang (HKBU), “Scaling Reproducibility: An AI-Assisted Workflow for Large-Scale Reanalysis,” 2026.

This paper formalizes many principles that this workflow uses intuitively. It demonstrates an AI-assisted pipeline that achieved 100% reproducibility across 92 papers (215 specifications) — conditional on accessible data and code — with each paper processed in under four minutes.

Key principles:

  • Template-executor separation — humans design diagnostic templates (what to measure), AI handles execution (how to run it). Maps to our spec-then-plan workflow.
  • Three-layer architecture — LLM orchestrator (coordination) → skill descriptions and knowledge bases (contracts and accumulated experience) → deterministic agent code (numerical work). Maps to our orchestrator → skills/rules → agents.
  • Structured intermediate files — agents communicate through standardized files on disk (JSON, CSV, logs), not hidden state. Ensures every step is inspectable and rerunnable.
  • Version-controlled knowledge accumulation — SKILL.md files with Context/Problem/Fix/Impact format. Maps to our /learn skill.
  • Adaptation between runs, not during runs — fixes are incorporated as version-controlled updates between sessions, never as ad hoc patches within a session. This ensures reproducibility.

When to reference it: You are designing a reproducibility workflow, building a replication package, or want to formalize the principles underlying this guide’s architecture.

6.4 MixtapeTools: The Rhetoric of Decks

Repository: scunning1975/MixtapeTools Author: Scott Cunningham (Baylor University), author of Causal Inference: The Mixtape

MixtapeTools provides the philosophical and practical framework for academic presentation design (see Pattern 14). Beyond the Rhetoric of Decks, it includes:

  • Referee 2 — a systematic 5-audit adversarial protocol for reviewing and replicating empirical work
  • Deck generation prompt — a tested, customizable multi-agent prompt for creating Beamer decks (builder → rhetoric reviewer → graphics specialist)
  • Example decks with professional color palettes, custom ggplot2 themes (theme_rhetoric()), and complete Beamer templates
  • Zero-warning compilation standard — even 0.5pt overfull hbox must be fixed

When to use it: You want to make your presentations genuinely beautiful and rhetorically effective, or you want a tested deck generation workflow for Claude Code.

6.5 AEA Data Editor Template

Website: social-science-data-editors.github.io/template_README Repository: social-science-data-editors/template_README Maintainer: Lars Vilhuber (Cornell University) and editors from REStat, EJ, CJE

The compliance standard for replication packages at 5+ major economics journals (see Pattern 13). Available in Markdown, Word, LaTeX, and PDF formats.

When to use it: You are preparing a replication package for journal submission and need the exact template that data editors will check against.

6.6 autoresearch: Constraint-Based Autonomous Research

Repository: karpathy/autoresearch Author: Andrej Karpathy

An autonomous research agent that runs continuous experiments — modifying code, training models, and evaluating results — without human intervention. The key insight for academic workflows:

  • program.md as a constitutional document — a single Markdown file defines what the agent CAN modify (architecture, hyperparameters), what it CANNOT (data pipeline, evaluation metric), and what success looks like (validation metric, lower is better)
  • Structured results logging — every experiment is recorded in a TSV file with branch name, metric, and status
  • Time-budgeted iterations — fixed training windows make experiments comparable

When to use it: You are running iterative computational experiments (Monte Carlo simulations, hyperparameter searches, model comparisons) and want Claude to explore the space semi-autonomously within defined constraints.

Example: Adapting the program.md pattern for a Monte Carlo study:

# program.md — Monte Carlo Experiment Constraints

## What You CAN Modify
- DGP parameters (sample sizes, effect sizes, correlation structures)
- Estimator implementations (new methods, tuning parameters)
- Number of replications (up to 10,000)

## What You CANNOT Modify
- prepare_data.R (data generation is frozen)
- evaluation metric (RMSE of ATT, lower is better)
- Output format (results.tsv with columns: method, n, rmse, coverage)

## Success Metric
RMSE of ATT estimate. Lower is better. Report coverage rate alongside.

6.7 stata-mcp: MCP server for Stata execution

Repository: SepineTam/stata-mcp Author: SepineTam (171+ stars, 91 releases, v1.17.3 as of May 2026)

A mature MCP server that lets Claude Code execute Stata .do files via a command-guarded interface — refuses destructive shell ops (!/shell/erase etc.), monitors RAM, and pairs with the Stata Language Server. Install once per user: claude mcp add stata-mcp --scope user -- uvx stata-mcp (requires uv and a local Stata install).

Why it matters for this template: v1.9.0 added /stata-replication for Stata-first projects, which depends on this MCP server. R-first projects (the original template focus) continue to use /data-analysis; the two skills are parallel — same pipeline shape, different source language. AEA submissions where the original replication package is in Stata are the canonical use case.

For end-to-end Stata workflows, see .claude/rules/stata-code-conventions.md (header scaffold, numbered pipeline, esttab tables, clustering discipline, AEA Data Editor compliance).

6.8 ClaudeCodeTools: The Editor Persona

Repository: aspi6246/ClaudeCodeTools

A collection of Claude Code personas, including “The Editor” — a deeply structured academic paper reviewer that runs seven sequential audit passes (see Pattern 15). Notable features:

  • R&R mode — tracks referee reports and cross-references each concern against revisions
  • Blunt, specific feedback — “This paragraph is incoherent” not “might benefit from clarity”
  • “So What” litmus test — five questions every paper must answer clearly

When to use it: You want a structured pre-submission paper review, or you’re responding to referee reports and need systematic tracking of which concerns have been addressed.

6.9 Anthropic-Shipped Apr 2026 Utilities

These are first-party Claude Code commands you can invoke directly without forking anything. Worth knowing because they fill gaps this template intentionally doesn’t try to fill:

  • /team-onboarding (Week 15) — packages your local Claude Code setup (CLAUDE.md, skills, agents, hooks, settings) into a replayable guide. Useful for lab groups: a PI configures the workflow once, the rest of the lab runs /team-onboarding and inherits a working copy. Complements but doesn’t replace this template’s “fork + customize” model.
  • /autofix-pr (Week 15) — runs Claude Code on a GitHub PR, applying typical CI-style fixes (lint, types, simple test failures). Pairs well with our /commit flow if you push a PR and want a follow-up auto-cleanup pass before review.
  • /powerup (Mar/Apr 2026 Week 14) — interactive lessons that teach Claude Code features (hooks, skills, MCP, plugins) with animated demos. Recommend this to new forkers who want to understand the primitives underneath the template’s customizations.
  • Ultraplan (Week 15) — draft a plan in the cloud from your CLI, review and comment on it in a web editor, then run it remotely or pull it back local. Useful for plans that need stakeholder review (e.g., a co-author signing off on an analysis approach before the actual run).
  • /loop self-pacing (Apr 2026 Week 15) — run a prompt or slash command on a recurring interval, or omit the interval to let the model self-pace until a stopping condition is met. Useful for status-polling tasks (“check the deploy every 5 minutes”) that pair with the Monitor tool above. The alias /proactive was added in Week 16.
  • /goal <verifiable condition> (May 2026 Week 20, v2.1.139) — the “keep working until X holds” command. Claude continues across turns until a fast model confirms the condition is satisfied. Distinct from /loop (which is interval-based) and from plan mode (which approves a strategy rather than enforcing an outcome). Pairs naturally with /commit’s quality gates: /goal "all sections pass /verify-claims with no HIGH-WARN findings" then commit. Works in interactive, claude -p, and Remote Control.
  • claude agents (May 2026 Week 20, v2.1.139) — one-screen dashboard for all background sessions. Replaces the multi-terminal pattern for parallel review work. Directly aligned with our /review-paper --peer and /qa-quarto parallel-reviewer setup; you can launch the referees and watch their progress from a single view.
  • /fewer-permission-prompts (Apr 2026 Week 16) — scans recent transcripts for read-only Bash and MCP calls and proposes a project-local allowlist. Sibling to our /permission-check: /permission-check diagnoses the prompt-fatigue source, /fewer-permission-prompts remediates it.

These are external to this template — invoke directly, no installation needed. Mention them as off-ramps when this template’s scope doesn’t fit.

6.10 Community Adoption

Research groups across multiple disciplines have forked and adapted this workflow for their own projects — 15+ research groups at the March 2026 survey; the repository has since passed 2,900 forks and 1,500 stars (GitHub, 2026-08-24). A fork is not a research group — the survey figure and the fork count measure different things, and only the first was checked by hand:

  • Economics — China innovation policy, mental health and layoffs, AIGC and stock prices, capital/labor shares in healthcare
  • Energy — Nepal and global energy economics, PV module reliability
  • Teaching — ECN 152 course development, Econ 730 causal panel data

Each adaptation follows the same pattern: fork the template, fill in CLAUDE.md placeholders, customize the domain reviewer, and add field-specific skills. The infrastructure (orchestrator, hooks, quality gates) transfers without modification.

7 Customizing for Your Domain

TipWhat ships preloaded vs. what you customize

Two disciplines are already concrete in this template:

  • Economics — top-5 journal profiles (AER, QJE, JPE, ECMA, ReStud), R-centric r-code-conventions.md, econometrics example in domain-reviewer.md.
  • Political Science — APSR, AJPS, JOP journal profiles (v1.8.0), formal-theory + survey-experiment paper types in methods-referee, poli-sci example in domain-reviewer.md.

Both fields are wired into .claude/references/discipline-cards.md, which /research-ideation, /interview-me, /preregister, and the editor agent read when you give them a discipline without a target journal. Cards document paper-type frequency, dominant journals, preregistration norms (OSF / AsPredicted / AEA RCT / ClinicalTrials.gov), significance-stars conventions, SE conventions, and dominant code language (R / Stata / Python).

Forking for psych, sociology, public health, or other fields: add ~3 journal profiles, 2–3 paper types, 1 discipline card. The infrastructure (orchestrator, hooks, quality gates, peer-review pipeline) is field-agnostic and transfers without modification. The v2.0 backlog (.claude/references/v2.0-backlog.md) lists psychology, sociology, and public-health as candidate next breadth additions.

7.1 Step 1: Build Your Knowledge Base

The knowledge base (.claude/rules/knowledge-base-template.md) is the most domain-specific component — it’s a path-scoped rule that loads automatically when Claude works on your content files. It provides skeleton tables for notation conventions, lecture progression, applications, design principles, anti-patterns, and R code pitfalls. Fill them in as you develop your project — you don’t need everything upfront.

7.1.1 Notation Registry

| Symbol | Meaning | Introduced | Anti-Pattern |
|--------|---------|------------|-------------|
| $\beta$ | Regression coefficient | Lecture 1 | Don't use $b$ |
| $\hat{\theta}$ | Estimator | Lecture 2 | Don't use $\hat{\beta}$ for different estimand |

7.1.2 Applications Database

| Application | Paper | Dataset | Package | Lecture |
|------------|-------|---------|---------|--------|
| Minimum Wage | Card & Krueger (1994) | NJ/PA fast food | `fixest` | 3 |

7.1.3 Validated Design Principles

| Principle | Evidence | Lectures Applied |
|-----------|----------|-----------------|
| Motivation before formalism | DA challenge: "students lost" | All |
| Max 3 new symbols per slide | Pedagogy review caught overload | 2, 4 |

7.2 Step 2: Create Your Domain Reviewer

Copy .claude/agents/domain-reviewer.md and customize the 5-lens framework for your field. The template provides the structure; you fill in domain-specific checks.

7.3 Step 3: Adapt Your Theme

The template includes matching LaTeX and Quarto palettes. To customize:

  1. Edit Preambles/header.tex (Beamer/TikZ) and Quarto/theme-template.scss (Quarto) together — same color names, matching HEX values.
  2. Run ./scripts/check-palette-sync.sh to confirm they agree. The check is also invoked by ./scripts/validate-setup.sh after any palette edit.
  3. Update CSS class names in the SCSS if needed.
  4. Modify the beamer-translator environment mapping to match your classes.

Palette contract. The core palette names (primary-blue, primary-gold, highlight-yellow, light-bg, jet) must exist on both surfaces. Snippets in templates/tikz-snippets/ currently inline their colors for standalone compilation, but real lectures that \input{header} inherit the palette automatically. See Preambles/README.md for the full contract and TikZ style library.

7.4 Step 4: Creating Custom Skills

The guide includes 60 skills for common academic tasks. But if you have repetitive workflows specific to your domain, you can create your own.

7.4.1 When to Create a Skill

Create a skill when: - You repeatedly explain the same 3+ step workflow to Claude - You need domain-specific quality checks (citation style, notation consistency, lab protocols) - You enforce field-specific output formats (thesis structure, journal templates) - You coordinate multi-tool workflows (data → analysis → manuscript)

Don’t create a skill for: - One-time tasks - Workflows that change frequently - Simple 1-2 step operations

7.4.2 Skill Structure

Each skill is a directory in .claude/skills/ with a SKILL.md file:

---
name: your-skill-name
description: [What it does] + [When to use] + [Key capabilities]
argument-hint: "[brief hint for user]"
allowed-tools: ["Read", "Write", "Edit", "Bash", "Task"]
---

# Your Skill Name

## Instructions
Step 1: [First action with details]
Step 2: [Second action]
...

## Examples
Example 1: [Common scenario]
...

## Troubleshooting
Error: [Common error]
Solution: [How to fix]

7.4.3 Complete Frontmatter Reference

The YAML frontmatter controls how your skill behaves. The most-used fields:

Field Purpose Example
name Display name in / menu compile-latex
description Most important. Controls when Claude auto-loads the skill Compile Beamer slides...
argument-hint Placeholder shown after /skill-name <filename>
allowed-tools Pre-approve tools (skip permission prompts). NOT a restriction — unlisted tools remain callable through normal permissions ["Read", "Bash", "Glob"]
disallowed-tools Remove tools from Claude’s pool while the skill is active — this is the actual restriction mechanism ["Edit", "Write"]
paths Glob patterns scoping when the skill auto-activates (skill-level analogue of path-scoped rules) ["scripts/**/*.R"]
when_to_use Extra routing context for auto-invocation after a merge conflict
arguments Named positional arguments for $name substitution [infile, outfile]
effort Override reasoning effort level high
context Set to fork to run in an isolated subagent fork
agent Link to an agent definition in .claude/agents/ proofreader
hooks Skill-specific hooks (same syntax as settings.json) {PreToolUse: [...]}
model Force a specific model haiku
disable-model-invocation Prevent Claude from auto-triggering true
user-invocable Whether it appears in the / menu true (default)
Warningallowed-tools does not sandbox

A common (and security-relevant) misreading: omitting Bash from allowed-tools does not make a skill read-only — allowed-tools only pre-approves the listed tools so they skip permission prompts; everything else stays callable under your normal permission settings. To genuinely remove tools while a skill runs, use disallowed-tools (e.g. ["Edit", "Write", "Bash"] for a read-only audit skill, plus AskUserQuestion for anything that runs unattended). See templates/skill-template.md for the full pattern.

NoteKey Design Choices
  • effort: high is useful for review skills that need deep reasoning (e.g., paper critique). Use effort: low for simple formatting skills to save tokens.
  • context: fork runs the skill in a fresh subagent context, protecting your main conversation from large outputs. Good for skills that produce verbose reports.
  • disallowed-tools genuinely removes tools while a skill runs — use it to make review skills read-only. (allowed-tools alone does not sandbox; see the callout above.)

7.4.4 Dynamic Content in Skills

Skills can include dynamic values using string substitutions and live command output:

String substitutions:

Syntax Expands To Example Use
$ARGUMENTS Full argument string after /skill-name /compile-latex Lecture01 → $ARGUMENTS = Lecture01
$0, $1, $N Positional arguments (0-based, space-separated) /deploy Lecture01 draft → $0 = Lecture01, $1 = draft
${CLAUDE_SESSION_ID} Current session identifier Unique log file names
${CLAUDE_SKILL_DIR} Path to the skill’s directory Reference supporting files bundled with the skill

Dynamic context injection with !`command` syntax:

## Context
Current git status: !`git status --short`
Recent changes: !`git log --oneline -5`
Available lectures: !`ls Slides/*.tex`

When Claude loads the skill, it runs these commands and injects the live output into the skill text. This is powerful for skills that need to adapt to the current project state.

7.4.5 Writing Effective Trigger Descriptions

The description field is the single most important thing you write when creating a skill. Claude reads the description of every available skill on every turn and uses it to decide whether to auto-invoke without the user typing a slash command. A vague description means a skill that only runs when the user remembers its name — defeating the point of auto-invocation.

The gold-standard pattern has three parts:

  1. Verb + object — what the skill does, in one clause. Start with an action verb (Compile, Review, Generate, Translate).
  2. “Use when:” trigger phrases — 3–5 phrases the user might actually say. Include verbatim quotes ("proofread", "check the layout") and semantic paraphrases ("does this overflow?"). Cover both explicit commands and natural-language requests.
  3. Disambiguation from sibling skills — if your skill lives near others in the same domain (e.g., proofread, visual-audit, and pedagogy-review all operate on slides), explicitly say what it is not for, or point at the alternative. This prevents mis-routing.

Example: refactoring a weak description into an A-grade one.

Before (weak — the skill exists but Claude won’t auto-pick it):

description: Run the proofreading protocol on lecture files. Checks grammar, typos, overflow, consistency.

After (strong — Claude will match this from cold prompts):

description: Read-only proofreading pass over lecture .tex or .qmd files.
  Checks grammar, typos, overflow, terminology consistency, and academic
  writing quality; produces a report without editing. Use when user says
  "proofread", "check for typos", "look for grammar issues", "copy-edit
  this", "any writing errors?", or before a lecture release.

The test: imagine a teammate who has never seen your skill list types "can you look for writing errors in Lecture 3?". Does your description contain enough lexical overlap that Claude would match it against competing skills? If not, add more trigger phrases.

Another good example (disambiguation):

description: Interactive interview that formalizes a fuzzy research idea into
  a structured spec (RQ, hypotheses, identification, data needs, empirical
  strategy). Use when user says "interview me", "help me think through this
  idea", "I have a half-baked idea". Multi-turn Q&A; saves spec to disk.
  NOT for lit review (/lit-review) or ideation from scratch (/research-ideation).

The final sentence — “NOT for X, use /Y instead” — is the disambiguation clause. Two skills with overlapping descriptions will split Claude’s routing probability; the explicit “not for” resolves the tie.

Bad (too vague — will never auto-invoke):

description: Helps with citations

Checklist before shipping a new skill:

7.4.6 Domain-Specific Examples

Regression Output Formatter

Converts R regression outputs to publication-ready LaTeX tables with proper formatting (standard errors in parentheses, significance stars, fixed effects rows).

Trigger: User runs regressions and says “make a table”, “format results”, “export to LaTeX”

Tools: Read, Write, Bash (to run R scripts)

Protocol Validator

Validates lab protocols against safety and reproducibility standards. Checks for: required sections (materials, procedure, safety), quantitative specifications, controls, and replication details.

Trigger: User provides protocol documents, asks “check protocol”, “validate procedure”

Tools: Read, Write

Citation Cross-Reference Checker

Cross-references in-text citations against bibliography entries. Identifies missing entries, unused references, and formatting inconsistencies.

Trigger: User asks “check citations”, “validate references”, when working on manuscripts

Tools: Read, Grep, Glob, Write

7.4.7 Quick Start

  1. Copy the template:

    mkdir -p .claude/skills/your-skill-name
cp templates/skill-template.md .claude/skills/your-skill-name/SKILL.md

  2. Customize for your domain:

    • Replace trigger phrases with your field’s terminology
    • Add domain-specific file types and tools
    • Include field conventions and common errors

  3. Test the skill:

    • Skills hot-reload automatically — changes are detected without restarting
    • Use one of your trigger phrases
    • Verify the skill loads and produces correct output

  4. Iterate:

    • If skill doesn’t trigger: Revise description with more specific phrases
    • If instructions unclear: Add more examples
    • If output wrong: Add validation steps

Full template: See templates/skill-template.md for comprehensive examples from biology, economics, and physics.

TipReal Example: /deep-audit Was Created with /learn

The /deep-audit skill was itself extracted from a repeating workflow using /learn. After running 7 rounds of manual consistency audits — each time launching 4 parallel agents to check guide accuracy, hook code quality, skills/rules consistency, and cross-document counts — the pattern was codified into a skill. Now /deep-audit launches those same 4 agents, triages findings, applies fixes, and loops until clean (loop-until-dry: converges after 2 dry rounds, with a fallback cap). It also encodes a table of known bug patterns from past audits so future rounds catch regressions faster.

This is the /learn lifecycle in action: discover a repeating workflow → extract it → never repeat the manual steps again.

7.5 Tips from 6+ Sessions of Iteration

  1. Keep CLAUDE.md under 150 lines. Claude follows ~150 instructions reliably. A 400-line CLAUDE.md means rules get silently ignored. Use path-scoped rules for detailed standards.
  2. Add rules incrementally. Don’t try to write all rules upfront. Add them when you discover patterns. Use paths: frontmatter so they only load when relevant.
  3. Use the [LEARN] format. Every correction gets tagged and persisted in MEMORY.md. This prevents repeating mistakes across sessions.
  4. Trust the adversarial pattern. The critic-fixer loop catches things you won’t. Let it run.
  5. Verify everything. The verification rule exists for a reason. Never skip compilation or rendering checks.
  6. Session logs matter. Document design decisions, not just what changed. Future-you will thank present-you.
  7. Devil’s Advocate early. Challenge slide structure before you’ve built 50 slides on a shaky foundation.
  8. Progressive disclosure. Start with CLAUDE.md + 2–3 rules. Add more as your workflow matures. Newcomers should not face all 37 rules on day one.
  9. Use CLAUDE.local.md for personal overrides. This file is automatically gitignored and loaded alongside CLAUDE.md. Put machine-specific paths, personal preferences, and local tool versions here — they won’t pollute the shared repo.

For capabilities beyond file editing and shell commands — web search during literature review, database queries for replication, or reference manager integration (Zotero, Mendeley) — Claude Code supports MCP servers. Configure them in .claude/settings.json under "mcpServers". Start with skills and agents first; add MCP when you need external integrations.

7.6 Extending with Plugins

Claude Code supports plugins — bundled collections of skills, agents, hooks, and MCP servers that can be installed from git repositories. Use /plugin to browse and manage plugins (it has a Discover tab for finding new ones). Plugins are a newer extension point; start with skills and rules (which you control entirely) before adopting third-party plugins.

8 Appendix: File Reference

8.1 All Agents

Agent File Purpose
Proofreader .claude/agents/proofreader.md Grammar, typos, consistency
Slide Auditor .claude/agents/slide-auditor.md Visual layout, overflow, spacing
Pedagogy Reviewer .claude/agents/pedagogy-reviewer.md Narrative arc, notation clarity
R Reviewer .claude/agents/r-reviewer.md R code quality, reproducibility
TikZ Reviewer .claude/agents/tikz-reviewer.md Diagram visual quality
Beamer Translator .claude/agents/beamer-translator.md LaTeX to Quarto translation
Quarto Critic .claude/agents/quarto-critic.md Adversarial Quarto QA
Quarto Fixer .claude/agents/quarto-fixer.md Applies critic’s fixes
Verifier .claude/agents/verifier.md Task completion verification
Domain Reviewer .claude/agents/domain-reviewer.md Your domain-specific review
Claim Verifier .claude/agents/claim-verifier.md Chain-of-Verification (fresh-context) fact-checker (v1.7.0)
Editor .claude/agents/editor.md Journal editor for /review-paper --peer (desk review + referee selection + editorial synthesis, v1.5.0)
Domain Referee .claude/agents/domain-referee.md Disposition-primed substance referee for /review-paper --peer (v1.5.0)
Methods Referee .claude/agents/methods-referee.md Paper-type-aware methodology referee for /review-paper --peer (v1.5.0; +formal-theory + survey-experiment in v1.8.0)
Humanize Auditor .claude/agents/humanize-auditor.md Read-only auditor for AI-voice tells in academic prose; invoked by /humanize (v1.9.0)
Promote-Memory Council .claude/agents/promote-memory-council.md Five-critic council (generality / staleness / redundancy / evidence / format) for [LEARN] promotion from native auto memory to MEMORY.md; invoked by /promote-memory (v1.9.0)
Sim Reviewer .claude/agents/sim-reviewer.md Monte Carlo reviewer — DGP/estimand match, Monte Carlo SE, coverage-vs-truth, claims↔︎tables parity (v1.10.0)
R Package Reviewer .claude/agents/r-package-reviewer.md R package-source reviewer — DESCRIPTION/NAMESPACE hygiene, roxygen, testthat, CRAN-policy red flags (v1.10.0)

8.2 All Skills

Skill Directory Purpose
/compile-latex .claude/skills/compile-latex/ XeLaTeX 3-pass compilation
/deploy .claude/skills/deploy/ Quarto render + GitHub Pages sync
/extract-tikz .claude/skills/extract-tikz/ TikZ to SVG conversion
/new-diagram .claude/skills/new-diagram/ Scaffold a TikZ diagram from the gallery
/proofread .claude/skills/proofread/ Run proofreading agent
/visual-audit .claude/skills/visual-audit/ Run layout audit agent
/pedagogy-review .claude/skills/pedagogy-review/ Run pedagogy review agent
/review-r .claude/skills/review-r/ Run R code review agent
/qa-quarto .claude/skills/qa-quarto/ Critic-fixer adversarial loop
/slide-excellence .claude/skills/slide-excellence/ Combined multi-agent review
/translate-to-quarto .claude/skills/translate-to-quarto/ Beamer to Quarto translation
/vaccinate .claude/skills/vaccinate/ Grade the grader: seed known defects + a clean control, report recall and false-positive rate into quality_reports/qualification/LEDGER.md
/adjudicate-review .claude/skills/adjudicate-review/ Turn incoming findings — AI review, referee report, linter, second model — into verified fixes. Every finding is a CANDIDATE until checked against the source
/blast-radius .claude/skills/blast-radius/ Before and after changing anything shared (return value, schema, default, units), enumerate every consumer and actually run them
/credible-claims .claude/skills/credible-claims/ Research brief before delegating, claim record after. Keeps faster execution from being mistaken for credible evidence
/differential-audit .claude/skills/differential-audit/ Compare two implementations — a port, a replication, a refactor, a version upgrade — so that agreement means something
/oracle-review .claude/skills/oracle-review/ Run an external frontier-model referee (Claude Code → GPT-5.6 Sol Pro) and adjudicate what comes back
/verify-artifact .claude/skills/verify-artifact/ Prove the file you are about to send IS the thing you mean — rebuild, verify integrity, diff against source
/voice-profile .claude/skills/voice-profile/ Extract a written voice profile from your own prior papers, then audit drafts against it — the positive counterpart to /humanize, which only detects AI tells
/validate-bib .claude/skills/validate-bib/ Bibliography validation
/devils-advocate .claude/skills/devils-advocate/ Design challenge questions
/create-lecture .claude/skills/create-lecture/ Full lecture creation
/commit .claude/skills/commit/ Stage, commit, PR, and merge
/lit-review .claude/skills/lit-review/ Literature search and synthesis
/research-ideation .claude/skills/research-ideation/ Research questions and strategies
/interview-me .claude/skills/interview-me/ Interactive research interview
/review-paper .claude/skills/review-paper/ Manuscript review
/respond-to-referees .claude/skills/respond-to-referees/ R&R cross-reference and response draft
/data-analysis .claude/skills/data-analysis/ End-to-end R analysis
/audit-reproducibility .claude/skills/audit-reproducibility/ Enforce replication tolerance thresholds on paper ↔︎ code
/learn .claude/skills/learn/ Extract discoveries into persistent skills
/context-status .claude/skills/context-status/ Show session health and context usage
/deep-audit .claude/skills/deep-audit/ Repository-wide consistency audit
/seven-pass-review .claude/skills/seven-pass-review/ Seven-pass adversarial manuscript review (parallel forked subagents)
/permission-check .claude/skills/permission-check/ Diagnose permission layers (6-tier stack)
/verify-claims .claude/skills/verify-claims/ Chain-of-Verification fact-check on any draft (v1.7.0)
/checkpoint .claude/skills/checkpoint/ Structured session-handoff snapshot — companion to narrative session logs (v1.8.0)
/preregister .claude/skills/preregister/ Generate a preregistration document (OSF / AsPredicted / AEA RCT Registry) from a research spec (v1.8.0)
/humanize .claude/skills/humanize/ Detect AI-voice tells in academic prose (read-only audit; no rewrite) (v1.9.0)
/compress-session .claude/skills/compress-session/ Distil the current session into a structured note (decisions, files, open questions, next actions, discarded-as-noise) before auto-compaction (v1.9.0)
/promote-memory .claude/skills/promote-memory/ Five-critic council that votes on whether candidate [LEARN] entries should be promoted from native auto memory to MEMORY.md (v1.9.0)
/stata-replication .claude/skills/stata-replication/ End-to-end Stata pipeline scaffold + execution via the stata-mcp MCP server (mirrors /data-analysis for R-first projects; v1.9.0)
/simulation-study .claude/skills/simulation-study/ Reproducible Monte Carlo study — DGP, estimator grid, seeded reps, bias/RMSE/coverage/size/power with Monte Carlo SEs (v1.10.0)
/r-package-check .claude/skills/r-package-check/ R package release gate — devtools::document() + tests + R CMD check --as-cran + CRAN-policy triage (v1.10.0)
/replication-package .claude/skills/replication-package/ Assemble a submission-ready DCAS / openICPSR replication package; calls /audit-reproducibility and blocks on FAIL (v2.0)
/challenge .claude/skills/challenge/ Stress-test a finding against the choices you didn’t make — specification curve over the discrete forks, then named sensitivity statistics (E-value, Cinelli–Hazlett RV, Oster δ) against the identifying assumption
/capture-environment .claude/skills/capture-environment/ Snapshot the computational environment (renv.lock / sessionInfo / requirements.txt / uv.lock + optional Dockerfile + seeds) (v2.0)
/power-analysis .claude/skills/power-analysis/ Power / required-N / MDE for study design (RCT, clustered/ICC, multi-arm, or simulation-based) + a methods paragraph for /preregister (v2.0)
/disclosure-check .claude/skills/disclosure-check/ Pre-screen restricted-data outputs for SDL violations (small cells, dominance, PII); gates on any CRITICAL (v2.0)
/grant-proposal .claude/skills/grant-proposal/ Scaffold a grant proposal (NSF/NIH/ERC/foundation) from an /interview-me spec; delegates DMP + facilities; aims↔︎methods↔︎budget coherence pass (v2.0)
/data-management-plan .claude/skills/data-management-plan/ Draft a funder-compliant Data Management Plan (NSF/NIH 2023/ERC/Horizon) (v2.0)
/coauthor-brief .claude/skills/coauthor-brief/ Generate a collaborator handoff brief: git delta, per-artifact state, open questions, reproduce-locally + restricted-data steps (v2.0)
/triage-inbox .claude/skills/triage-inbox/ Triage academic email + calendar (Gmail/Calendar MCP) into a prioritized digest + referee-obligations tracker; human-gated actions only (v2.0)
/syllabus .claude/skills/syllabus/ Build a course syllabus from a topic/reading list (schedule, objectives, assessment + rubric, per-week /create-lecture work-list) (v2.0)
/teach-from-paper .claude/skills/teach-from-paper/ Turn a paper into a lecture outline, teachable results, slide skeleton (→ /create-lecture), discussion questions, exercise brief (v2.0)
/respond-to-eval .claude/skills/respond-to-eval/ Turn student course evaluations into a classified teaching-improvement plan (Keep/Change/Investigate/Out-of-scope) (v2.0)
/scaffold-exercises .claude/skills/scaffold-exercises/ Scaffold a graded problem set (analytical/empirical/coding) with worked solutions; clean student set + separate solution key (v2.0)
/new-skill .claude/skills/new-skill/ Scaffold a convention-compliant skill (interview → write SKILL.md with gate-passing frontmatter) (v2.0)
/diagnose .claude/skills/diagnose/ Root-cause a wrong or failing empirical result — reproduce → minimise → bisect → instrument → fix; --no-fix localizes without editing (v2.0)
/submission-disclosures .claude/skills/submission-disclosures/ Submission-time disclosure block: journal-matched AI-use, CRediT roles, conflict-of-interest, and data-availability statements (v2.1)

8.3 All Rules

Always-on (load every session):

Rule File Purpose
Plan-First Workflow plan-first-workflow.md Plan mode + context preservation
Orchestrator Protocol orchestrator-protocol.md Review runtime: fan-out → reduce → judge (+ hallucination gate) → loop-until-dry (goal-first / gate-enforced; augments contractor mode)
Session Logging session-logging.md Three logging triggers
Meta-Governance meta-governance.md Template vs working project distinctions
Prompt Shaping prompt-shaping.md Ambient prompt-shaping habit (replaces the retired /prompt and /prompt-only skills)
Progress Reports progress-reports.md GitHub as memory — issues as defect memory, quality_reports/ as work memory, MEMORY.md as lesson memory
Repo Hygiene repo-hygiene.md Scratch must not become main — enforced by check-repo-hygiene.py on every commit

Path-scoped (load only when working on matching files):

Rule File Triggers On
Verification Protocol verification-protocol.md .tex, .qmd, docs/
Agent-Authored Code agent-authored-code.md **/*.sh, **/*.py
Inference Robustness inference-robustness.md scripts/**/*.R, scripts/**/*.do
Issue Ledger issue-ledger.md .github/**, **/ISSUE_TEMPLATE/**
Writing With AI writing-with-ai.md **/*.tex, **/*.qmd
Single Source of Truth single-source-of-truth.md Figures/, .tex, .qmd
Quality Gates quality-gates.md .tex, .qmd, *.R
R Code Conventions r-code-conventions.md Figures/**, scripts/**, explorations/** (analysis scripts)
TikZ Quality tikz-visual-quality.md .tex
TikZ Prevention tikz-prevention.md Slides/**, Figures/**, Preambles/**
TikZ Measurement tikz-measurement.md Slides/**, Figures/**, Preambles/**, scripts/**
Beamer-Quarto Sync beamer-quarto-sync.md .tex, .qmd
PDF Processing pdf-processing.md master_supporting_docs/
Proofreading Protocol proofreading-protocol.md .tex, .qmd, quality_reports/
No Pause no-pause-beamer.md .tex
Replication Protocol replication-protocol.md *.R
Knowledge Base knowledge-base-template.md .tex, .qmd, *.R
Orchestrator Research orchestrator-research.md *.R, explorations/
Exploration Folder exploration-folder-protocol.md explorations/
Exploration Fast-Track exploration-fast-track.md explorations/
Content Invariants content-invariants.md .tex, .qmd, Preambles/, scripts/R/**
Cross-Artifact Review cross-artifact-review.md master_supporting_docs/, .tex, .qmd
Summary–Body Parity summary-parity.md CHANGELOG.md, README.md, .qmd, skill/rule/agent .md
Post-Flight Verification post-flight-verification.md skills that generate factual claims (/lit-review, /research-ideation, /respond-to-referees, /review-paper, /interview-me)
Model Routing model-routing.md .claude/agents/**/*.md, .claude/skills/**/SKILL.md — 70/20/10 architect/editor split, per-agent model: field guidance (v1.9.0)
Review Fencing review-fencing.md .claude/agents/**/*.md, .claude/skills/**/SKILL.md — reviewer independence as a property of the environment: neutral copy outside the checkout, prior verdicts withheld, own reading before prior findings, positive controls fenced from committed answer keys (v2.5.1)
Stata Code Conventions stata-code-conventions.md **/*.do, scripts/stata/** — header scaffold, numbered pipeline, esttab tables, clustering discipline, AEA compliance (v1.9.0)
Simulation Conventions simulation-conventions.md **/*simulation*.R, **/*_sim.R, explorations/** — Monte Carlo discipline: DGP/estimand, L’Ecuyer seeding, Monte Carlo SE, coverage-vs-truth, raw-result storage (v1.10.0); assumption-regime discipline — a per-script header naming the estimand, the maintained assumptions, the single one being relaxed, and how correct specification was verified, plus the in-/out-of-assumption firewall and relax-exactly-one over a severity grid (v2.5.1)
R Package Conventions r-package-conventions.md R/**, tests/**, DESCRIPTION, NAMESPACE, man/** — package-source standards: no library() in R/, roxygen NAMESPACE, Imports/Suggests, testthat 3e, CRAN policy (v1.10.0)
Confidential Data confidential-data.md restricted/confidential data paths — no raw confidential data in git, disclosure-avoidance discipline, used by /disclosure-check / /replication-package / /data-management-plan (v2.0)

8.4 Hooks

Hook Type Configuration
Session log auto-writer Stop (command) .claude/hooks/log-reminder.py — auto-writes the session log on every meaningful change-set (no longer merely a reminder)
Desktop notification Notification (command) .claude/hooks/notify.sh
Context state capture PreCompact (command) .claude/hooks/pre-compact.py — DRAFT-block default is ON
Context restoration SessionStart[compact|resume] (command) .claude/hooks/post-compact-restore.py
Context monitor PostToolUse[Bash|Agent|Task] (command) .claude/hooks/context-monitor.py
Git guardrails PreToolUse (command) .claude/hooks/git-guardrails.py — blocks reset --hard / clean -f / push --force / add -A; refuses merge / rebase / pull on a dirty tree, including chains that would clean it first (ALLOW_DIRTY_MERGE=1)
Claim reconcile PostToolUse (command) .claude/hooks/claim-reconcile.py — flags stale numeric claims when scripts change, including edits to a declared appears_in display
Root-of-trust guard PreToolUse (command) .claude/hooks/root-of-trust-guard.py — best-effort tripwire against silent shell writes to .claude/settings*.json, .claude/hooks/, .githooks/, plus the destructive-git deny list applied to bash -c / env -S payloads; reads and Edit/Write still pass, so it changes the channel rather than locking the files (ALLOW_ROOT_OF_TRUST_WRITE=1)

Additional hook events available in Claude Code (not used in this template but available for custom hooks):

Event When It Fires Use Case
UserPromptSubmit Before user message is processed Input validation, auto-routing
PermissionRequest When permission dialog appears Auto-approve patterns, logging
PostToolUseFailure When a tool call fails Error tracking, retry logic
SubagentStart When a subagent spawns Resource tracking
SubagentStop When a subagent completes Result aggregation
PostCompact After context compaction Post-compaction cleanup
SessionEnd When session closes Final state saving, cleanup
WorktreeCreate When a git worktree is created Branch tracking
WorktreeRemove When a git worktree is removed Cleanup verification
TaskCompleted When a background task finishes Progress notifications
ConfigChange When settings are modified Audit logging

8.5 Troubleshooting

8.5.1 LaTeX Won’t Compile

Symptom: xelatex errors or missing packages.

Fix: 1. Check you have XeLaTeX installed: which xelatex 2. Ensure TEXINPUTS includes Preambles/: the /compile-latex skill handles this 3. Missing package? Install via TeX Live: tlmgr install [package]

8.5.2 Quarto Won’t Render

Symptom: quarto render fails or produces broken HTML.

Fix: 1. Check Quarto version: quarto --version (need 1.3+) 2. Check for syntax errors in YAML frontmatter 3. Missing TikZ SVGs? Run /extract-tikz first

8.5.3 Hooks Not Firing

Symptom: No context warnings, no auto-written session log, no git guardrails firing.

Fix: 1. Check hooks are configured: cat .claude/settings.json | grep hooks 2. Ensure Python 3 is available: which python3 3. Check hook file permissions: ls -la .claude/hooks/

8.5.4 Claude Ignores Rules

Symptom: Claude doesn’t follow conventions in .claude/rules/.

Fix: 1. Rules use paths: frontmatter — check the path matches your files 2. Too many rules? Claude follows ~150 instructions reliably. Consolidate. 3. Try: “Read .claude/rules/[rule].md and follow it for this task”

8.5.5 Context Lost After Compaction

Symptom: Claude forgets what you were working on.

Fix: 1. Point Claude to the plan: “Read quality_reports/plans/[latest].md” 2. Check session log: “Read quality_reports/session_logs/[latest].md” 3. The post-compact-restore.py hook should print recovery info automatically

8.5.6 Quality Score Too Low

Symptom: Score stuck below 80, can’t commit.

Fix: 1. Run /slide-excellence to get detailed issue breakdown 2. Fix critical issues first (they cost -10 to -20 points each) 3. Ask Claude: “What are the remaining critical issues?”

8.5.7 Skills Not Auto-Invoked

Symptom: Claude doesn’t use skills when you describe a task.

Fix: 1. Be explicit in your request: “Review my slides for grammar and layout issues” 2. Check skill has auto-invocation enabled (no disable-model-invocation: true) 3. Skill descriptions help Claude know when to use them — check they’re clear

8.5.8 Plans Saved to Wrong Directory

Symptom: Plans save to ~/.claude/plans/ instead of your project directory. Can’t track plans in git.

Fix: Add to .claude/settings.json:

{
  "plansDirectory": "quality_reports/plans"
}

This tells Claude Code to save plans inside your project where they can be version-controlled.

9 Standing on Shoulders

This guide builds on the work of many. We are grateful to these projects and their authors.

Core Infrastructure:

  • Claude Code by Anthropic — the CLI tool, VS Code extension, and Desktop app that makes all of this possible

Research Workflows:

  • clo-author by Hugo Sant’Anna (UAB) — paper-centric research workflows with adversarial agent pairs, simulated peer review, and full research lifecycle management
  • claudeblattman by Chris Blattman (University of Chicago) — comprehensive workflows for non-technical academics: executive assistant, proposal writing, project management, and the fresh-context critique pattern

Reproducibility & Data Management:

Presentation Design & Tools:

  • MixtapeTools / The Rhetoric of Decks by Scott Cunningham (Baylor) — the philosophical and practical framework for beautiful, rhetorically effective academic presentations
  • Scott Cunningham, Causal Inference: The Mixtape — the textbook whose author developed the presentation framework above
  • autoresearch by Andrej Karpathy — constraint-based autonomous research with program.md as constitutional document
  • ClaudeCodeTools — “The Editor” persona for seven-audit sequential paper review

Origin:

  • This workflow was extracted from Econ 730: Causal Panel Data at Emory University, developed by Pedro Sant’Anna. The econometrics origin is one application — the patterns are domain-agnostic and have been extended by others across fields.