/auto-research

name: auto-research
description: "Iteratively improve a local artifact (draft, document, page) by running a hill-climbing loop. The user names the artifact, the evaluator, and the budget. Claudia edits the artifact, scores it, keeps it if better or reverts if worse, repeats. Use when user says \"iterate on this\", \"loop on this until it's better\", \"run experiments on this draft\", \"auto-research this\", \"make this better and don't stop until it's good\". Workspace-scoped, never touches live files, no external actions during the loop."
effort-level: high
invocation: contextual

Auto-Research

A hill-climber for any local artifact with a rubric. Inspired by [Karpathy's autoresearch pattern](https://github.com/karpathy/autoresearch), adapted to Claudia's safety principles.

Mental model

Three primitives, one governance file:

1. **The artifact** — what gets iterated on (a draft email, a brief, a wiki page, a one-pager). Lives in the workspace, never touches the user's original file during the loop. 2. **The evaluator** — a scalar rubric. Plain English. An independent Checker (the `loop-checker` agent, Haiku) scores each iteration against it, not Claudia herself. The rubric must produce a number for the original artifact before the loop starts. 3. **The budget** — iteration count (default 20). Loop stops when budget is exhausted or score plateaus. 4. **The program** (governance file) — what the user wants, what's off-limits, what counts as "better." Claudia helps the user write this if they don't volunteer it.

Loop: read program + artifact + results history, Claudia (the Maker) proposes one specific change, implements it, then dispatches the `loop-checker` (the Checker) to score it independently. If the Checker's score beats the running best, ratchet (commit); if worse, revert (git reset). Write the status file. Report each iteration as a one-line update. Repeat until budget is hit.

When to invoke this skill

User explicitly asks:

• "Iterate on this until it's [adjective]"
• "Loop on this draft"
• "Run experiments on this"
• "Auto-research this"
• "Hill-climb this against [criterion]"
• "Make this better, don't stop until it's good"

User implicitly invokes when:

• They've shared an artifact and a quality bar in the same message
• They've tried 2-3 manual revisions of the same draft in the same session and are still unsatisfied

When NOT to invoke

Refuse to start the loop if:

1. **External-action artifact.** The artifact is, or directly drives, an external action (an email about to be sent, a Slack message in the compose window, a calendar invite). Auto-research on these is too easy to misuse. Hand-iterate with the user instead. 2. **No clear evaluator.** The user can't articulate what "better" means even after one pass of helping. Without an evaluator, the loop hill-climbs the wrong hill. 3. **Sensitive content.** Medical, deeply personal, legal-defensible artifacts. Iteration risks introducing fabricated detail that looks plausible. Decline and explain. 4. **The artifact is already good.** If you score the baseline and it's above the user's stated threshold, tell them and offer one quick polish instead of N iterations. 5. **Bold structural change is the actual need.** Karpathy's own limitation: RLHF-trained iteration is "cagy and scared." Iterations tend toward safe edits, not bold reframings. If the user wants a fundamentally different angle, iteration will not get them there. Suggest a fresh draft instead.

Workspace layout

Each run gets its own workspace at `~/.claudia/auto-research/<task-id>/`:

~/.claudia/auto-research/<task-id>/
├── program.md           the brief (user-authored with Claudia's help)
├── artifact.md          (or .txt, the working copy that gets edited)
├── original.md          immutable copy of the input, for reference and diff
├── results.tsv          one row per iteration: timestamp, score, kept/reverted/contested, change-summary
├── research_status.md   loop control plane (see docs/loop-status-schema.md): iteration, verified, score, checker_verdict, next_action
├── best.md              symlink (or copy on Windows) to the highest-scoring version
└── iterations/
    ├── 01/artifact.md
    ├── 02/artifact.md
    └── ...

The task-id is the slugified user phrase plus a short timestamp: `iterate-board-update-20260515-1430`.

**Critical:** The loop edits `artifact.md` inside the workspace. The user's original file (wherever it lives in their file system) is **NEVER** modified during the loop. At the end, Claudia asks the user where to put `best.md`; the user decides.

program.md template

# Program for: <one-line description of the task>

## Goal

(1-3 sentences. What is the end state Claudia is iterating toward?)

## Evaluator (rubric)

Each iteration is scored 0-10 on each dimension. Total score = sum. Higher is better.

| Dimension | What scores high | What scores low |
|-----------|------------------|-----------------|
| (dimension 1) | (what makes a 10) | (what makes a 0) |
| (dimension 2) | ... | ... |
| (dimension 3) | ... | ... |

## Hard constraints (do NOT violate)

- Length cap: stay under N words.
- Must contain: specific phrase or fact.
- Must NOT contain: forbidden phrasings, names, claims.
- Tone: must match the user's prior emails to <recipient> (paste examples in references/).
- (etc.)

## Budget

- Max iterations: 20 (default)
- OR stop when score plateaus (no improvement for 5 iterations in a row)

## Out of scope

- (anything Claudia might be tempted to do that isn't the goal)

Claudia's first action when invoked: read the artifact, draft a program.md based on what the user said, present it for confirmation, then start the loop.

The loop (Claudia's internal workflow)

For each iteration N:

1. **Read the state.** Read `program.md`, `artifact.md`, last 3 rows of `results.tsv`. 2. **Propose one change.** One specific edit, justified in one sentence. Not a rewrite. Not a refactor. One change.