User Guide

Common workflows and what to expect

A Typical Workflow

Every interaction follows the same loop: you describe, agents execute, critics score, you approve. Claude plans the work, dispatches specialized agents, and presents results for your sign-off. For complex tasks, it asks 3–5 clarifying questions before committing to a plan.

%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#f0eee6', 'primaryTextColor': '#141413', 'primaryBorderColor': '#d1cfc5', 'lineColor': '#d97757', 'secondaryColor': '#faf9f5', 'tertiaryColor': '#e6e3da', 'edgeLabelBackground': '#faf9f5', 'clusterBkg': '#f0eee6', 'clusterBorder': '#d1cfc5'}}}%%
flowchart LR
    D(Discovery<br/>Literature + Data):::phase1 --> S(Strategy<br/>Identification Design):::phase2
    S --> E(Execution<br/>Code + Paper):::phase3
    E --> R(Review<br/>Simulated Peer Review):::phase4
    R -->|score >= 95| SUB(Submission<br/>Package + Gate):::phase5

    classDef phase1 fill:#f0eee6,stroke:#788c5d,color:#141413,stroke-width:2px
    classDef phase2 fill:#f0eee6,stroke:#4d7c5a,color:#141413,stroke-width:2px
    classDef phase3 fill:#f0eee6,stroke:#d97757,color:#141413,stroke-width:2px
    classDef phase4 fill:#f0eee6,stroke:#b85c3e,color:#141413,stroke-width:2px
    classDef phase5 fill:#f0eee6,stroke:#87867f,color:#141413,stroke-width:2px

You can enter at any stage. Each phase produces structured output saved to quality_reports/.

Your First Review

Simulated peer review catches fatal problems before real referees do. One command dispatches two independent reviewers calibrated to your target journal.

What you type: /review --peer JHR paper/main.tex

What happens behind the scenes: The editor does a desk review — checks scope, assigns each referee a disposition (Credibility, Policy, Skeptic, etc.) and pet peeves that shape their review personality. Two blind referees then review independently: a domain-referee (subject expertise) and a methods-referee (empirical methods). Neither sees the other’s report.

What you see: An editorial decision that classifies every concern as FATAL, ADDRESSABLE, or TASTE:

# Editorial Decision --- Journal of Human Resources
**Decision:** Major Revisions

## Referee 1 (domain-referee) --- Disposition: Policy
- ADDRESSABLE: Missing discussion of policy implementation costs (Section 6)
- ADDRESSABLE: Literature review omits Garcia & Santos (2024) on same population
- TASTE: Prefer confidence intervals over p-values

## Referee 2 (methods-referee) --- Disposition: Credibility
- FATAL: Pre-trends test shows significant coefficient at t-2 (Figure 3)
- ADDRESSABLE: Clustering at state level with 12 states --- use wild bootstrap
- ADDRESSABLE: No sensitivity analysis (Rambachan & Roth 2023)

## Action Items
- MUST: Address pre-trends concern (fatal if unresolved)
- MUST: Add wild bootstrap standard errors
- SHOULD: Add sensitivity bounds
- SHOULD: Cite Garcia & Santos (2024)

What to do next: Work through MUST items first. Use /revise to route each comment to the right agent — new analysis goes to the coder, clarifications go to the writer, disagreements get flagged for your review. For more on the peer review architecture (dispositions, pet peeves, journal calibration), see Agents.

Your First Draft

What you type: /write intro

What happens behind the scenes: Claude reads your paper type (reduced-form, structural, descriptive, or theory+empirics), your strategy memo, and any existing sections. The writer drafts using paragraph-level argument moves — each paragraph has one job:

Paragraph 1 [MOTIVATION]: Big question --- why this matters for policy
Paragraph 2 [GAP]: What the literature hasn't answered
Paragraph 3 [THIS PAPER]: "We estimate..." --- result preview with magnitude
Paragraph 4 [IDENTIFICATION]: Source of variation, one-sentence design
Paragraph 5 [PREVIEW]: Key finding with effect size
Paragraph 6 [ROADMAP]: Section-by-section guide

A cleanup pass then strips 24 known AI writing patterns (hedging, filler phrases, over-signposting). The argument structure adapts to your paper type — reduced-form leads with identification and result, structural leads with the model and counterfactual, descriptive leads with the data innovation and key fact.

What you see: A LaTeX section file saved to paper/sections/intro.tex, plus a claim-source map linking every numerical claim to a specific script and output file.

What to do next: Review for accuracy and voice. If you have prior papers, run /write style-guide [dir] first to calibrate the writer to your voice. For all available sections and flags, see the Command Reference.

Running the Full Pipeline

What you type: /new-project [topic]

What happens behind the scenes: The pipeline runs through all five phases, pausing for your approval at each transition:

  1. Discovery — librarian and explorer run in parallel, searching for literature and datasets. Their critics review coverage and feasibility. You see an annotated bibliography and ranked dataset list.
  2. Strategy — the strategist classifies your paper type and designs the identification strategy. The strategist-critic runs a 4-phase adversarial review. You see a strategy memo with assumptions, pseudo-code, and a robustness plan.
  3. Execution — the coder translates the strategy memo into numbered scripts; the writer drafts the manuscript from actual results. Both are reviewed by their paired critics. You see scripts, tables, figures, and LaTeX sections.
  4. Review — the editor dispatches two blind referees. You see an editorial decision with classified concerns and action items.
  5. Submission — the verifier runs a 10-check audit on the replication package. The final gate enforces score >= 95 with all components >= 80.

