Command Reference

Every command, what it dispatches, and what it produces

Quick Lookup

Command Flags / Modes What It Does
/new-project [topic] Full orchestrated pipeline: idea to paper
/discover interview, lit, data, ideate Discovery phase: interview, literature, data, ideation
/strategize strategy, pap, pap interactive, theory Empirical strategy, pre-analysis plan, or formal theory section
/analyze [dataset] --dual [langs] End-to-end data analysis (single or parallel language)
/write [section] intro, strategy, results, conclusion, data, model, abstract, full, humanize, style-guide Draft sections, strip AI patterns, or extract personal voice
/review [file] --peer [journal], --peer --r2, --stress [journal], --methods, --theory, --proofread, --code, --replicate [lang], --all Quality reviews (routes by target + flags)
/revise [report] R&R cycle: classify + route referee comments
/talk create, audit, compile; formats: job-market, seminar, short, lightning; --beamer Presentations (Quarto RevealJS default, Beamer opt-in)
/submit target, package, audit, final Submission pipeline
/tools commit, compile, validate-bib, lint, journal, context, deploy, learn, dashboard, upgrade Utilities
/checkpoint --auto, --memory-only, --scaffold-only, --dry-run, --setup-obsidian Session handoff: memory + logs + Obsidian
/freeze [dirs] off Block edits outside specified directories for this session
/careful off Block destructive bash commands for this session

Detailed Skill Reference

/new-project

Syntax: /new-project [topic] or /new-project interactive

What happens:

  1. Enter plan mode. Create the folder scaffold (data/, scripts/, paper/, quality_reports/). Draft a high-level plan and save it to quality_reports/plans/. Wait for user approval.
  2. Run /discover interview to produce the research specification and domain profile.
  3. Run /discover lit and /discover data in parallel — librarian and explorer agents search for literature and datasets.
  4. Run /strategize to design the identification strategy. If the paper type calls for formal theory, also run /strategize theory.
  5. Run /analyze and /write to implement the strategy in code and draft the manuscript.
  6. Run /review --all and /review --peer for quality scoring and simulated peer review.
  7. Optionally run /submit for journal targeting and replication packaging.

Modes / Flags: None. This skill is always orchestrated through the full pipeline.

Agents dispatched:

Phase Agents Gate
Discovery Direct interview; librarian + librarian-critic; explorer + explorer-critic Research spec exists
Strategy Strategist + strategist-critic; optionally theorist + theorist-critic Score >= 80
Execution Data-engineer + coder + coder-critic; writer Score >= 80
Peer Review Editor + domain-referee + methods-referee; all critics in parallel Editorial decision
Submission Coder + verifier; orchestrator Score >= 95, all components >= 80

Output artifacts:

  • quality_reports/research_spec_[topic].md
  • .claude/references/domain-profile.md
  • quality_reports/strategy_memo_[topic].md
  • scripts/R/ (analysis scripts)
  • paper/sections/ (LaTeX drafts)
  • quality_reports/reviews/ (referee reports)

What to do next: The pipeline pauses at each phase transition for your approval. Review the research spec, strategy memo, analysis results, and referee feedback at each gate before proceeding.


/discover

Syntax: /discover [mode] [topic or query]

What happens:

  1. Detect mode from arguments: interview (default), lit, data, or ideate.
  2. Read .claude/references/domain-profile.md for field calibration.
  3. Dispatch the appropriate agent(s).
  4. Run the paired critic (for lit and data modes).
  5. Save outputs to quality_reports/.

Modes / Flags:

Mode Description
interview (default) Structured 5–8 exchange conversation to formalize a research idea
lit [topic] Literature search with citation chains, proximity scores (1–5), and critic review
data [question] Dataset discovery with feasibility grades (A/B/C/D) and 5-point critique
ideate [topic] Generate 3–5 ranked research questions with strategies

Agents dispatched:

Mode Agents Output Path
interview Direct conversation (no agent dispatch) quality_reports/research_spec_[topic].md, .claude/references/domain-profile.md, quality_reports/decisions/discovery_[topic].md
lit Librarian + librarian-critic quality_reports/lit_review_[topic].md + HTML report + BibTeX entries
data Explorer + explorer-critic quality_reports/data_exploration_[topic].md
ideate Direct generation quality_reports/research_ideas_[topic].md

