Write good goal

Write Good Goal

Create goal text that another coding agent can use directly. Optimize for a goal that can actually progress inside the goal run. Prefer shaping the goal so it finishes cleanly over writing a goal that predictably pauses.

Hard length limit: the final paste-ready goal text, including any feasibility warning, must be at most 4000 Unicode characters unless the user gives a different limit — the same cap as a Claude Code /goal condition, so the text stays usable as one. Counting by eye is unreliable: draft to a working target of about 3500, verify with a real count (wc -m) when a shell is available, and compress before responding if over; never ask the user to trim it later.

Workflow

1. Extract the contract inputs: objective, source and boundary, done criteria, approvals, human judgment points, context anchors (entry files, repro and test commands, key docs), and any cost or compute constraints.
2. Classify each done criterion before drafting:
   • Agent-achievable: the agent can produce or verify it within normal rounds.
   • External evidence: it depends on elapsed time, future data, scheduled runs, third-party state, or long-running observation.
   • Human decision: deterministic verification cannot decide it, or policy or product judgment is required.
   • Approval: the user must explicitly allow an irreversible action or scope change.
3. Do a feasibility check before drafting:
   • If the main objective cannot complete inside the goal run because it needs wall-clock waiting, future observations, external-state changes, or a product or policy decision, warn the user and propose a tighter agent-achievable goal.
   • If the external requirement is only a follow-up acceptance gate, move it out of Done and into Follow-Up Gate so the goal can complete without pretending the future evidence exists.
   • If the external requirement is central and cannot be scoped out, add a Risk / Pause Plan and say the goal is expected to pause.
   • If the total effort is unknown or plausibly larger than one goal run (for example a whole-codebase rewrite), bound it: an explicit bound in Done ("or stop after N rounds with a completion report"), staged work, or a Risk / Pause Plan. Never promise completion of unknown scale unbounded.
4. If a criterion is not agent-achievable in the current run, put it in Follow-Up Gate, Human Gate, or Risk / Pause Plan, or ask the user to rescope it. Do not bury it inside normal Done.
5. Close information gaps with one batched grill, not a serial interview:
   • Split facts from decisions. Look up facts yourself in the repo, the files, or the conversation. If the executing agent can discover a fact during the run (commands, paths, configs), write the discovery into the goal instead of asking anyone.
   • A gap is worth asking only when the wrong guess would materially change the goal text AND no safe default exists. When a safe default exists, adopt it and record it under Assumptions instead of asking. If no gap clears this bar, skip the grill entirely and go straight to the goal.
   • Ask every gap that clears the bar together in a single message, typically two to five questions. Never ask one question, wait for the answer, then ask the next.
   • Attach a recommended default to every question: the user can reply "use all defaults", answer selectively, or override; unanswered items resolve to their defaults.
   • With an interactive question tool, send the batch as one turn with the recommended option first; otherwise send one compact numbered list.
   • Hard cap: two batches. Then adopt the remaining defaults and record each adopted default under Assumptions.
6. Draft only the goal text by default. Add a short feasibility warning before the goal only when it needs a follow-up gate, human decision, or pause plan.
7. Self-check before responding:
   • Done criteria can be judged as pass, partial, paused, or blocked.
   • Every Done bullet contains the literal marker — check: with a check whose result the agent can surface in the run transcript. Goal evaluators judge only what the transcript shows; verification described in prose without the marker does not count.
   • Main Done criteria are agent-achievable unless the user explicitly accepts an expected pause.
   • Progress selection compares next moves before each round.
   • Elapsed-time or external-evidence requirements are scoped out, moved to a follow-up gate, or given a pause and resume trigger.
   • Human gates are limited to semantic judgment or explicit approval.
   • Capability-only work has a five-round budget.
   • Context and Done name only files, commands, and thresholds that come from the user, the repo, or the conversation. Unknown specifics were either grilled in the batch or recorded in Assumptions, never invented.
   • No constraint, gate, or pause expectation is stated in more than one section.
   • If total scope is unknown or plausibly exceeds one run, Done carries a bound or the goal has a staged or pause structure.
   • The output is directly pasteable into Codex or Claude Code and stays within the active character limit.

