Harvest

---
name: harvest
description: Turn proven session behavior into a skill, rule, profile, AGENTS.md diff, or team learning; artifacts seed /autoresearch evals. Triggers "harvest this workflow", "turn this session into a skill", "preserve this behavior".
context: fork
argument-hint: "[what to harvest]"
---

# harvest

Extract the repeatable procedure behind an unusually good result and land it as a
reviewed cc-settings artifact — with the *evidence measured*, not asserted. The
output is a concrete file (skill, rule, profile section, AGENTS.md diff, or
team-knowledge note) plus a filled [harvest contract](./CONTRACT.md) whose verdict
(PASS / FAIL / INCONCLUSIVE) decides whether it may be promoted, and to what scope.

This is a **ratchet**: it only tightens shared standards on behavior it can show
repeated or survived a trap. Behavior it cannot measure is marked INCONCLUSIVE and
held back, not written up as fact.

## Standalone Codex source boundary

Claude frontmatter does not create an isolated fork in standalone Codex. Keep
evidence inspection read-only in the current context or use a fresh native
reader. Audit native rules under `${CODEX_HOME:-$HOME/.codex}/rules`, the
installed `AGENTS.md`, and managed artifacts in the real cc-settings git
checkout named by the Codex sentinel's `repo_path`. Installed plugin/cache files
and `darkroom/source` may be inspected for drift, but never edited as the source
repo.

## Phase 1 — Witnessed behavior census

Before deciding *what* to harvest, inventory *what was actually seen*. For each
candidate behavior, record — from evidence, not memory:

- **Witness count**: how many independent sessions / transcripts / runs showed it,
  and therefore **multi-witness** (≥2) or **single-witness** (1).
- **What repeated**: the steps that were identical every time — the deterministic core.
- **What varied**: what differed across witnesses. Decide per difference: noise to
  drop, or part of the signal to preserve.
- **Evidence inspected**: the transcripts, PRs, diffs, or outputs you actually read.
- **Not proven**: what you are *inferring* rather than observing. Name the gaps.

Evidence comes two ways — use whichever the user has:

1. **Interview** — 3–5 questions, one at a time: trigger? ordered steps? where the
   default would have gone wrong? how you knew the output was good? what it refused?
2. **Transcript / diff analysis** — the user points at a session, PR, or outputs.
   Read them, reconstruct the same answers yourself, then confirm with the user.

An unknown witness count is `null`, never an optimistic guess. Single-witness is a
valid census result — it just caps how far the artifact can travel (Phase 5).

## Phase 2 — Filter to the harvestable

The bar is **a repeatable procedure, not raw intelligence**. Test each candidate:

- What did the session do *differently* from the default path? ("ran the failing
  test before reading any source", not "it was smarter").
- Would the same steps help a weaker model or a fresh session? If the value was
  depth of reasoning alone, **stop and say so** — that can't be harvested, and prose
  about it is context bloat, not capability.
- Is it already covered? In Claude check the "All Skills" table in `MANUAL.md`
  and `~/.claude/rules/`; in standalone Codex use the source boundary above. If
  an existing artifact covers 80% of it, the deliverable
  is a *diff to that artifact*, not a new one.

## Phase 3 — Fill the harvest contract

Distill the census into the [harvest contract](./CONTRACT.md) — copy its template
and fill every field: trigger, observed evidence, procedure, known failure modes,
quality bar, trap prompts, required tools, verification result, promotion decision.

If you can't fill a row with something concrete, it is `null` / INCONCLUSIVE — that
is data, not a blank to paper over. A missing failure mode usually means the
behavior wasn't actually different from the default; go back to Phase 1.

## Phase 4 — Route to the smallest artifact, then write it

| The behavior is… | Artifact | How |
|---|---|---|
| A multi-step workflow a user would invoke | **Skill** | `bun run new-skill` + `docs/skill-authoring.md` |
| An always-on constraint tied to file types | **Rule** | New/edited file in `rules/` with `paths:` frontmatter |
| A workflow bundle for one project type | **Profile** | Section in the matching `profiles/*.md` |
| A universal standard every tool should follow | **AGENTS.md** | Targeted diff to the relevant section |
| A single gotcha, decision, or convention | **Team learning** | Hand off to `/share-learning` |

Bias toward the smallest artifact that carries the procedure — folding into an
existing skill beats adding a new one (see the skill cap in CLAUDE-FULL.md). Author
it in the target's own conventions, carrying the contract's fields into the file:
procedure as steps, failure modes as a DON'T / red-flags section, quality bar as
explicit checks.

For skills, complete registration: `ACTIVE_SKILLS` in `src/lib/managed-skills.ts`, the human
contract in `docs/skills.md`, then `bun run lint:skills`.

## Phase 5 — Verify: traps, then verdict

Write **2–3 trap prompts** — realistic requests where an agent *without* the
artifact takes the documented bad path. For each:

1. Run it against a fresh subagent **with** the artifact loaded. The subagent must
   not see the trap's expected answer or this checklist (blind-run rule — same as
   `/autoresearch`).