Output artifacts:

  • Interview: Research specification, domain profile (if still template), decision record documenting rejected alternatives.
  • Literature: Annotated bibliography with proximity scores, BibTeX entries, frontier map, interactive HTML report. Unverified citations marked % UNVERIFIED.
  • Data: Ranked dataset list with feasibility grades. Each dataset assessed on measurement validity, sample selection, external validity, identification compatibility, and known issues. Includes a rejection table for discarded datasets.
  • Ideation: 3–5 research questions ranked by feasibility and novelty, each with a candidate identification strategy.

What to do next: After interview, review the research spec and confirm it matches your vision. After lit or data, check coverage gaps flagged by the critic. Proceed to /strategize once discovery outputs exist.


/strategize

Syntax: /strategize [mode] [question or spec path]

What happens:

  1. Read discovery outputs (research spec, literature review, data assessment) and domain profile.
  2. Output a mandatory Pre-Strategy Report (or Pre-Theory Report) proving inputs were loaded.
  3. Dispatch the creator agent (Strategist or Theorist).
  4. Dispatch the paired critic for adversarial review (4 sequential phases, early-stop on critical gaps).
  5. Iterate up to 3 rounds if critical issues found.
  6. Save the memo, review, and decision record.

Modes / Flags:

Mode Description
strategy (default) Design identification strategy for any of the 4 paper types
pap [spec] Draft pre-analysis plan in AEA/OSF/EGAP format
pap interactive Guided 6-question PAP interview, then draft
theory [target] Formal theory section: assumptions, theorems, proofs

Agents dispatched:

Mode Agents Output Path
strategy Strategist + strategist-critic quality_reports/strategy_memo_[topic].md, quality_reports/strategy_memo_[topic]_review.md, quality_reports/decisions/strategy_[topic].md
pap Strategist (PAP mode); optionally strategist-critic quality_reports/pre_analysis_plan_[topic].md
theory Theorist + theorist-critic quality_reports/theory/[topic]/theory_memo.md, assumptions.tex, results.tex, proofs.tex, notation_glossary.md

Output artifacts:

  • Strategy: Strategy memo (design choice, estimand, assumptions, pseudo-code, robustness plan, falsification tests, top 5 referee objections). Decision record with rejected alternatives and invalidation conditions. HTML report.
  • PAP: Full pre-analysis plan with 10 standard sections. Platform-adapted for AEA/OSF/EGAP. ASSUMED placeholders flagged with a pre-registration checklist. Adapted for observational studies when applicable.
  • Theory: Theory memo, LaTeX files for assumptions/results/proofs, notation glossary. Decision record linking each theorem to its empirical claim. Theorist-critic score contributes 20% to weighted aggregate when present.

What to do next: Review the strategy memo carefully — it becomes the contract the Coder implements. Confirm the identification strategy, assumptions, and robustness plan. For theory mode, verify proof correctness and assumption minimality before proceeding.


/analyze

Syntax: /analyze [dataset path or goal] or /analyze --dual r,python

What happens:

  1. Output a mandatory Pre-Code Report proving the strategy memo, domain profile, and naming map were loaded.
  2. If raw data provided, dispatch Data-engineer for cleaning, variable construction, and summary statistics.
  3. Dispatch Coder for the main specification, robustness checks, and publication-ready output.
  4. Dispatch coder-critic for the full 12-category review.
  5. Iterate up to 3 rounds on critical or major issues.
  6. Present results summary with estimates, scripts, outputs, and code review score.

Modes / Flags:

Mode Description
default Single-language analysis (R by default, or as declared in CLAUDE.md)
--dual [lang1,lang2] Parallel analysis in two languages with cross-language comparison

Agents dispatched:

Mode Agents Output Path
default Data-engineer + Coder + coder-critic scripts/R/, paper/tables/, paper/figures/, quality_reports/results_summary.md
--dual Data-engineer + 2 Coders (parallel) + 2 coder-critics + comparison Same as above for both languages + quality_reports/cross_language_comparison.md

