Define Goal

define-goal

Phase 2 of long-haul. Converts .longhaul/SPEC.md into a completion condition you can hand to Claude Code's /goal, written to .longhaul/GOAL.md. This condition is the target the whole haul steers by — get it sharp.

What makes a good /goal condition

/goal's evaluator is a fast model that, after every turn, reads only the conversation (it runs no tools) and decides yes/no. A strong condition has all four parts:

1. One measurable end state — a test result, a benchmark threshold, a file count, an empty queue, an exit code. Not "better" or "done".
2. A stated check — how it's proven, phrased so the agent's own output demonstrates it: pytest tests/x -q exits 0, bench/run.py prints p95 is set, and

the haul "passes" against code it never changed. If the check imports the package directly from the tree (most pytest layouts) it's fine — but say which case applies. A proof that's secretly run in the wrong env is worse than no proof.

When "done" has a ratchet AND an acceptance gate

If SPEC.md names two tiers (a cheap per-round ratchet check and an expensive/external/one-shot acceptance gate), the condition carries both, but they play different roles — and saying so in the /goal text is what stops the evaluator from declaring victory on the cheap half:

• The ratchet is re-run and re-printed every round; it's the measurable end

state the loop optimizes.

• The acceptance gate is run once, late, after the ratchet is green and the

incumbent is locked. Its evidence — a job-SUCCEEDED line, a query result, a sign-off — is pasted into chat once and persists there, so the evaluator keeps seeing it on later turns. State explicitly that the goal holds only when both the ratchet output and the gate's pasted evidence are in the transcript, so a ratchet-green-only turn does not trip completion. Phrase the gate's evidence as a before → predicted → after (a baseline, a pre-registered predicted value, and invariants that must hold), not a bare "succeeded" — so the pasted proof is falsifiable. haul-loop captures the baseline/prediction before firing.

A pure cheap-and-headless goal has no gate — the ratchet is the whole condition.

Iterate until the end state is clear

If SPEC.md's success signal is missing, fuzzy, or not transcript-demonstrable, do not paper over it — the goal would loop forever, since the evaluator can never see the proof. Go back to the user with the AskUserQuestion tool — one question per call, each offering 2–4 concrete options as tabs (the user can pick Other to free-type) — until the end state is a single measurable thing with a check whose output Claude can print. This iteration is the point of the phase; don't shortcut it to produce a goal you know is unverifiable.

Process

1. Read .longhaul/SPEC.md. If the success signal isn't measurable + demonstrable, iterate with the user (above) before drafting.
2. Draft the condition with the four parts above, on one logical line.
3. Write .longhaul/GOAL.md (template in [../long-haul/reference/file-formats.md](../long-haul/reference/file-formats.md)): the condition, the literal /goal … line, the proof line (the exact command the loop echoes each round — with its exact interpreter/env per "Pin how the check is invoked"), the acceptance gate and its pasted-evidence form if "done" has one, and a note on why the check is transcript-demonstrable.
4. Set GOAL: (one-line restatement) in STATE.md, advance PHASE: haul.

The gate — the user runs /goal

You cannot execute a slash command yourself. Present the line and hand off:

> Goal condition ready. Review it, then run this yourself to start the haul: > > /goal > > Once it's active, each turn I'll run one haul-loop round — deciding explore vs > exploit and keeping only measured wins — until the condition holds.

Set STATUS: WAITING-USER: approve-goal. Wait for the user to approve (and possibly edit) and to actually run /goal. Only then does the haul begin.

If invoked standalone (not by the orchestrator), note that once /goal is active, haul-loop takes each turn until the goal clears, then wrap-up ships.

Don't

• Don't make the condition depend on something the agent won't print. If proving it requires running a tool, make running it and surfacing the output part of the loop's job — and say so in GOAL.md.
• Don't omit the round clause. A goal with no cap can run away over the long horizon.
• Don't widen scope beyond SPEC.md. The goal is the contract; keep it tight.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ccomkhj
• Source: ccomkhj/skills
• License: MIT

Install and usage instructions live in the source repository linked above.