# Autoresearch Finalize

Finalize an autoresearch session into clean, reviewable branches.

- Repository: https://github.com/davebcn87/pi-autoresearch (8207 stars)
- Category: Engineering
- License: MIT
- Last updated: 2026-10-07
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add davebcn87/pi-autoresearch --skill autoresearch-finalize -g -a claude-code -y`
Codex: `npx skills add davebcn87/pi-autoresearch --skill autoresearch-finalize -g -a codex -y`
Cursor: `npx skills add davebcn87/pi-autoresearch --skill autoresearch-finalize -g -a cursor -y`
Gemini CLI: `npx skills add davebcn87/pi-autoresearch --skill autoresearch-finalize -g -a gemini-cli -y`

## Description

Finalize an autoresearch session into clean, reviewable branches. Use when asked to "finalize autoresearch", "clean up experiments", or "prepare autoresearch for review".

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Finalize Autoresearch

Turn a noisy autoresearch branch into clean, independent branches, one per logical change, each starting from the merge-base.

## Step 1, Analyze and Propose Groups

1. Read `.auto/log.jsonl` (legacy: `autoresearch.jsonl`). Filter to **kept** experiments only.
2. Read `.auto/prompt.md` (legacy: `autoresearch.md`) for context.
3. Expand all short commit hashes to full hashes: `git rev-parse <short_hash>`
4. Get the merge-base: `git merge-base HEAD main`
5. For each kept commit, get the diff stat (use `$BASE..<commit>` for the first, `<prev_kept>..<commit>` for subsequent).
6. Group kept commits into logical changesets:
   - **Preserve application order.** Group N comes before Group N+1.
   - **No two groups may touch the same file.** Each branch is applied to merge-base independently, overlapping files would conflict. If two groups touch the same file, merge them into one group.
   - **Watch for cross-file dependencies.** Each branch is independent, so if group 1 adds an API in `api.js` and group 2 calls it in `parser.js`, group 2's branch won't work in isolation. When proposing groups, flag dependencies: "group 2 depends on group 1, review together." If the dependency is tight, merge the groups.
   - **Keep each group small and focused.** One idea, one theme per group.
   - **Don't hardcode a count.** Could be 2, could be 15.

Present the proposed grouping to the user:

```
Proposed branches (each from merge-base, independent):

1. **Switch test runner to forks pool** (commits abc1234, def5678)
   Files: vitest.config.ts, package.json
   Metric: 42.3s → 38.1s (-9.9%)

2. **Tune worker count and timeouts** (commits ghi9012, jkl3456)
   Files: test/setup.ts
   Metric: 38.1s → 31.7s (-16.8%)
```

**Wait for approval before proceeding.**

## Step 2, Write groups.json and Run

Write `groups.json`:

The rest: https://github.com/davebcn87/pi-autoresearch/blob/HEAD/skills/autoresearch-finalize/SKILL.md