Output artifacts:

  • Numbered scripts in scripts/R/ (or language-appropriate directory) following the standard layout: 00_master, 01_setup, 02_data_preparation, 03_descriptive, 04_estimation, 05_robustness, 06_figures, 07_tables.
  • Publication-ready tables (.tex) in paper/tables/. Bare tabular environments only — no \begin{table} wrappers.
  • Publication-ready figures (.pdf) in paper/figures/. No titles inside figures.
  • results_summary.md with all point estimates, standard errors, sample sizes, and anomaly flags. This is the mandatory handoff artifact to the Writer.
  • .rds files for every computed object (model fits, cleaned data, summary statistics).
  • Code review report in quality_reports/.

What to do next: Read results_summary.md to understand the findings. Check that estimates align with your expectations. Review the code review report for any unresolved issues. Proceed to /write to draft the paper.


/write

Syntax: /write [section or mode] [file path]

What happens:

  1. Read all available context: existing draft, research spec, strategy memo, domain profile, bibliography, generated tables and figures, results_summary.md.
  2. Detect paper type (reduced-form, structural, theory+empirics, descriptive) from the strategy memo.
  3. Load personal style guide from .claude/references/personal-style-guide.md if it exists.
  4. Dispatch Writer with type-specific section templates and paragraph-level argument moves.
  5. Run cleanup pass to strip AI writing patterns.
  6. Present through drafting gates, pausing for approval.

Modes / Flags:

Mode Description
intro Introduction with type-specific moves (preview, result, contribution)
strategy Empirical strategy (reduced-form), model + estimation (structural), or model + tests (theory+empirics)
results Results narration adapted to output type (tables, event studies, counterfactuals)
conclusion Conclusion with type-appropriate ending
data Data section (expanded for descriptive papers)
model Model section (structural or theory+empirics only)
abstract Abstract, 100–150 words (requires other sections first)
full All sections in sequence with 3 drafting gates
humanize [file] Strip 24 AI writing patterns without rewriting content
style-guide [dir] One-shot extraction of personal voice from prior papers

Agents dispatched:

Mode Agent Output Path
[section] / full Writer paper/sections/[section].tex
humanize Writer (cleanup mode) Edited file in place
style-guide Writer (style-extraction mode) .claude/references/personal-style-guide.md

Output artifacts:

  • LaTeX section files in paper/sections/.
  • Claim-source map in quality_reports/claim_source_map_[project].md linking every numerical claim to its source table, figure, or computation.
  • Personal style guide (for style-guide mode) documenting sentence-length distribution, passive-voice frequency, lexicon patterns, and citation conventions.

What to do next: Review each drafted section for accuracy and voice. The Writer uses TBD placeholders for missing results — fill these in or re-run after /analyze completes. Run /review --proofread for manuscript polish, or /review --peer for simulated peer review.


/review

Syntax: /review [file path or --flag] [journal]

The most polymorphic skill in the system. Routing depends on file type and flags.

What happens:

  1. Detect review mode from arguments: auto-detect by file extension, or use explicit flag.
  2. Dispatch the appropriate critic agent(s).
  3. Run mechanical lint (for code reviews) before the judgment review.
  4. Produce scored reports. Critics never edit files — they produce reports only.
  5. Save reports to quality_reports/ with HTML versions and dashboard refresh.

Modes / Flags:

Flag Description
(auto .tex paper) Comprehensive review: writer-critic + strategist-critic + verifier in parallel
(auto .R/.py/.jl) Code review: coder-critic standalone (categories 4–12)
(auto .tex in talks/) Talk review: storyteller-critic
--peer [journal] Full simulated peer review: editor desk review, referee dispatch, editorial decision
--peer --r2 [journal] R&R round 2: same referees remember prior reports
--stress [journal] Hostile stress test: adversarial dispositions, double critical pet peeves
--methods [file] Causal audit only: strategist-critic 4-phase review
--theory [file] Proof audit only: theorist-critic 4-phase review (logical validity, assumption minimality, citations, linkage)
--proofread [file] Manuscript polish only: writer-critic 6-category review
--code [file] Code review only: coder-critic categories 4–12 (no strategy comparison)
--replicate [lang] Cross-language replication: re-implement in target language, compare outputs
--all All critics in parallel + weighted aggregate score