Goal Shape

Write in the user's language; keep the section headings and the check: marker in English. Under the default limit, preserve Goal, Boundary, Done, Loop, Human Gate, and Round Report; include the optional sections (Context, Assumptions, Follow-Up Gate, Risk / Pause Plan) only when they earn their space. When no later acceptance evidence is needed, omit the Follow-Up Gate heading and block entirely. Never emit an empty optional section.

If feasibility risk exists, put this before the goal:

Feasibility Warning:
[The requested done condition depends on external evidence, elapsed time, or a human decision. I scoped the goal to the agent-achievable slice and put the external condition in Follow-Up Gate. To keep it in Done, the user must explicitly accept a pausing goal.]

Goal:
[One-sentence objective.]

Context:
- [Optional. Real entry files, repro/build/test commands, and key docs the
  agent should start from. Only known items, never invented ones.]

Boundary:
- Use: [...]
- Do not use: [...]
- Out of scope: [adjacent work the agent must not start.]
- Approval needed: [...]

Done:
- [End state 1 — check: command, diff, or artifact whose result the agent can
  show in the transcript.]
- [End state 2 — check: ...]

Assumptions:
- [Optional. Defaults adopted without user confirmation. If one proves wrong,
  pause and report instead of working around it.]

Follow-Up Gate:
- [Optional. Acceptance evidence that cannot exist during the goal run, such as future observations, scheduled data, external review, or a later human decision.]

Loop:
Before each round, compare up to three next moves by expected increment, expected state change, and cost or risk. Choose the move with the best expected progress toward Done.
Valid increments:
- Outcome: the target artifact or result improves.
- Evidence: trustworthy evidence increases.
- Capability: a named blocker is removed.
Prefer Outcome or Evidence over Capability when similarly feasible. Do not run more than five consecutive Capability-only rounds.
If a check that passed in an earlier round fails now, fix it before any new move.
After each round, check whether the next required state change depends on external evidence, elapsed time, or human judgment. If yes, stop at the pause point instead of inventing adjacent work.

Risk / Pause Plan:
[Optional. Include only when the goal is expected to pause or has a meaningful pause risk.]
Pause when the next required progress depends on external evidence, elapsed time, human decision, or explicit approval and no remaining agent-achievable increment would materially advance Done.
When pausing, report:
- current proven state
- missing trigger or evidence
- exact resume condition
- optional monitor or scheduled check, if supported

Human Gate:
Ask for human input only when deterministic verification cannot decide correctness or explicit approval is required.

Round Report:
For each round report:
- selected move
- increment type
- expected state change
- actual state change
- verification
- next decision

Rules

• Do not turn the goal into a full project plan.
• Do not exceed the active character limit. Compress boundaries, merge related bullets, and omit optional sections first.
• Do not put wall-clock waiting, future observations, external-state changes, or later human decisions in main Done unless the user explicitly wants a pausing goal. Prefer completing the agent-achievable slice and recording external acceptance as Follow-Up Gate.
• State each constraint in exactly one section; other sections reference it instead of restating it. A gate listed under Approval needed does not reappear in Human Gate prose or Assumptions.
• Assumptions records only adopted defaults that settle a contestable decision. Conventions any competent agent applies, and constraints Boundary already enforces, do not belong there.
• When the user gives a round or time budget, write the bound into Done (for example "or stop after 20 rounds") so the evaluator can enforce it.
• A paused goal is not complete. It has a proven state, a missing trigger, and a concrete resume condition.
• Do not enumerate every bad direction. Select next-round candidates by expected progress, and do not count process surface as progress unless it removes a named blocker.
• Prefer observable state changes over vague quality language.
• When the blocker is human input, approval, elapsed time, or external evidence, state it instead of inventing more preparation. One narrow blocker-removal round may create a real collection, monitoring, or verification mechanism; after that, pause until the missing evidence exists.

Evals

evals/evals.json + evals/rubric.md cover the failure modes this skill prevents. After changing this file, rerun the suite; ship only when every case passes.