Role

Phase 1: Setup (do this once)

Before the loop starts, establish the configuration. Infer from the user's goal:

If the repo exposes both affected-test and full-suite targets, use the affected-test target for the per-iteration Guard and keep the full-suite gate for baseline checks, periodic health checks, and final verification.

Confirm with the user

Print a setup summary and ask the user to confirm before starting:

Target: eliminate `any` types in src/**/*.ts
Metric: `any` count (current: 47), direction: lower
Verify: grep count
Guard: tsc --build && npm test
Iterations: unlimited (or cap at N)

Reply "go" to start, or tell me what to change.

Phase 2: Baseline

1. Run the Verify command → record the baseline metric value
2. Run the Guard command → confirm it passes (if it doesn't, fix guard failures first)
3. Log: iteration=0, metric=<baseline>, status=baseline

Phase 3: Iteration Loop

For each iteration:

3a. Hypothesis

Pick ONE focused change. Apply multiple perspectives:

• Structural: What pattern in the code causes the metric to be high?
• Statistical: Which files have the most occurrences?
• Historical: What worked in previous iterations? (Check lessons)
• Diminishing returns: Are the remaining cases harder? Adjust strategy.

3b. Change

Make ONE atomic change. Small, focused, reversible.

3c. Commit

git add <changed-files>
git commit -m "autoresearch: <what changed>"

Never use git add . — other work may be in progress.

3d. Dual-Gate Verification

Run both gates:

1. Verify — run the metric command. Did it improve?
2. Guard — run the guard command. Did anything break?

3e. Keep or Discard

• KEEP: Log success, extract a lesson (what worked and why)
• DISCARD: git revert --no-edit HEAD, log failure (what didn't work and why)

3f. Log

Append to results log (keep in .orchestrator/ or project root):

iteration | metric_before | metric_after | delta | status | hypothesis | lesson

3g. Health Check

Every 5 iterations:

• Check disk space
• Verify git is clean (no uncommitted changes leaked)
• Re-run guard to ensure accumulated changes haven't drifted
• Check if metric is still measurable (command still works)

Smart Stuck Recovery

Instead of blindly retrying, use graduated escalation:

A single successful KEEP resets all counters.

When REFINEing:

• Sort remaining targets by estimated difficulty (easiest first)
• Skip the files/patterns that have been failing
• Try a different transformation strategy

When PIVOTing:

• Step back and reconsider the approach entirely
• Example: if manual any replacement isn't working, try a codemod tool instead
• Example: if line-by-line optimization isn't working, try algorithmic changes

Cross-Run Learning

Extract structured lessons after every KEEP and every PIVOT:

## Lessons (autoresearch-lessons.md)

### What Worked
- [Lesson]: Replacing `any` with `unknown` first, then narrowing with type guards — safer and more mechanical
- [Lesson]: Running eslint --fix before manual changes eliminates easy wins first

### What Failed
- [Lesson]: Trying to infer complex generic types from usage — too fragile, causes guard failures
- [Lesson]: Batch-replacing `any` in test files — tests use `any` intentionally for mocking

### Strategic
- [Lesson]: After PIVOT — switched from manual replacement to `ts-migrate` codemod for repetitive patterns

Keep max 50 lessons. Summarize older entries. Read lessons at the start of every run to avoid repeating mistakes.

Parallel Experiments (optional)

When multiple hypotheses are equally promising, test them simultaneously in isolated worktrees:

Main agent (orchestrator)
├── Worktree A → hypothesis 1
├── Worktree B → hypothesis 2
└── Worktree C → hypothesis 3

Pick the best result, merge it, discard the rest. Only use when:

• Multiple approaches are equally viable
• Each hypothesis is independent (no conflicts)
• The metric is deterministic (same input → same output)

Modes

The skill auto-detects the appropriate mode from the user's goal:

Hard Rules

1. Ask before starting, never during. Confirm the setup once, then iterate without interruption. The user may be away.
2. One focused change per iteration. Never batch multiple changes.
3. Mechanical verification only. No "I think this looks better." Run the command.
4. Commit before verification. This enables clean revert if verification fails.
5. Never stage unrelated changes. git add <specific-files> only.
6. Keep run artifacts uncommitted. Results log, lessons, state files stay out of git.
7. Discard gains under 1% that add disproportionate complexity.
8. Unlimited iterations by default unless the user specifies a cap.
9. Never ask "should I continue?" Once launched, keep going until done or stuck.
10. Use the stuck recovery ladder. 3 discards → REFINE, 5 → PIVOT, not brute-force retry.
11. Extract lessons. After every KEEP and every PIVOT.

Output Format

Write to .orchestrator/{pipelineId}/autoresearch.md (or project root if standalone):

## Autoresearch Report

### Goal
[What was the target]

### Results
- Baseline: [starting metric]
- Final: [ending metric]
- Improvement: [delta and percentage]
- Iterations: [total] (kept: [N], discarded: [N])

### Key Lessons
- [Top insights from the run]

### Remaining Work
- [What couldn't be automated, needs human decision]

### Verdict
<!-- VERDICT: PASS -->
Target achieved / Target partially achieved (X% improvement) / Target not achievable

Related Skills

Attribution

Adapted from codex-autoresearch (MIT) by leo-lilinxiao, inspired by Karpathy's autoresearch.