Flag combinations: --peer and --r2 combine (for R&R second round). --peer and --stress are mutually exclusive — --stress replaces the peer flow with adversarial dispositions. All other flags are standalone and do not combine.

Agents dispatched:

Flag Agents Output Path
(auto .tex) writer-critic + strategist-critic + verifier quality_reports/
(auto code) coder-critic quality_reports/[file]_code_review.md
--peer Editor + domain-referee + methods-referee (3 sequential phases) quality_reports/reviews/YYYY-MM-DD_desk_review.md, _referee_domain.md, _referee_methods.md, _editorial_decision.md
--peer --r2 Same referees (reload dispositions from round 1) quality_reports/reviews/ with _r2 suffix
--stress Editor + 2 adversarial referees (SKEPTIC disposition, 2 critical pet peeves each) quality_reports/reviews/
--methods strategist-critic quality_reports/[file]_strategy_review.md
--theory theorist-critic quality_reports/theory_[topic]_review.md
--proofread writer-critic quality_reports/[file]_proofread_report.md
--code coder-critic quality_reports/[file]_code_review.md
--replicate Coder (replication) + coder-critic Replicated script + comparison report
--all All critics in parallel (theorist-critic included when theory section exists) quality_reports/ + weighted aggregate score

Peer review details: The editor reads the paper and decides DESK REJECT or SEND TO REFEREES. If sent, the editor assigns each referee a disposition (STRUCTURAL, CREDIBILITY, MEASUREMENT, POLICY, THEORY, or SKEPTIC) plus one critical and one constructive pet peeve from the journal’s referee pool. Both referees review independently and blind. Every major comment must include “what would change my mind.” The editor then classifies each concern as FATAL, ADDRESSABLE, or TASTE and produces an editorial decision: Accept / Minor Revisions / Major Revisions / Reject. When a journal name is provided, the entire flow calibrates to that journal’s profile.

R&R rounds: Round 2 skips desk review. Same referees check whether each prior concern was resolved, partially resolved, or not addressed. Round 3 (max) allows Accept, Minor, or Reject only.

Scoring:

Mode Blocking? Gate
Comprehensive Yes 80 commit, 90 PR
Peer Review Yes Editorial decision
Stress Test Advisory Non-blocking
Code Review Yes 80 commit
Causal Audit Yes 80 commit
Proofread Yes (paper), advisory (talks) 80 commit

What to do next: Read the reports. For peer review, address MUST items first, then SHOULD items. For code review, fix critical and major issues, then re-run. For --all, check which components are below 80 and focus there.


/revise

Syntax: /revise [referee-report-path] [paper-path]

What happens:

  1. Read the referee report(s) and the current paper.
  2. Classify every referee comment into one of 5 categories.
  3. Build a tracking document with counts and priorities.
  4. Dispatch agents for routable items (Writer for text changes, flag Coder tasks for user approval).
  5. Draft a point-by-point LaTeX response letter.
  6. Flag all DISAGREE items for mandatory user review.

Modes / Flags: None. This skill handles real R&R responses (not simulated reviews — use /review --peer for that).

Agents dispatched:

Classification Routed To Action
NEW ANALYSIS Coder (flagged for user approval first) Create analysis task
CLARIFICATION Writer Draft rewritten section
REWRITE Writer Structural revision
DISAGREE User (mandatory) Diplomatic pushback drafted, flagged for review
MINOR Writer Fix directly

Output artifacts:

  • quality_reports/referee_response_tracker.md — summary counts, action items by priority (HIGH/MEDIUM/FLAGGED/LOW)
  • quality_reports/referee_response_[journal]_[date].tex — LaTeX response letter with referee quotes, color-coded responses, page references
  • Revised section files in paper/sections/ (for CLARIFICATION and REWRITE items)

What to do next: Review all DISAGREE items — these require your judgment. Approve NEW ANALYSIS tasks before they execute. Check the response letter tone matches your voice. Proceed to /review --peer --r2 to simulate the next referee round.


/talk

Syntax: /talk [mode] [format] [--beamer] [file]