2. Judge the transcript against the contract's quality bar: did it avoid the
   specific failure mode?

Then set the **verification result** per the contract's rubric:

- **PASS** — multi-witness, or single-witness with all traps passing.
- **FAIL** — a trap reproduced the bad path with the artifact loaded. Do not
  promote; revise and re-run, or stop.
- **INCONCLUSIVE** — evidence missing, single-witness with no passing trap, or any
  required field still `null`. Personal draft only; never a shared standard.

The **promotion scope gate** ([CONTRACT.md](./CONTRACT.md)) binds the verdict to how
far the artifact travels: single-witness never reaches `AGENTS.md`, `rules/`,
`profiles/`, or team-knowledge on its own.

## Phase 6 — Seed autoresearch (skills only)

When the routed artifact is a **skill**, hand its evidence forward: write or update
`skills/<name>/RESEARCH.md` so `/autoresearch` can later optimize it.

- `## Test Inputs` ← the trap prompts (one `### Test N:` per trap).
- `## Checklist` ← the quality-bar checks (observable, binary — 3–7 items).
- `## Settings` ← defaults (`samples: 3`, `min_improvement: 0.05`, `max_rounds: 50`).

**Preserve the blind-run rule**: the seed carries only the raw prompt and the binary
criteria — never the expected answer, the scoring rationale, or this conversation's
context. Leaking any of those teaches to the test.

Validate the shape before finishing: `bun run lint:research skills/<name>/RESEARCH.md`
(required sections present, ≥2 test inputs, 3–7 checklist items, numeric settings).

## Deopt / fallback

- **Evidence missing** → mark INCONCLUSIVE. Do not promote; do not invent a PASS.
- **Trap prompts fail** → FAIL. Fix the artifact and re-run, or stop.
- **Unknown numbers** → `null` / INCONCLUSIVE, never aspirational.
- **Unknown territory** — behavior you can't reconstruct, a judgment you can't
  verify from evidence on disk — → fall back to `/verify`, `/oracle`, human
  approval, or normal reasoning rather than forcing a verdict.

## Approval gate

**Stop. Present the artifact and the filled contract (with its verdict). Wait for
approval before:**

- Editing `AGENTS.md`, `rules/`, or `profiles/` (shared standards — every teammate
  inherits these; require multi-witness **and** PASS)
- Posting to the team-knowledge repo via `/share-learning`
- Committing anything

Personal-scope drafts (a new unregistered skill file, a RESEARCH.md seed) may be
written freely; the gate is on anything shared.

## Pairs with

- `/autoresearch` — the optimization loop on a harvested skill; Phase 6 hands it a
  ready RESEARCH.md seeded from the traps and quality bar
- `/share-learning` — the routing target for single-note learnings
- `/verify` or `/oracle` — the fallback when a behavior is real but can't be measured
  into a verdict

## What this skill does NOT do

- **Clone model reasoning.** It captures procedures — steps, checks, gates. If the
  magic was the model itself, the honest output is "not harvestable".
- **Call model APIs** to sample or distill behavior. Evidence comes from the user,
  transcripts, and artifacts already on disk.
- **Assert what it didn't witness.** Unknown counts are `null`; unproven behavior is
  INCONCLUSIVE. Every promotion carries a verdict, or it isn't done.