tools¶
paper-drafting
Tools¶
Utility subcommands for project maintenance and infrastructure.
Input: $ARGUMENTS — subcommand followed by any arguments.
Subcommands¶
/tools dashboard [--open] — Project Dashboard¶
Regenerate the project dashboard HTML file.
If --open is specified (or by default), open the dashboard in the browser:
The dashboard scans the entire project — paper sections, data, scripts, quality reports, bibliography, plans — and renders an interactive HTML overview. Regenerate it after any significant work.
/tools commit [message] — Git Commit¶
Stage changes, create commit, optionally create PR and merge. - Run git status to identify changes - Stage relevant files (never stage .env or credentials) - Create commit with descriptive message - If quality score available and >= 80, note in commit
/tools compile [file] — LaTeX Compilation¶
Automated multi-pass compilation via latexmk.
For papers:
For talks:
Note: paper/latexmkrc configures XeLaTeX, TEXINPUTS, and BIBINPUTS. Falls back to manual 3-pass if latexmk is unavailable.
/tools validate-bib — Bibliography Validation¶
Cross-reference all \cite{} keys in paper and talk files against Bibliography_base.bib. Report: missing entries, unused entries, duplicate keys.
/tools lint [file|dir] — Mechanical Code Linting¶
Run grep-based checks on R/Python/Julia scripts against the coding standards' prohibited patterns. Catches mechanical violations before the coder-critic's judgment review.
- Single file:
/tools lint scripts/02_estimate.R - Directory:
/tools lint scripts/(recursive) - Default:
/tools lint(lintsscripts/)
What it checks (drawn from .claude/references/coding-standards-*.md):
| Check | R | Python | Julia | Severity |
|---|---|---|---|---|
| Absolute paths | x | x | x | HIGH |
setwd() / os.chdir() / cd() |
x | x | x | HIGH |
| Missing seed (stochastic code) | x | x | x | HIGH |
install.packages() / pip install |
x | x | HIGH | |
rm(list = ls()) |
x | MEDIUM | ||
T/F literals |
x | MEDIUM | ||
sapply() |
x | MEDIUM | ||
attach()/detach() |
x | MEDIUM | ||
<<- global assignment |
x | MEDIUM | ||
stargazer / plyr |
x | MEDIUM | ||
set.seed() position (after line 30) |
x | MEDIUM | ||
| Wildcard imports | x | MEDIUM | ||
np.random.seed() global state |
x | MEDIUM | ||
Bare except: |
x | MEDIUM | ||
eval/@eval runtime |
x | MEDIUM | ||
Late library()/import/using |
x | x | x | LOW |
print() for status |
x | LOW | ||
require() |
x | LOW | ||
1:n patterns |
x | LOW |
Output: Findings by file with severity, line number, and fix suggestion. Always advisory (exit 0).
When to use:
- Before /review --code — catches mechanical violations instantly
- Before commits — quick sanity check
- The coder-critic focuses on judgment (strategy alignment, numerical plausibility, design); this catches the grep-able stuff
/tools journal — Research Journal¶
Regenerate the research journal timeline from quality reports and git history. Shows chronological record of agent actions, phase transitions, scores, decisions.
/tools context — Context Status¶
Show current context status and session health. Check context usage, whether auto-compact is approaching, what state will be preserved.
/tools deploy — Deploy Guide Site¶
Render Quarto guide site and publish to GitHub Pages.
/tools learn — Extract Learnings¶
Extract reusable knowledge from the current session. Auto-memory handles corrections automatically; this is for multi-step workflows worth turning into a full skill.
/tools upgrade — Upgrade Clo-Author Infrastructure¶
Upgrade an existing project to the latest clo-author architecture.
What it does:
1. Clone the latest clo-author release into a temp directory
2. Save the user's filled-in domain-profile.md and any custom journal profiles
3. Delete the old .claude/ directory
4. Copy the new .claude/ in
5. Restore the user's domain-profile.md and custom journal profiles
6. Optionally copy new templates/
7. Report what changed
Workflow:
Step 1: DOWNLOAD
- Clone latest clo-author into /tmp/clo-author-upgrade
- Or: gh release download --repo hugosantanna/clo-author
Step 2: PRESERVE USER CUSTOMIZATIONS
- Save .claude/references/domain-profile.md if filled in (not just placeholders)
- Save any custom journal profiles the user added to journal-profiles.md
- Save .claude/settings.json (user's permissions and hooks)
- Save .claude/settings.local.json if it exists
Step 3: REPLACE
- Delete old .claude/ entirely
- Copy new .claude/ from the downloaded release
- Restore saved customizations from Step 2
Step 4: DO NOT TOUCH
- paper/, scripts/, data/, explorations/, quality_reports/
- CLAUDE.md, Bibliography_base.bib, README.md, .gitignore
- Any other user content
Step 5: REPORT
- List what was updated (new agents, skills, rules)
- List what was preserved (domain profile, settings, custom profiles)
- Clean up temp directory
No git merge. No upstream remote. No conflicts. Just delete and replace .claude/.
Bundled Resources (Level 3)¶
| Resource | Path | When |
|---|---|---|
| Gotchas | gotchas.md |
Always — known failure points |
Principles¶
- Each subcommand is lightweight. No multi-agent orchestration needed.
- Compile uses latexmk. Handles multi-pass and biber automatically.
- validate-bib catches drift. Run before commits to catch broken citations.
- Upgrade preserves content. Infrastructure changes, your paper doesn't.