pi-goal-writer

name	pi-goal-writer
description	Drafts and reviews strong /goal objectives for Pi pi-goal and compatible goal-mode agents. Use when the user asks to write, improve, audit, or meta-prompt a long-running agent goal with clear success criteria, verification, constraints, iteration policy, and blocked stop conditions.

Pi Goal Writer

Purpose

Write /goal prompts that are fit for persistent autonomous work. A goal is not a bigger ordinary prompt; it is a completion contract. The agent will keep using it to decide what to do next and whether it can honestly stop, so the goal must define the desired end state, the evidence that proves it, the constraints that must remain true, and when to stop as blocked instead of drifting.

Use this skill for Pi pi-goal first. The same goal-writing principles also apply to Codex Goal mode and compatible /goal workflows.

Core rule

Never produce a vague goal such as “make this better,” “finish the feature,” or “improve the codebase.” Turn the user’s rough intent into a goal with auditable completion criteria.

A strong goal includes six parts:

1. Outcome — what must be true when the work is done.
2. Verification surface — tests, commands, benchmark output, report, artifact, diff audit, PR state, screenshots, logs, or other concrete evidence.
3. Constraints — what must not regress or be changed.
4. Boundaries — files, directories, tools, systems, data sources, or permissions the agent may or may not use.
5. Iteration policy — how the agent should choose the next action after each attempt.
6. Blocked stop condition — when the agent should stop honestly, with evidence and the next needed input, instead of continuing blindly.

Workflow

1. Default to Pi pi-goal. Write a Pi-compatible /goal command unless the user explicitly asks for another harness. The goal body can usually be reused in Codex Goal mode; Pi also supports optional token budgets such as /goal --tokens 50k ....
2. Gather context before drafting when the task depends on a repository, issue, test suite, benchmark, PR, design, or external documentation. Read the relevant files or sources instead of inventing the verification surface.
3. Ask at most three clarifying questions only when missing information changes the goal contract. Prefer making safe assumptions explicit when the user is trying to move quickly.
4. Draft the goal as a single pasteable command, then include a short rationale or checklist showing how the six parts are covered.
5. For high-stakes or ambiguous work, provide two options: a narrower goal that is safer to execute and a broader goal that delegates more discovery to the agent. Recommend one.

Goal template

Use this shape unless the user asks for a different format:

/goal <desired end state>, verified by <specific evidence>, while preserving <constraints>. Use <allowed inputs/tools/scope> and avoid <forbidden scope>. Between iterations, <how to choose the next best action and what to re-check>. If blocked or no defensible path remains, stop with <evidence gathered, attempted paths, blocker, and next input needed>.

For Pi token budgets:

/goal --tokens 50k <same goal contract>

Writing standards

Make the goal self-contained. It should survive context compaction and continuation turns. Include exact command names when known, but do not invent commands. Say “run the relevant project checks identified in AGENTS.md/package scripts” only when exact commands are unknown and the agent can inspect them.

Make completion evidence-based. The goal should require the agent to inspect real artifacts before declaring success: files changed, tests passed, benchmark numbers, rendered screenshots, logs, PR checks, or a written audit. Do not let “tests pass” be the only evidence unless the tests actually cover every requirement.

Bound the scope. Name excluded directories or behaviors when important, such as “do not rewrite CLI user-facing output,” “do not change public API behavior,” or “do not touch generated files except via the generator.”

Preserve honesty under uncertainty. If evidence may be unavailable, require a final report that separates confirmed findings, approximate/proxy evidence, blocked claims, and remaining uncertainty.

Prefer concrete stop language: “If blocked, stop with the exact blocker and what would unlock progress.” Avoid weak endings like “do your best.”

Review checklist

Before returning a goal, verify it answers:

• Can the agent tell when it is done?
• Can the user independently audit that completion claim?
• Are regressions and forbidden approaches named?
• Does the goal allow iteration without inviting unlimited drift?
• Does it define what to do when tests, credentials, network, data, or product decisions block progress?
• Is it pasteable as one /goal command?

Examples

Weak:

/goal improve logging

Strong:

/goal Implement structured runtime logging, verified by targeted logger tests, the full project check/type/test suite, and final audits showing no production console.* calls outside approved CLI/UI/logger-sink exceptions. Preserve existing operator-visible console behavior, avoid logging secrets or credentials, and keep the logger generic rather than error-only. Between iterations, inspect the diff and audit remaining catch paths before deciding the next change. If blocked, stop with the unverified requirement, evidence gathered, and the next input needed.

Weak:

/goal fix flaky checkout test

Strong:

/goal Diagnose and either fix or conclusively characterize the flaky checkout test, verified by a reliable local reproduction or an evidence-backed failure analysis plus the relevant test command passing when a fix is made. Preserve public checkout behavior and avoid broad timing hacks unless the evidence shows timing is the root cause. Between iterations, record the hypothesis tested, command output, and next most likely cause. If the flake cannot be reproduced or no safe fix remains, stop with attempted reproductions, logs, suspected causes, and the missing evidence needed.

Weak:

/goal reproduce this paper

Strong:

/goal Produce the strongest evidence-backed reproduction of the paper using available local resources, verified by a final claim-by-claim report and any generated artifacts or runnable checks. Attempt the headline results where feasible, label approximate reconstructions separately from exact reproductions, and do not overclaim missing seeds, checkpoints, datasets, or implementation details. Between iterations, map claims to available evidence and prioritize the highest-value verifiable claim. If exact reproduction is blocked, stop with confirmed claims, proxy evidence, blocked claims, and the specific missing materials.