What you see: At each gate, a summary with scores and the next decision point. The pipeline never advances without your approval.

What to do next: Read the strategy memo carefully — it becomes the contract the coder implements. Review referee reports as you would real ones. For details on any phase, see the Command Reference.

Revising After Referee Reports

What you type: /revise [referee-report.pdf]

What happens behind the scenes: Each referee comment is classified into one of five categories and routed to the appropriate agent:

Classification Routed to Example
NEW ANALYSIS Coder (flagged for your approval first) “Control for X” or “Show results by subgroup”
CLARIFICATION Writer “Explain your exclusion restriction more clearly”
REWRITE Writer “Restructure Section 4”
DISAGREE You (mandatory review) “Your identification assumption is violated”
MINOR Writer Typos, formatting, citation additions

What you see: A tracking document with counts and priorities, plus a draft point-by-point LaTeX response letter. DISAGREE items are always flagged — Claude never autonomously pushes back on referees.

What to do next: Review DISAGREE items and decide your response. Approve NEW ANALYSIS tasks before they execute. Run /review --peer --r2 to simulate the next referee round with the same dispositions.

Creating a Talk

A talk is not a paper read aloud — it is a narrative with a different arc. The storyteller agent builds format-aware slide decks that respect this distinction.

What you type: /talk create seminar

What happens behind the scenes: The storyteller reads your paper and builds a slide deck in the specified format (seminar: 25–35 slides, 30–45 min). It applies format-specific narrative arcs — reduced-form talks lead with the policy question, structural talks build the model step by step, descriptive talks open with the data innovation. The storyteller-critic reviews for overflow, content fidelity, and narrative flow.

What you see: A Quarto RevealJS .qmd file in paper/quarto/ with speaker notes on every slide, plus a critic review report. Talk scores are advisory — they do not block commits.

What to do next: Review the slides against your paper. Run /talk audit to catch text overflow and sizing issues. Run /talk compile to build the HTML presentation. For Beamer LaTeX output, add --beamer — that produces a .tex file in paper/talks/ instead. For all format options, see the Command Reference.

Session Guards

Two commands protect you from expensive mistakes. Both are session-scoped — they reset when the conversation ends.

/freeze paper/ locks a directory from edits for the rest of the session. Use it when you are reviewing code but jotting notes about the paper — the system will refuse to modify frozen paths, preventing accidental overwrites while your attention is elsewhere.

/careful activates confirmation prompts before every file write. Use it before working on a critical branch, during final pre-submission edits, or any time the cost of a wrong edit exceeds the cost of an extra confirmation step.

Neither command persists across sessions. Start a new conversation and all guards are cleared.

Quality Gates

Three thresholds govern what actions the system allows:

Gate Score required What it means
Commit >= 80 Work can be committed to the repository
PR >= 90 Work can be opened as a pull request
Submission >= 95 + all components >= 80 Work can be submitted to a journal

Scores are weighted aggregates of individual critic scores. Each critic starts at 100 and deducts for issues found. The system manages this automatically — you will rarely think about it unless a score drops below 80, which blocks commits until the flagged issues are fixed.

Recovering from a low score: Run /review --all to get a per-component breakdown. Fix critical issues first (they carry the largest deductions). Re-run the relevant review to update the score. For the full scoring formula and component weights, see Rules & Invariants.

Troubleshooting

LaTeX Won’t Compile

Symptom: latexmk or xelatex errors, missing packages.

  1. Check you have XeLaTeX and latexmk installed: which xelatex latexmk
  2. paper/latexmkrc configures TEXINPUTS and BIBINPUTS automatically
  3. Missing package? Install via TeX Live: tlmgr install [package]
  4. On Overleaf: set compiler to XeLaTeX via Menu > Compiler (Overleaf reads latexmkrc automatically)

Hooks Not Firing

Symptom: No file protection or context survival.

  1. Check hooks are configured in .claude/settings.json
  2. Ensure Python 3 is available: which python3
  3. Check hook file permissions: ls -la .claude/hooks/
  4. Hook blocking an edit you want to make? See Hooks & Automation for how to customize protected patterns.

Claude Ignores Rules

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

  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”

Context Lost After Compaction

Symptom: Claude forgets what you were working on.

  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. See Hooks & Automation for details.

Quality Score Too Low

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

  1. Run /review --all to get detailed issue breakdown
  2. Fix critical issues first (they cost the most points)
  3. Check per-component scores — one weak component can drag down the aggregate

Upgrading

Run /tools upgrade to upgrade your project to the latest clo-author version. It replaces .claude/ and templates/, preserving your paper, scripts, data, bibliography, and CLAUDE.md.

Note

Your files are safe. The upgrade only touches .claude/ (the infrastructure) and templates/. Your paper, scripts, data, bibliography, and all research content are never modified or deleted.

Manual alternative: Download the latest release, delete your .claude/ directory, and copy the new one in. Your CLAUDE.md stays yours — the infrastructure reads whatever paths you have there.