# Writing Goals

> Use when writing a Claude Code goal or completion condition, running bounded unattended work, or decomposing a large objective into verifiable sub-goals.

- Skill: `iliaim/writing-goals-2` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add iliaim/writing-goals-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/iliaim/writing-goals-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: iliaim (https://skillmd.com/u/iliaim)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/iliaim/writing-goals-2

---


# Writing goals for Claude Code

Follow `shared/method.md` completely. It is the canonical method. Load its linked shared
references as the task requires; this adapter adds only Claude-native integration instructions.

## Invoke and trust

- Invoke as `/writing-goals`; use `/goal <condition>` for Claude's session-scoped goal.
- For non-interactive execution, invoke `claude -p "/goal <condition>"`. The
  `--dangerously-skip-permissions` flag disables interactive approvals; use it only inside the
  sandbox required by `shared/autonomy.md`.
- `/goal` requires a trusted workspace and the hooks system. Managed `disableAllHooks` makes it
  unavailable.
- Project hooks live in `.claude/settings.json`. Review hook source before trusting it; unattended
  permission modes do not turn a hook into containment. Stop and PreToolUse hooks are cooperative
  backstops, not a security boundary. Run unattended work in an OS-level sandbox (for example,
  a `sandbox-exec` profile where available) with only the intended writable source paths.
- Before presenting a non-trivial plan, invoke the separate read-only challenger and validate its
  exact-plan receipt with `assets/validate-review-packet.sh`; do not present a review packet while
  the challenge is missing, stale, non-independent, or red.

## Current Claude platform facts

- A `/goal` condition is limited to **4,000 characters**. Its evaluator reads the conversation
  rather than running tools, so require surfaced evidence or use a deterministic command Stop
  hook.
- Stop-hook input includes `stop_hook_active`, which is true when Claude is already continuing
  because a Stop hook blocked. By default, Claude overrides the hook after **eight consecutive blocks without progress**. Keep `GOAL_GATE_CAP <= 8`, unless
  `CLAUDE_CODE_STOP_HOOK_BLOCK_CAP` is deliberately raised to at least the chosen repository cap.
- A command Stop hook blocks with exit 0 and
  `{"decision":"block","reason":"..."}` on stdout (or exit 2 plus stderr); clean exit 0 with no
  block allows stopping. Use `assets/gate.claude.sh`.
- A reported Claude Code bug can bypass pre-use policies after some background-task completions;
  this is another reason the sandbox, not the hook, is the boundary.

## Native Claude goal

For a run that warrants a native Claude goal, set one `/goal` condition for the complete
objective/run. Keep it below the platform's 4,000-character limit and make it a concise,
user-legible completion contract:

If asked to set the goal yourself, inspect the current session, repository guidance, working tree,
tests, and exact verification surface first. If a material outcome, proof, preservation constraint,
boundary, iteration rule, or blocked stop remains ambiguous, state the proposed understanding in
plain English and obtain approval before setting the goal. Ask only for the unresolved decision.
When those facts are clear from the request and investigation, do not ask again: write the contract
directly.

When monitoring a running goal, make each status check one concise sentence stating the current
activity, whether the run remains on track, and the next gate.

Use this shorthand only to compose the contract; retain every section below rather than merging
them into one sentence:

`/goal <desired end state> verified by <specific evidence> while preserving <constraints>. Use <allowed boundaries>. Between iterations, <evidence-led next action>. If blocked, <blocked report and unlock>.`

```text
Objective: <one complete parent outcome>
Read first: <exact repository files, issue, specification, or decision record>

## Outcome
Given: <baseline>
When: <completed transition>
Then: <measurable end state>
Positive scenario: <normal success>
Negative scenario: <rejected/failure result>
Edge case: <boundary result or evidence-based not applicable>

## Verification surface
Evidence: <exact test, benchmark, report, artifact, command output, or source>
Given: <evidence proves outcome>
When: <fresh check>
Then: Automated proof: `<command>` exits 0 with <signal>; Manual proof: <specific observation when needed>
Positive scenario: <passing signal>
Negative scenario: <false-pass-preventing failure signal>
Edge case: <threshold/partial/noisy-evidence handling>

## Constraints
Given: <protected baseline>
When: <authorized work>
Then: <each named preservation requirement remains true with evidence>
Positive scenario: <preserved behavior>
Negative scenario: <detected regression>
Edge case: <version/migration/compatibility boundary>

## Boundaries
Allowed: <paths, tools, data, repositories, external resources; repository-local default>; Forbidden: <excluded resources/actions>
Given: <Allowed is sufficient>
When: <investigate/change/verify>
Then: <use only Allowed; request approval to widen>
Positive scenario: <in-bound operation>
Negative scenario: <refusal/escalation>
Edge case: <generated/transitive/credential-adjacent handling>

## Iteration policy
Given: <attempt evidence>
When: <select next action>
Then: <record hypothesis/action/change/result; choose next lowest-risk, highest-evidence action; never retry blindly>
Positive scenario: <safe next experiment>
Negative scenario: <same failure stops/reassesses>
Edge case: <conflicting/noisy evidence disambiguation>

## Blocked stop condition
Given: <no defensible path, unavailable proof, or enforced limit>
When: <evidenced>
Then: <do not claim success; report attempted paths, evidence, blocker, and unlock>
Positive scenario: <exhausted in-bound path produces complete handoff>
Negative scenario: <defensible next step means continue>
Edge case: <budget/partial-proof/unavailable-verifier incomplete result>

Document: <focused documentation or not applicable with reason>
Details (optional): `<stable workspace-relative contract or plan path>`
Checkpoint: <current phase; exact evidence observed; next gate; blocker/decision>
Stop when: <Outcome, Verification surface, Constraints, Boundaries, and Iteration policy proof pass>, OR <Blocked stop is evidenced and its non-success handoff is reported>
```

Keep the instantiated condition at or below 4,000 characters: before setting `/goal`, measure it
with `wc -m`. If the six sections cannot fit without merging, omitting, or weakening criteria, use
the persisted lightweight/protected workflow instead; `Details` cannot replace a criterion. Outcome,
Verification surface, Constraints, Boundaries, and Iteration policy `Then` criteria are cumulative and parent-level;
the Blocked stop condition is mutually exclusive and never contributes to completion.
Do not treat the goal as complete because implementation began, a subset passes, or child slices are
complete. For a full plan, derive the success criteria from the frozen `objective_acceptance`. State
concrete outputs, access decisions, files, responses, or other observable signals; never use vague
criteria such as “works correctly.” Claude evaluates the conversation rather than rerunning tools, so
surface the exact command, exit status, and relevant output in the conversation. For unattended or full-tier work, use
`assets/gate.claude.sh` as the deterministic verification gate; the `/goal` condition is not
independent execution evidence. Keep implementation steps, alternatives, per-slice checks, and
lifecycle receipts in the contract or protected plan rather than the native goal. Do not use
`/goal` for a direct one-shot edit with no useful verification boundary.

For coordinated or multi-turn work, the native `Checkpoint` sentence is only a summary. Persist
the checkpoint's current phase, exact evidence observed, next gate, and blocker in the `Details` target or frozen
contract before reporting it; the native goal remains navigation and completion evidence, not the
durable lifecycle authority.

Use literal paths and commands. Do not delete, skip, weaken, narrow, or rewrite tests or other
verification surfaces to make the goal pass; do not refactor unrelated code or add dependencies.
Do not create a new ADR or decision record without human approval. If a product decision, absolute
target, irreversible/external action, new dependency/ADR, or objective change is required, pause
and ask before proceeding.

If the host exposes an enforceable budget and it is reached, the goal is incomplete—not success and
not a resolved blocker. Stop substantive work and report progress, evidence, blocker, and the next
useful step. For `research_design`, keep the persisted contract's claim-evidence ledger: one claim
per row with exact source/evidence, support status (`confirmed`, `approximate`, `support-only`, or
`blocked`), and remaining uncertainty.

Sources: [Claude goal documentation](https://code.claude.com/docs/en/goal) and
[Claude hooks reference](https://code.claude.com/docs/en/hooks),
[Claude hooks guide](https://code.claude.com/docs/en/hooks-guide), and
[Claude Code issue #47810](https://github.com/anthropics/claude-code/issues/47810).