Goal Instruction Writer

Goal Instruction Writer turns a rough request into an instruction contract for sustained, multi-stage work. It defines the desired outcome, the loop that advances it, and the conditions for ending it. Draft mode builds a new Goal; Refine fills gaps while preserving an existing Goal; Audit identifies ambiguity and proposes small corrections; Convert reshapes a ticket, checklist, or brief without expanding its scope.

Preview mode shows the concrete work loop before a final Goal is written. It covers the starting state, first work unit, success and failure branches, evidence, drift gates, and stopping conditions. The user confirms or revises this design before it becomes the executable instruction. A preview does not authorize external actions.

Use the skill when multi-stage work has unclear acceptance evidence, authority, scope, verification cadence, waiting behavior, or termination. Ordinary one-shot prompts do not need it. Requests mainly about operating a host's native Goal loop belong with goal-loop instead. Drafting an instruction does not grant access or permission to execute the underlying task. When the mode is unstated, infer it from the input; ask only questions that change the outcome, authority, acceptance evidence, or legal ending. Otherwise state assumptions and continue.

For feedback, pilot, adoption, launch, or validation work, establish what qualifies as evidence, how many non-author responses are needed, and the observation window. Author-only activity counts only if the user explicitly selects that threshold. A feedback entry point and actual feedback are different completion conditions.

Inputs include the user's request, an existing Goal, or a project brief. The contract preserves the user's language, intent, scope, and authority boundaries. It identifies an authoritative baseline, allowed changes, frozen behavior, measurable acceptance criteria, dependencies, and the final artifact or report.

A compact Goal Anchor holds the outcome, criterion identifiers, frozen scope, and current phase. One supplied anchor format is:

Goal Anchor: <one sentence describing the user/system outcome>
Success criteria: C1 <...>; C2 <...>; C3 <...>
Frozen scope: <invariants, protected behavior, and forbidden side effects>
Allowed authority: <tools, files, systems, and approvals available>
Current phase: <phase or milestone>

Each iteration inspects the durable cursor, selects one criterion, names an expected evidence change and scope reason, acts, verifies, and records the result. Results are classified as ON_TARGET, SIDE_QUEST, or DRIFTED. Side quests enter a deferred list. Drift stops the loop for realignment; it cannot silently redefine acceptance to fit completed work. The default phase gate rereads the Anchor every three to five iterations, at milestones, and before high-cost or irreversible actions.

Verification distinguishes focused iteration checks from broader phase and delivery requirements. Evidence stays reusable while the relevant artifact, inputs, dependencies, and environment remain valid. Repeating a check requires a change or unresolved concern that justifies it. Expensive checks receive timeouts or attempt limits; a timeout leaves the criterion open. All required checks still need valid evidence before completion.

Limits may be a timebox, budget, attempt count, or finite work list. Two equivalent actionable attempts without acceptance progress or relevant new evidence normally trigger realignment. External waiting has a separate checkpoint containing the unmet criterion, dependency, last observation, next check time or event, and deadline. Before that trigger, continue independent work or yield. Waiting and a due observation of a pending dependency are neither failed attempts nor acceptance progress; actual calls and elapsed time still consume host budgets.

Draft, Refine, and Convert return design notes and a ready-to-paste instruction with the contract fields. Refine and Audit identify remaining ambiguities and the smallest resolving changes. Unrelated outcomes belong in separate Goals.

The final contract distinguishes complete, blocked, owner-paused, timeboxed, stopped, and realignment-required outcomes. Preserve the terminal labels GOAL COMPLETE, GOAL BLOCKED: <reason>, GOAL TIMEBOXED: <state>, and GOAL REALIGNMENT REQUIRED. Completion requires verified acceptance criteria and the deliverable. A timeboxed ending records progress and the remaining gap; realignment preserves the checkpoint rather than claiming completion. A blocker needs a verifiable dependency that cannot be resolved without new input or permission, plus the attempts made and exact unblock condition. Difficulty or uncertainty alone does not qualify. Reports retain evidence, remaining gaps, decisions, and a resumable cursor.

Runtime execution, permissions, persistence, timers, and resumption come from the host and user. Recording a future check does not create a scheduler. The host must supply the timer, event, or later authorized invocation and access to the checkpoint. The documented waiting branch has not been validated by a live wait/resume test.