Quarto RevealJS is the default output format. Beamer is available via --beamer for departments or conferences that require PDF slides.

What happens:

  1. Parse mode (create, audit, compile) and format (job-market, seminar, short, lightning).
  2. For create: read the paper, extract key content, dispatch Storyteller to build the slide file, then dispatch storyteller-critic for review.
  3. For audit: run visual quality checks on existing slides.
  4. For compile: run quarto render (default) or latexmk (Beamer).

Modes / Flags:

Mode Description
create job-market 40–50 slides, 45–60 min, full story (Quarto RevealJS)
create seminar 25–35 slides, 30–45 min, motivation + main result + robustness
create short 10–15 slides, 15 min, question + method + key result
create lightning 3–5 slides, 5 min, hook + one result + so-what
create [format] --beamer Beamer LaTeX instead of Quarto RevealJS
audit [file] Visual layout check (overflow, fonts, sizing)
compile [file] Quarto or XeLaTeX compilation

Agents dispatched:

Mode Agents Output Path
create Storyteller + storyteller-critic paper/quarto/[format]_talk.qmd
create --beamer Storyteller + storyteller-critic paper/talks/[format]_talk.tex
audit Visual checks (no agent dispatch) Advisory report
compile Compilation only Compiled HTML or PDF

Output artifacts:

  • Quarto .qmd (default) or Beamer .tex file.
  • Storyteller-critic review in quality_reports/[format]_talk_review.md.
  • Talk scores are advisory (non-blocking).

What to do next: Review the generated slides against your paper. Check that all claims are traceable to the manuscript. Run /talk audit to catch overflow and sizing issues. Compile with /talk compile.


/submit

Syntax: /submit [mode] [journal]

What happens:

  1. Detect mode from arguments: target, package, audit, or final.
  2. For target: analyze contribution and recommend journals.
  3. For package: build AEA-compliant replication package with master script and documentation.
  4. For audit: run 10-point replication verification.
  5. For final: run comprehensive review + replication audit + score gate enforcement.

Modes / Flags:

Mode Description
target Rank 3 journals by contribution fit, methodology fit, audience, desk rejection risk
package Build replication package: master script, README, data docs, codebook
audit 10-check verification of replication package
final [journal] Full gate: score >= 95, all components >= 80. Produces cover letter or blocks with issues

Agents dispatched:

Mode Agents Output Path
target Orchestrator (journal selection) quality_reports/journal_recommendations_[date].md
package Coder + Verifier paper/replication/
audit Verifier (10 checks) Pass/fail audit report
final All agents + gate enforcement quality_reports/quality_gate_[date].md + HTML report

Output artifacts:

  • Target: Ranked journal list with rationale.
  • Package: Master script, README, data documentation, codebook in paper/replication/.
  • Audit: Pass/fail on 10 checks (master script runs, tables reproduce, figures reproduce, README complete, data docs present, numbered script order, dependencies listed, runtime documented, output paths match, no hardcoded paths).
  • Final: Quality gate report. If PASS: cover letter draft + submission checklist. If FAIL: blocking issues listed.

What to do next: For target, pick a journal and confirm before proceeding. For package, run audit to verify completeness. For final, if it passes, review the cover letter draft and submit. If it fails, fix blocking issues and re-run.


/tools

Syntax: /tools [subcommand] [args]

Each subcommand is lightweight — no multi-agent orchestration.

Subcommands:

Subcommand Description
commit [message] Stage changes, create commit. Notes quality score if available. Never stages .env or credentials.
compile [file] LaTeX compilation via latexmk. Routes to paper/ or paper/talks/ based on file location.
validate-bib Cross-reference all \cite{} keys against Bibliography_base.bib. Reports missing, unused, and duplicate entries.
lint [file\|dir] Grep-based mechanical linting for R/Python/Julia against prohibited patterns. Catches setwd(), absolute paths, missing seed, T/F literals, sapply(), and more. Severity-graded (HIGH/MEDIUM/LOW). Always advisory.
journal Regenerate the research journal timeline from quality reports and git history.
context Show current context usage and session health. Check whether auto-compact is approaching.
dashboard [--open] Regenerate the project dashboard HTML. Opens in browser by default.
deploy Render Quarto guide site and publish to GitHub Pages.
learn Extract reusable knowledge from the current session into auto-memory.
upgrade Upgrade .claude/ to the latest clo-author release. Preserves domain profile, custom journal profiles, and settings. Does not touch paper/, scripts/, data/, or any user content.

