peakspec/marshal/optimize-goal

Optimize Goal

Overview

A goal.md is a long-form instruction the user writes to a file instead of typing into chat, meant to be fed to Claude Code's `/goal` command. /goal uses that same text twice: once as the directive for the first turn, and then every turn after, a separate transcript-only judge model re-checks it against the conversation to decide whether to stop. Whatever is ambiguous, unmeasurable, or unverifiable in the file passes straight through into both of those — there's no chat back-and-forth to catch it later. This skill reviews an existing goal.md against a checklist tuned to both general prompt clarity and /goal's actual mechanics, clarifies the gaps with the user, and only then rewrites the file.

Not for: helping someone compose a goal.md from scratch when no draft exists yet — that's superpowers:brainstorming territory. This skill starts from a file that already exists.

Workflow

1. Read the goal.md the user points to.
2. Silently audit it against the checklist in references/best-practices.md. Judge

relevance to this goal.md — don't force a fixed template onto it. A one-paragraph goal doesn't need a Prerequisites section; a multi-repo goal probably does.

1. Ask clarifying questions one at a time, ordered by impact (biggest ambiguity or

highest blast-radius gap first — e.g. missing success criteria before missing formatting preferences). Prefer multiple-choice phrasing when the gap has a natural small set of answers.

1. Draft the enhanced version once questions are answered. Preserve the user's own

structure, section names, and voice — tighten and fill gaps, don't impose a rewrite they didn't ask for.

1. Show the draft (or a diff against the original) and get explicit approval.
2. Only after approval, overwrite goal.md in place. Never write the file before the

user has signed off on the content.

Checklist quick reference

Full detail with examples in references/best-practices.md. Categories to scan for on every goal.md, applied contextually:

Common mistakes

• Asking everything at once. Dumping five clarifying questions in one message gets

shallow answers. One at a time, highest-impact gap first.

• Rewriting before approval. Draft, show, wait for sign-off, then write the file.
• Enforcing a rigid template. The checklist is a lens, not a form to fill in — a

short goal.md that's already clear doesn't need every category addressed explicitly.

• Treating "no file yet" as in scope. If the user has only an idea and no draft,

point them to superpowers:brainstorming instead of improvising a first draft here.