What to do next: Run validate-bib before commits to catch broken citations. Run lint before /review --code to clear mechanical violations. Run dashboard after any significant work to refresh the project overview.


/freeze

Syntax: /freeze [dirs] or /freeze off

Session-scoped edit guard. Blocks Write and Edit operations on files outside the specified directories.

What happens:

  1. Parse directory arguments from the command.
  2. Write guard configuration to .claude/state/session-guards.json.
  3. The session-guard.py PreToolUse hook enforces the restriction on every subsequent Edit or Write.
  4. Confirm what is frozen and what remains editable.

Examples:

Command Effect
/freeze paper/ Only allow edits in paper/
/freeze scripts/ data/ Only allow edits in scripts/ and data/
/freeze off Deactivate — all paths editable again

Behavior:

  • .claude/ is always editable regardless of freeze scope (we cannot freeze ourselves out of configuration changes)
  • Paths are relative to the project root
  • Session-scoped — resets when the conversation ends
  • Only blocks Claude’s Edit and Write tools, not the user’s editor

When to use: During focused writing sessions (freeze everything except paper/), during code review (freeze everything except notes), or when editing data pipelines (freeze paper/ to prevent accidental manuscript changes).


/careful

Syntax: /careful or /careful off

Session-scoped destructive command guard. Blocks Bash commands matching dangerous patterns before they execute.

What happens:

  1. Write guard configuration to .claude/state/session-guards.json.
  2. The session-guard.py PreToolUse hook tests every Bash command against destructive patterns.
  3. Matching commands are blocked with an explanation.

Blocked patterns:

Pattern What It Catches
rm -rf / rm -r Recursive force delete
git reset --hard Discard all uncommitted changes
git push --force / -f Overwrite remote history
git clean -f Delete untracked files
git checkout -- . Discard all working tree changes
git branch -D Force-delete branch
DROP TABLE / DROP DATABASE SQL destruction
chmod 777 Overly permissive permissions

Behavior:

  • Session-scoped — resets when the conversation ends
  • Only blocks Claude’s Bash tool, not the user’s terminal
  • Non-destructive commands pass through without delay
  • rm without -rf (single file deletion) is still allowed

When to use: Before deadlines, on critical branches, or whenever an extra safety net is worth the occasional blocked command. The cost is near-zero — the hook only fires on Bash calls, and pattern matching takes microseconds.


/checkpoint

Syntax: /checkpoint [--flag]

What happens:

  1. Gather context: run git log, git diff, scan today’s plans and session logs.
  2. Detect Obsidian configuration (.claude/state/obsidian-config.md).
  3. Draft a compact checkpoint summary: what happened, memory updates, scaffold updates, Obsidian updates.
  4. Present for user confirmation (one prompt, not five).
  5. Save to all targets in parallel: auto-memory, SESSION_REPORT, research journal, Obsidian (if configured), dashboard refresh.
  6. Confirm what was saved.

Flags:

Flag Effect
--auto Skip user confirmation, save immediately
--memory-only Only update Claude Code auto-memory
--scaffold-only Memory + SESSION_REPORT + research journal, skip Obsidian
--dry-run Show what would be saved without saving
--setup-obsidian Walk through creating .claude/state/obsidian-config.md from the example template

Agents dispatched: None. This is a direct operation with no agent dispatch.

Output artifacts:

  • ~/.claude/projects/.../memory/ — auto-memory files for future conversations.
  • SESSION_REPORT.md (project root) — append-only session log entry.
  • quality_reports/research_journal.md — agent-invocation trail (only if agent work happened).
  • Obsidian vault updates (only if configured): project-note journal entry, dashboard row, daily journal.
  • Refreshed project_dashboard.html.

What to do next: Run this before /compact, before ending a session, or whenever the user says “checkpoint,” “save progress,” or “wrap up.” The next session reads these artifacts to resume context.