Imported from som1shi/pi-config (skills/goal-crafter/SKILL.md). Install upstream with npx skills add som1shi/pi-config --skill goal-crafter. Copyright stays with the author.

Goal Crafter

Craft one high-quality /goal command for Pi's local pi-goal-supervisor.

This skill writes a goal contract. It does not start the goal, implement the work, or run an autonomous loop.

When the user explicitly asks for goal crafting, goal-skill iteration, broad session-history research, or goal-design research, do not ask permission for read-only research, subagent research/review, or creating or updating the requested local skill artifact. Put temporary notes under .scratch/; a strict no-file or no-artifact instruction forbids them. Keep working until the evidence is sufficient or a real safety or permission blocker stops the task.

Trigger

Use this skill only for explicit goal-crafting intent, such as:

• "write a /goal"
• "give me a good /goal for this"
• "turn this into a goal"
• "goal for current work"
• "resume this as /goal"
• "review/refine this /goal"
• visible /goal ... text that the user asks to improve

Do not auto-trigger merely because work is messy, long-running, or resumable. In those cases, ask whether the user wants a /goal.

Local /goal semantics

Pi's local /goal is session-scoped and continuation-oriented:

• /goal <objective> starts or replaces the active goal.
• /goal, /goal status, /goal pause, /goal resume, and /goal clear manage it.
• The supervisor queues one continuation at safe idle boundaries; it does not grant tools or permissions.
• Completion requires GOAL_DONE: <specific evidence from transcript/artifacts/verifications>.
• For crafted goals, default to a long-horizon continuation contract: first passing checks, first working output, first benchmark win, or a status summary is not completion unless the user explicitly asked for a small bounded goal or explicitly ends/ships the active goal.
• Blocking requires GOAL_BLOCKED: <specific blocker and evidence that no safe non-asking next step exists>.
• A blocked marker is accepted only when every safe path is blocked by an automatic command/tool/runtime guardrail; a missing required tool, resource, credential, auth, access, or service; or a required protected action that is not authorized and has no safe alternative.
• /goal never asks the user questions while running. When a normal session would ask an in-scope material engineering, product, or workflow question, invoke the forced decision-review gate below. Decision review always chooses the best supported in-scope answer; ambiguity is never a blocker.
• Starting a /goal is evidence that the user intends the task to be doable within an already-approved safe scope; it does not itself authorize sudo, mutating git, external mutation, disclosure/export/persistence, materially effectful private access, HITL, or safety bypasses. Genuine read-only authenticated/private access follows the normal session policy. External mutations are in scope only when the user has approved the exact target(s), action(s), expected effect, and environment boundaries. Otherwise resolve the scope before rendering or encode that path as unavailable. Emit GOAL_BLOCKED only when the protected action is required, no safe alternative can complete the goal, and the marker identifies that exact core blocker.
• Do not center goal design on permission gating. A good goal is a durable objective, scoped work boundary, verification loop, continuation policy, and observable completion evidence; runtime safety and automatic blockers remain separate.
• Do not encode unsupported terminal states as if the supervisor enforces them. No default token budget, wall-clock budget, repeated-no-progress stop, generic "stop if unclear", or decision-review blocker.

Resource posture

/goal uses the same normal configuration, tools, skills, subagents, parent-write ownership, proof, review, reflection, progress, safety boundaries, and completion behavior as an interactive session. It retains normal goal continuation semantics. Its only decision-authority override is that a material question that would normally go to the user goes through forced decision review instead.

Default goal shape for this user is adaptive and long-horizon: the goal should keep choosing safe useful evidence-producing work until the user explicitly ends it or the goal runner can show that no safe useful in-scope options remain. Use a short bounded goal only when the user explicitly asks for one.

When crafting or supervising goals, keep the normal-session resource posture and add only the question-review substitution:

• Follow the normal subagent, parent-write, proof, review, progress, and verification rules. Goal mode does not add another general swarm or workflow layer merely because it is active.
• For every in-scope material choice that would normally ask the user, run a substantial review of that exact question with at least three distinct relevant advisors—reviewer, researcher, planner, adversarial, or another fitting role. Gather further evidence or review angles as needed, validate and synthesize the results, choose the best supported in-scope answer, and record the decision, evidence, assumptions, uncertainty, and rejected alternatives. The gate always chooses; it never returns INCONCLUSIVE or blocks on ambiguity.
• Advisors cannot authorize destructive actions, external mutations, deployment, disclosure, export, persistence, or other protected actions. Read-only work follows the global rule. If a protected action is required and no safe alternative can complete the goal, emit only the supervisor-supported blocker.
• For nontrivial, multi-owner, behavior/API/schema, PR-sized, migration, cross-file, or otherwise risk-bearing goals, create the same visible contract card, plan, and owner map required by the normal workflow before editing. Replace the normal user approval question with the forced decision-review gate.
• The contract card should name previous behavior, desired outcome, public behavior/API/schema/config/env names, compatibility boundaries, required docs/tests surfaces, explicit non-goals, protected actions, and forbidden alternate shapes or artifacts.
• Use session readers, relevant .scratch artifacts, current repo files, and context-mode for large session/log outputs when they materially improve correctness.
• Include web/code research when the objective needs current external facts or local evidence is insufficient.
• Use the normal manager-workflow review stage for every nontrivial plan and final-readiness review. Give reviewers the full goal contract, non-goals, relevant decisions, target, proof/evidence, angle, and stop condition.
• Judge design quality across the complete repeated lifecycle, including failure recovery, deployment, verification, cleanup, and final state. Prefer the best, cleanest, most cohesive complete design; minimize components only when doing so omits no required lifecycle behavior.
• Automatically apply only validated, mechanically local, non-material fixes inside the goal behavior, then return control to manager-workflow.
• Run all relevant read-only verification automatically. Mutating validation, disclosure, export, persistence, deployment, or destruction requires an already approved exact boundary; advisors cannot authorize it.

Evidence priority

Build the goal from evidence in this order:

1. Latest explicit user instruction in the current session.
2. Current system/developer/project instructions, especially AGENTS.md.
3. Current repo state and relevant files/docs named by the task.
4. Active TODOs/task trackers.
5. Current .scratch/ artifacts, run outputs, plans, reviews, and handoffs.
6. Most recent compaction or Continuation card:.
7. Relevant session history directly tied to the same task.
8. External docs or best-practice sources.
9. Community examples.

Rules:

• Newer and primary evidence beats older summaries.
• If the user pauses or redirects a hypothesis, mark that branch stale and make the new branch current.
• Compactions, session history, TODOs, .scratch files, and historical artifact paths are recovery indexes, not final authority, fixed scope, or required execution order.
• Existence-check and read historical artifact refs before treating their contents as evidence.
• Prefer search terms, source-of-truth discovery, and evidence trails over hardcoded lists of old paths or old findings inside the final goal.
• Separate current facts from historical continuity.
• Mark stale, superseded, contradicted, or unverified facts explicitly.
• Do not mine unbounded history. Stop once evidence is enough to identify objective, constraints, verification, and blockers.
• When researching goal-making or task-spec practice, weight experienced practitioner reports, primary/creator sources, and frontier AI-agent/spec/eval sources above beginner acronym guides, SEO listicles, or generic framework summaries.
• Do not let framework labels drive the goal shape. Use external frameworks only for ingredients that improve this specific goal's evidence, continuation, obstacle handling, or verifier.

Procedure

1. Confirm mode and scope

• Goal: produce exactly one fenced text block containing one /goal ... command.
• The final response must have no intro, outro, caveat paragraph, or second code block. The first non-fence text inside the block must start with /goal .
• Do not implement the underlying task.
• Do not start the goal for the user unless the user explicitly asks after seeing it.
• Do not make material product/API/scope/workflow decisions silently.
• Do not ask for approval for routine local research, artifact notes, or requested local skill-file creation/update when goal crafting or goal-skill iteration is already the task.

2. Gather current context first

Inspect what tools can answer before asking. If the user provides an exact local path as the target, read or inspect that path directly before asking clarifying questions, especially when the surrounding context implies inspect/debug.

Inspect:

• latest user request and corrections,
• unresolved decisions,
• active TODOs or progress trackers,
• open blockers and approval gates,
• current cwd/repo/instruction constraints,
• relevant files/docs named by the task.

Use session history only when it is directly relevant to the current task. Stable agent behavior belongs in AGENTS.md, repository-local Pi decisions in DECISIONS.md, and temporary research in .scratch/; do not create another persistence path from inferred preferences or raw transcripts. Research/review artifacts should be curated and safe: do not include raw secrets or secret-like values, and if a scanner flags an artifact, require redaction/rewrite before treating it as final evidence.

3. Gather continuity evidence

When the user asks to use "current session", "previous conversation", "compaction", "where we left off", or similar, inspect the relevant continuity sources:

• recent session messages,
• compaction summaries and Continuation card: sections,
• saved .scratch/ research/plans/reviews/sessions/runs artifacts,
• prior session examples only when topic-matched.

Extract only facts that affect the goal: current objective, latest status, constraints, verification evidence, blockers, stale branches, and next safe action.

4. Build an adaptive long-horizon goal by default

Default format:

/goal <one measurable objective>.

Context discovery:
- Reconstruct the current task context from the latest user request, current repo/docs/config, relevant TODO/compaction/session history, and relevant `.scratch` artifacts.
- Treat TODOs, compactions, prior sessions, and `.scratch` artifacts as discovery pointers, not authority, mandatory execution order, fixed scope, or hardcoded goal content.
- Re-verify important historical claims from current source, docs, config, transcript evidence, or fresh checks before relying on them.
- Use search terms, source-of-truth discovery, and evidence trails instead of hardcoded lists of old paths or old findings.

Scope:
- In scope: <bounded objective area, source-of-truth discovery, verification surfaces, and safe quality ratchet work>.
- Out of scope: <explicit non-goals, approval-required actions, unsafe/private/destructive routes>.
- Scope may shift only when fresh evidence shows a better in-scope target; record the reason before continuing.

Constraints:
- <project/user/tool safety rules that must remain true>
- <forbidden or protected actions not already authorized>
- Use the normal session config without asking the user questions while the goal runs.
- Follow the normal parent-write, subagent, proof, review, progress, and verification contract; do not add a second goal-only orchestration layer.
- For every in-scope material decision that would normally ask, force substantial review by at least three distinct relevant advisors, gather more evidence as needed, choose the best supported answer, and record the decision, evidence, assumptions, uncertainty, and rejected alternatives. Never return `INCONCLUSIVE` or block on decision ambiguity.
- For nontrivial work, use the normal visible contract card and owner map, then final independent review against them.

Minimum acceptance:
1. <verifiable acceptance criterion + required evidence>
2. <verifiable acceptance criterion + required evidence>
3. <verifiable acceptance criterion + required evidence>

Verification:
- <exact safe local checks/artifacts to inspect, or a first criterion to discover valid checks if unknown>
- Map each Minimum acceptance item to fresh evidence from transcript, artifacts, diffs, checks, docs, or review.
- Use model-selected behavioral proof; do not force baseline/build/typecheck/live checks when irrelevant.
- Complete the review/fix stage owned by `manager-workflow`; the main agent validates and synthesizes its evidence.
- Include final verification against the contract card, owner map, tests/docs evidence, scope and artifact hygiene, and forbidden artifacts.
- Account for generated/untracked artifacts, debug outputs, and implementation locations before GOAL_DONE.
- Treat live/external/expensive/effectful/protected validation as unavailable unless its exact action and boundary were already approved.

Continuation policy:
- Work in smallest evidence-producing steps.
- Do not treat first passing checks, first working output, first benchmark win, or status/morning summary as completion.
- After each meaningful step, choose the next safest useful in-scope action: source inspection, benchmark refinement, implementation, simplification, compatibility check, regression test, docs update, cleanup, review, or progress handoff.
- GOAL_DONE is valid only when the user explicitly asks to end/finish/ship the active goal, or when Minimum acceptance is proved and the runner can state with evidence that no safe useful in-scope option remains.

Blocked only if:
- <verified automatic command/tool/runtime guardrail blocks every viable safe path; a required tool/resource/credential/auth/access/service is missing; or a required protected action is not authorized and no safe alternative can complete the goal>
- Never block for an unresolved engineering, product, or workflow decision; the forced review must choose the best supported answer.
- For a required unauthorized protected action, emit exactly `GOAL_BLOCKED: required protected action not authorized; no safe alternative: action=<specific action>; effect=<required effect>; evidence=<evidence>`.
- For another allowed class, emit GOAL_BLOCKED with the specific blocker and evidence that no safe non-asking next step exists.

Keep the command paste-ready as exactly one fenced text block and no surrounding prose. Include only details the goal runner needs. Do not paste evidence inventories, old paths, old findings, or todos as hardcoded requirements. Include exact paths/names only when they are the current target, an authoritative current source of truth, or necessary for locating the work; otherwise encode discovery terms, source-of-truth search, and re-verification policy.

Before rendering, apply these internal shape-fit checks. Do not emit framework names or extra sections by default; expose the underlying detail only when it materially helps the runner:

• Separate the durable outcome, progress loop, and completion evidence.
• For known-path work, make acceptance criteria specific, atomic, observable, bounded, and tied to verifiers.
• For uncertain or frontier work, include the smallest bounded experiment or probe that can produce decision-grade evidence, then continue based on that evidence.
• For repeated failure, risky quality ratchets, or likely friction, include obstacle/fallback thinking as safe next actions, not as new stop/block rules.
• For bad-win risks, fold anti-goals into non-goals, constraints, or forbidden alternate shapes.
• Distinguish progress actions from completion evidence; do not treat effort, a first pass, or the agent's own confidence as proof.
• Prefer external evidence: commands, diffs, screenshots, logs, benchmarks, source citations, live checks, or accepted review findings. Self-review may supplement evidence but cannot replace it.
• Calibrate scope as either minimal bounded completion or adaptive quality ratchet according to the user's request; do not silently choose one.
• Do not let weak stop framing such as "probably stop once checks pass" collapse a quality-sensitive, integration-sensitive, or "actually good/use your judgment" request into checks/docs-only acceptance; keep live behavior, source-backed gaps, and options-exhaustion evidence when the task plausibly needs them.
• For tool, extension, CLI, provider, integration, rendering, or prompt-behavior goals, checks/docs-only acceptance is invalid unless the user explicitly asks for only checks/docs. Include at least one representative live, replay, harness, screenshot, transcript, or behavior-smoke verifier, or state that live behavior remains unavailable/unverified.
• Use exhaustive inventories, matrices, rationale, and phase detail only when the user explicitly asks for everything, a comprehensive contract, or equivalent depth. Otherwise keep the goal compact while retaining every detail needed to execute and verify it.

5. Adapt the goal to the task shape

For bug or unexpected-behavior goals, include this spine in the acceptance criteria:

• reproduce or observe the exact failing command/input and current behavior,
• identify the supported root cause before editing, including why the behavior failed before now,
• implement the smallest behavior-correct fix,
• add or update a regression test tied to the failing behavior,
• update user-facing docs when command behavior changes,
• run narrow affected checks first, then the relevant broader check,
• use fresh review for nontrivial fixes.

When the user asks for "better", efficiency, cleanup, or stronger quality after a working first pass, add quality-ratchet criteria instead of stopping at correctness: inspect whether performance, simplicity, maintainability, concurrency/resource bounds, and reviewability are still weak; improve the smallest relevant surface; verify the improvement with fresh evidence.

When live-testing goal-crafter behavior or prompt/skill changes, use natural under-specified probes that are plausible failure cases. Do not only test with prompts that name the exact target, constraints, and acceptance criteria; include vague requests, weak stop framing, and tempting overmanagement language so the test shows how the agent thinks by itself.

Treat phrases such as "overnight", "keep going", "don't stop", "dont stop", "constant improvement", "hillclimb", "ratchet", "fully exhaust options", or "make it better" as cues for the adaptive long-horizon form. These cues strengthen continuation and evidence-refresh policy; they do not authorize unsafe actions, unbounded history mining, or hardcoded old context.

For delegated subagent goals, state that inherited conversation is reference-only unless the task explicitly says to continue it, and give each child a concrete deliverable, scope boundary, validation target, and output contract. For subagent configuration work, verify discovery/registration with subagent doctor/list/get, fix frontmatter schema before assuming files are active, check duplicate builtin/user shadowing, disable only duplicated builtins instead of deleting packaged agents, and explicitly grant needed direct tools rather than relying on parent inheritance. Preserve exact output shape constraints such as bullet counts; when the task says to return exact text, the output contract must forbid extra explanation. For async or long-running delegated goals, include observability handles: run id when known, output/result/session paths, progress files, control thresholds, and when the parent must inspect them. For Pi subagent responsiveness/config goals, verify async support with doctor/status after reload, distinguish asyncByDefault from force-top-level async, and check required runtime pieces such as session dir, jiti resolution, intercom bridge, and lazily-created chain-run directories before declaring the setup broken. For async debugging, include foreground replay, artifact existence checks, and detached stderr/stdout capture when background runs vanish silently. For tool-demo goals, avoid mutating persistence tools unless explicitly permitted and reversible or cleanup is available. If the task is read-only or no-edit/no-artifact, align prose with runtime/output policy: no writes means no output files unless an explicit artifact path is part of the task; do not create .scratch/, change .gitignore, or make convenience artifact setup edits. If the task says do not inspect files, do not include file-read requirements.

For review goals, include exact target files/diffs/artifacts, named risk surfaces, review angle, severity contract (must-fix vs notes), direct inspection requirement, changed-file justification when reviewing a broad diff, and explicit reporting when a relevant check is unavailable rather than passed. If named context files/artifacts are missing, report that and use next-best evidence only when safe and in scope. For post-fix follow-up, return the findings and evidence to manager-workflow; do not reopen unrelated optional cleanup unless requested. Confirm preserved invariants as well as failures so fix passes know what not to break. For PR-comment review goals, revalidate each visible comment against current HEAD and classify it as still-valid blocker, stale/resolved, unverifiable, or non-actionable with direct evidence; do not edit unless the user explicitly asks for fixes.

For ambiguous implementation goals, especially when the user says "think where it lives", include placement/design reconnaissance before edits: inspect architecture, identify candidate locations, choose the cleanest fitting location with evidence, and use advisory subagent/review when the decision is nontrivial. For broad/risky changes, include an evidence-backed recommendation and concrete diff sketch before implementation; prefer canonical ownership and the cleanest complete lifecycle, minimizing touch points only when that does not omit required behavior, verification, deployment, cleanup, or final-state work, and verify whether an existing layer/source of truth already owns the behavior before adding fallback code. If a supposedly simple fix expands because valid review findings expose consistency requirements, add a scope-expansion checkpoint: explain the causal chain, newly touched surfaces, why each is required, and which changes remain separable or out of scope. When the user iterates on architecture or corrects a premise, separate current-state evidence from target invariants, capture the user's corrected contract, and phase implementation/tests around those invariants before editing. For gateway/proxy architecture goals, make the boundary explicit: local clients should marshal requests/responses and hold only gateway credentials, while server-side components own provider keys, provider-specific validation, retries, token counting, uploads, and internals; local access to provider/token-retry-only internals should fail loudly unless explicitly supported. Request serialization should reject unsupported raw/provider objects rather than silently stringify them, and proxy routing should send only explicit safe overrides, not full client-side registry/provider config. For producer/consumer schema migrations, define the consumer-side typed contract, schema tests/docs, and frozen/golden examples before adding ingestion/adapters or changing lower-level producers/agents; keep those phases separate when the user defines that rollout. Reuse authoritative source types for embedded fields when docs say the wire field is exactly that source type, but keep benchmark/product-owned envelope fields in the consuming repo. For stable wire contracts, use explicit versioned top-level models/unions rather than letting V1 silently absorb future V2 fields, and add negative tests for unknown-field drift, missing required wire fields, alias round-trips, and helper usage. When reusing permissive upstream models, pre-validate nested allowed keys if the canonical contract must reject producer drift, and prevent source-model default factories from mutating the wire shape unless the docs require that field. Do not declare adjacent layers out of scope or no-change-needed without inspecting the relevant path. Default scope stays narrow, but if a blocker is proven in an adjacent repo/layer, the goal should allow evidence-driven inspection/fix there and require final review across every changed repo/surface. For separately shipped repos or ignored nested repos, include deployment-order/API compatibility notes and requested PR/status updates so one side does not land with imports or protocol expectations the other side lacks. Distinguish dependency/usefulness from feature/review-unit ownership; do not fold branches or features together merely because one deploy or use case benefits from the other.

For repo-orientation goals, include first-action inspection of AGENTS.md, README/docs, project structure, and relevant code symbols before recommendations.

For product/library/research or feasibility goals, include current source verification: confirm names/spelling, package availability, maintenance maturity, primary docs/source, current code paths, and caveats. Preserve no-edit mode unless implementation is explicitly requested. For feasibility answers, require source-traced root causes, options with effort/pros/cons, a recommended path, risks, and validation design. When the user challenges whether a mechanism breaks the plan, trace the actual current code path and distinguish compatible pieces from incompatible architecture. Do not rely on recollection for current ecosystem claims.

For comparison, architecture-option, or benchmark goals, inspect both sides from source/docs before judging; separate researched facts from inference. Separate decision axes such as raw overhead, correctness, workload fit, managed product vs owned workflow, prototype speed vs long-term control, distributed safety, utilization, simplicity, operational risk, and UX. Test for false binaries when multiple options can run commands, read docs, or expose SDKs. Include what each option would concretely look like, argue from failure modes and concrete needs rather than generic keyword lists, and preserve plausible options instead of forcing one winner when tradeoffs differ. Require honest negative answers when evidence supports them. If benchmark numbers are not apples-to-apples, state why and define a fair workload-relevant benchmark design instead of forcing one winner. Report unavailable checks explicitly.

For config/local-settings goals, preserve the user's requested minimality: diagnose the symptom before editing, change the smallest useful setting set, isolate the harmful sub-setting instead of disabling a desired feature wholesale, avoid broad optional tuning, include the exact validation command, verify the runtime command/process behavior when possible, and require recovery/retry when an initial validation command was malformed.

For local system performance, hardware, audio, display, or daemon debugging goals, do not guess from symptoms alone: collect live process samples, service/journal/kernel logs, relevant config/code paths, package/kernel/firmware versions, and a direct repro or falsification probe before causal claims. Separate symptom recovery from durable root-cause fix; do not call a restart/rebind/reload workaround fixed when the underlying trigger can recur. Track every diagnostic state change, preserve the original settings/profile, restore them before completion unless retaining the change was already explicitly approved; a running goal never pauses to request that approval, and state remaining upstream/version/config risks explicitly.

For OS boot, partition, firmware, or recovery repair goals, treat privileged steps as protected rather than dumping a long script. Run safe non-privileged diagnostics yourself when possible. A running /goal never waits for a user command result: keep privileged handoff unavailable unless the required output is already supplied, continue safe diagnostics, and emit GOAL_BLOCKED only when no safe non-asking path remains. Before copying or rewriting boot/recovery files, require read-only inspection, backups with paths, and post-copy hash/existence verification. For reinstall or partition advice, name the exact partitions to preserve/delete and the expected boot-order/GRUB repair follow-up; do not imply a destructive reinstall is required when a targeted reinstall/repair is enough.

For MCP, model registry, or external integration config goals, inspect existing config, bundled/default/custom config sources, loader precedence, cached/live tool schemas, and current server docs before editing. For MCP tool validation errors, distinguish lazy/cached metadata from bad invocation args: check configured command/binary, cached schema required fields, a bounded live success probe when safe, and logged failed call payloads before blaming server availability or config. For material auth/transport choices, a running goal uses at least three distinct decision advisors and records the supported in-scope choice; genuinely read-only authenticated/private access follows normal policy, while mutation and other protected authorization remain unavailable. Prefer OAuth or environment-based auth over tracked secrets. Validate config syntax, document restart/reload/auth follow-up, and distinguish written config from currently active tool availability.

For UI/rendering goals, include inspection of the exact render path, theme/type APIs, and existing layout constraints; prefer the smallest visual diff; preserve width/layout invariants; and include visual/manual validation or risk notes when automated verification cannot prove the UI result. Use screenshot evidence when available. For command/code block rendering, include copyability as an acceptance criterion: multiline commands should be copyable without decorative borders, gutters, prompts, or box characters unless explicitly intended. For local Pi UI customization, verify the durable ownership layer before editing: prefer the tracked extension/config/fork that survives reinstall/update, and revert accidental installed node_modules patches rather than leaving fragile global-package edits. For Pi extension UI changes, note that source edits may not hot-reload into an already-running Pi process and require restart/reopen verification when relevant. If the UX target is subagents/background tasks, include demo scenarios plus user-visible status/log affordances such as footer/status, selectable runs, and inspectable logs. For subagent rendering, verify live/partial states, pending/running/completed/detached/interrupted semantics, global recent activity, hidden +more counts grouped by type, per-agent last/+more summaries, expanded per-agent lists, and automated coverage for the renderer branches.

For frontend data-visualization or ranking goals, trace the metric from source data through transformation helpers to every displayed, ranked, filtered, or charted surface. Preserve semantic distinctions between hidden/unavailable numeric data and true zero; do not let missing or internal-only values become artificially good ranks. Prefer one shared source-of-truth helper for policy such as visibility, labels, or availability, and require review/verification across every affected visualization or recommendation surface, not just the screenshot that exposed the issue. When displayed rankings change, require an explanation grounded in the ranking/filtering algorithm, not just a before/after screenshot.

For generated data, benchmark exports, or exported artifacts, identify whether the bug belongs in source metadata, acquisition/materialization, parser shape, generator/export logic, generated artifact, downstream aggregate view, or consuming UI before editing. For count mismatches, trace expected vs produced counts at every pipeline boundary: source inputs, generated outputs, uploaded items, queue receipts, result rows, and exported views. Do not silently drop failed/empty generated items when downstream expects one output per source input; either emit explicit failure outputs or hard-fail before launching doomed long jobs. Verify the live/current file contract and ownership model before proposing schema or Lambda design; inspect actual producer/service/lambda implementations for every affected benchmark or data source instead of assuming S3 paths, archive layout, local filenames, or required files from stale scratch samples. State source precedence between live/current source, temp cache, local mirror, and fallback when multiple sources exist. External-storage fallback should only trigger for true missing-object cases; auth, credentials, permission, throttling, configured-run fetch failures, or other infra errors should surface as such and not be relabeled as file-not-found or swallowed into generic failed-item bookkeeping that preserves stale output. Prefer fixing the upstream source of truth and regenerating artifacts with exact commands; include dependency update steps when generated data comes from another repo/package, and include dependent aggregate/index views that must be refreshed together. Preserve existing parser/result shapes when the user asked only to fetch or materialize new inputs; separate acquisition from transformation unless shape migration is explicitly approved. For acquisition-only work, state where fetched artifacts may live, usually system temp or in-memory, and explicitly forbid repo-stored fetched outputs unless requested. If two artifacts are similarly named or related, name which artifact is authoritative for each consumer. Check custom loader/extension paths as well as default paths, and verify locks/hashes/cache invalidation use the same source precedence as the parser/export path so stale local mirrors do not drive rebuild decisions after a configured external run is used. Cache fingerprints for remote artifacts should include object metadata or content identity unless immutability is guaranteed and documented; run IDs alone are not enough for mutable object stores. Preserve user-requested model subsets without shrinking unrelated global metadata or marking unrelated local/stale models as freshly locked, avoid materializing or querying unrelated remote objects, enforce cardinality invariants such as single-run-per-external-result consistently across parser, lock, and materialization paths, and prevent temp-path collisions from multiple external run IDs or provider/model names that share basenames. Distinguish remote lookup keys, parser-shaped S3 object names, and local temp filenames in docs and code: keep externally required artifact names unchanged while making temp paths collision-proof. Remove permissive fallback lookup paths when the producer contract is known; fallback should be justified by real producer behavior, not investigation leftovers. Tests should run builders/parsers on representative fixture inputs and assert semantic outputs, including precedence/fallback/cache-invalidation/partial-export/temp-collision cases, not only validate generated JSON against a schema. If CI cannot access live external artifacts, narrow skips to the specific external-backed benchmark/model/check tuples instead of skipping whole benchmarks or globally excluding model names that also appear in unrelated benchmarks. For live export or migration claims, include a representative end-to-end flow with a complete/equivalent real run when allowed, and compare exported metrics/task coverage against current local/HEAD data before deleting or replacing existing results. Verify freshness with the repo’s stale-export or generated-data checks, match verification scope to the failing command, assert cleanliness for every generated backend and frontend file the command can touch, classify unrelated pre-existing failures separately, and avoid hand-editing generated outputs or UI workarounds for source-data errors unless explicitly requested. When asked whether behavior is fully tested or whether locks/generated outputs will change, separate unit/static coverage from live external validation, state untested live paths, and identify expected one-time cache/lock invalidations versus unchanged local/platform inputs.

For feature-flag or alternate-path goals, include compatibility/regression criteria for existing behavior. State whether old behavior must be byte-for-byte preserved or behaviorally preserved, and require fresh evidence for the old path and the new path.

For persisted formats, serialized files, replay/resume artifacts, compaction/history artifacts, public helper/result formats, or generated configs, include an explicit compatibility/migration decision. If old on-disk or public formats may exist, require tests for old-format reads or a documented no-compatibility decision resolved and recorded through the three-advisor gate. When removing or moving a public/result field, trace downstream consumers, exporters, docs, and tests that reference the old surface, and add path-level tests proving the real provider/server/export path populates the new surface rather than only helper-level tests. Ensure docs match runtime behavior and artifact extensions/names match the serialized content, such as not writing JSON content under a binary-looking extension.

For branch-splitting, stack repair, commit-topology, or commit-organization goals, start with read-only graph/diff recon using exact base/head evidence, changed-path clusters, and feature-slice grouping. Preserve the user's intended branch/PR semantics and existing PR identity; do not invent branch names, rename PR branches, or create review boundaries when the existing meaning is ambiguous. Produce a plan or .scratch/research artifact before any mutating git command. Do not include git mutation steps as automatically approved unless the user explicitly authorized that exact mutation scope. If the user will drive git mutations, include command-by-command handoff: inspect state after each user command, verify preconditions/postconditions, revise stale plans after git-spice restacks or external diff/tool behavior surprises, and copy exact next commands when requested. Adapt to the user's Git UI/workflow: if they use lazygit, say they will commit themselves, or are a git expert, state the branch/context, unstaged file list, PR/head status, and remaining requirement instead of unsolicited checkout/commit/amend/push command blocks; verify actual local/origin/PR state yourself before saying what remains. Explicit plan-review requests should adversarially check branch topology, PR attachment, upstack branches, dirty state, failure modes, and recovery commands before giving the next command block. Rebase/restack conflict goals should resolve by preserving invariants from both sides, then run focused syntax, conflict-marker, diff-check, and relevant tests; after a stack restack, final verification should run from the top branch/final tree rather than an earlier branch missing later code. For dedicated merge-conflict agents, encode that the user initiates gs upstack restack, the agent may inspect gs ls/read-only git state and edit conflicted files, but mutating git-spice commands must be prompt-forbidden and guardrail-denied just like mutating git commands. Before reset/squash/review advice, inspect staged and unstaged scope; keep code changes separate from generated data or migration artifacts unless the user intentionally bundles them. After focused fixes atop staged work, report MM/staged/unstaged state and the exact staging command for the user when useful. For messy history, prefer clean-base patch splitting when appropriate: generate patch files, account for full diff coverage, mark optional/unclassified leftovers, temp-apply patches to a clean base, run syntax/tests per patch, and get a fresh review of patch separation before the user creates branches. Patch-split review must check README/user-command safety, new-file staging, optional patch dependencies, duplicate definitions, stale docs, security behavior, and out-of-scope changes; passing temp tests does not override scope or instruction blockers.

For simplicity/cleanup goals, include locality criteria: avoid unnecessary helper extraction, prefer inline one-use logic when clearer, remove obsolete patches/dead compatibility shims when explicitly requested or proven unnecessary, and run focused checks.

For user-run command or SQL goals, require commands/queries to fit the user's execution surface: local shell, psql, Retool SQL runner, notebook, cloud console, or clipboard. If the user needs one pasteable Retool statement, do not give shell scripts or multi-step local psql -f workflows. Inspect available app models/source schema before resorting to broad database schema-discovery queries. Commands must be executable from the stated cwd and include needed safe environment setup. If terminal/TUI selection adds padding or breaks backslash continuations, prefer semantic clipboard/copy tooling that extracts raw code or individual shell commands, defaults to recent relevant assistant output, combines cd dir plus following command into (cd dir && command ...), and states idle/streaming limitations. If the user asks to run a command themselves or the command is long, copy the exact command with wl-copy when available; never claim it was copied without doing it.

For public-facing copy, teammate-facing plans, docs, screenshots, PR descriptions, or examples, preserve exact output shape, bullet count, verbosity, and no-tool constraints when given. Preserve the user's casual language, section structure, and flow where correct; do not replace it with bureaucratic/business prose. Avoid tables in generated Markdown or other persisted/non-direct output; direct UI/chat may use one only when materially clearer. Prefer short sections with a few nested bullets. For PR descriptions or teammate-facing summaries of technical stacks, separate the high-level core flow from details/hardening/testing instead of flattening everything into one undifferentiated bullet list; update every related PR/doc in the stack when the same structure applies. Present the current plan/decision in the user's requested shape; avoid private migration history, adversarial rationale, or internal debate unless requested. If the user designates a doc/spec as the reference or source of truth, the goal should update that document when decisions or implementation behavior change. If the deliverable is a non-scratch user-facing file, name its exact location; .scratch is not a substitute unless requested. Add privacy/detail constraints: no private usernames, absolute local paths, provider names, repo history, secrets, or internal-only details unless the user explicitly wants them public.

For public repo release goals, include tracked-file and committed-content hygiene: auth/session/cache/crash/onboarding/runtime files, .gitignore, and current commit diffs. Include attribution/license review for copied or adapted configs, docs, extensions, and skills. Public docs should explain the current reusable config and design, not private migration history, session transcripts, personal comparisons, or adversarial rationale. Distinguish intentional personal preferences/assumptions from non-portable hardcoded paths: document retained preferences, change tracked user-specific absolute paths when feasible, leave ignored runtime state alone, and verify sanitization with direct searches.

For public demo or video goals, prefer a staged real coding workflow over a one-shot docs edit: starting user request, visible plan, autonomous decision-advisor/review checkpoints, pi-lens/LSP inspection, small real edit, visible diff/status, and concise final status. The running goal must not pause for ask_user or approval; normal subagent behavior still applies, while noisy duplicate probes do not. Keep prompts and output video-friendly and free of private details.

For live/provider/API validation goals, state external side effects, cost/credential assumptions, bounded smoke scope, and secret-handling constraints. Do not read .env or secret files; use safe environment-presence checks and user-provided credentials only. Preserve identifiers needed for follow-up actions, such as run ids created by --mode new before pausing/cancelling them. When live tests are long-running, require a tmux/background monitor with logs/status artifacts and check-ins rather than a silent blocking command; if a run appears stuck, capture stuck point/status/stack, run narrow suspected checks, then restart the broader check when justified. Verify the running service/container code version matches the working tree or commit under test before trusting live results. For live database checks, discover schema before querying columns. For startup/performance goals, compare relevant modes, identify what each mode loses, measure before/after, and consider moving noncritical work to post-start background tasks.

For infra, security, API gateway, supply-chain incident, or access-change goals, answer can/should/how separately before mutation. Inspect current scripts, docs, lockfiles/package metadata, CI workflows/logs, cloud/security-group state, screenshots/error text, cached IaC context files, and authoritative provider/advisory docs. Treat successful synth/build as insufficient when warnings identify deploy-time risks; surface warnings with file:line evidence and fix required invariants such as known-length imported lists for CDK VPC/subnet attributes. Verify comments, Dockerfile descriptions, and runbook claims match the actual command/install behavior after infra changes. Treat client-supplied config as untrusted: allowlist safe user-facing inference parameters and reject routing/internal fields such as custom endpoints, API keys, client registry options, or transport settings unless explicitly designed and secured. Preserve or verify replacement and break-glass access paths before removing public exposure; defer irreversible cleanup until access is proven. Treat cloud/network/security mutations as unavailable unless exact targets, expected effects, and environment boundaries were already authorized. A running goal never waits for approval; continue safe read-only work, or emit GOAL_BLOCKED only when no safe non-asking path remains. After an authorized mutation, verify primary access, backup access, and cleanup state. For package compromise incidents, distinguish repo checkout/CI installs that use this repo's lockfile from package consumers that resolve from published metadata; fix both install commands and package constraints when needed. Do not bypass package registry quarantine. Scope log scans to the actual compromise window once known, but say when org-wide or local-developer exposure has not been fully checked. Investigate all install surfaces with secrets, including CI, publish jobs, deploy workflows, Docker builds, local developer machines, sandbox/agent install commands, and downstream repos consuming the package. Secret rotation guidance should separate direct CI/GitHub secrets from secrets only reachable through cloud credentials; use CloudTrail/object-level access where possible and state IAM last-access lag/granularity caveats before deciding a secret did not need rotation. For signing, HMAC, encryption, auth, or integrity features, test falsy/empty credential cases and ensure docs/names state the exact protection boundary; do not imply whole-object integrity when only a field/blob is protected. Security docs must match the actual intended policy and tested behavior; if code/tests and docs disagree on pass-through, rejection, unsigned behavior, or trust boundaries, decide/fix the policy before claiming documentation is updated. Readiness/startup checks should validate all prerequisites needed for real non-health requests, including auth/security config, not just backend/provider availability. For access-control debugging, distinguish install state, tag/owner approval, ACL policy, host user existence, control-plane records/names, network reachability, and actual login success. For host privilege escalation, analyze whether SSH/ACL policy lets other users assume that Unix account before granting elevation; prefer tightening identity mapping first or asking explicitly. For access docs based on user-supplied messages, follow the requested operational shape and tone; do not replace a non-safety-affecting requested instruction with personal best practice.

For operational or integration-sensitive goals, cover current-state research through the explicitly approved deployment or mutation, live user-flow validation, cleanup, and verified final operational state. Match verification to the real user flow that failed; static checks and unit tests alone do not prove that live workers, queues, containers, or CLIs actually behave correctly. For thorough testing, define a bounded representative matrix of user flows, such as CLI path vs direct API path, pause/resume or retry variants, cleanup state, and regression paths, while avoiding unnecessary provider spend. Before trusting container/dev-server results, verify the runtime contains the changed code. Server/resource lifecycle work should include close/reset behavior for clients, pools, Redis/database handles, and reload/test lifecycles. API goals should map malformed client input to stable 4xx errors instead of leaking internal 5xx paths. For complex concurrency changes, require a concise protocol explanation of the new behavior. Include end-of-work hygiene before GOAL_DONE: restore or account for temporary fixtures/data, check scoped dirty state in every touched repo, check relevant background processes/runs, state final dev-stack/service state, close or update local todos/progress/handoffs when available, update requested PR/docs/status text without overwriting unrelated content, and separate proved behavior from operational remediation for old state and residual risks.

For cancellation, timeout, queue, retry, or long-running provider goals, include realistic failure-mode criteria: slow provider calls, slow Redis/database fallback, cancellation cleanup/drain behavior, timeout bounds, and no stuck/hanging shutdown paths. For queue protocols, include key lifecycle, wake semantics, lost-wakeup checks, resume/cancel interactions, Redis key inspection with expected prefixes, cleanup state, and practically relevant race tests. Model resources explicitly: what blocks the Redis server, event loop, pooled connection, worker, run, and per-item fanout; compare alternatives by observed failure mode, wake latency, Redis load, connection use, and worker occupancy. For edge-case verification, enumerate the matrix of covered cases and require blockers-only findings with file:line refs and missing tests. Require practical-risk triage: fix realistic user-impacting failure modes, and explicitly name/defer low-value theoretical races instead of overengineering them.

6. Use expanded continuity form only when warranted

For schema or data-contract docs, include source/derivation annotations when relevant: which fields are copied from source artifacts, which are derived, which are optional/future, and which raw details are retained for downstream recalculation. Prefer a clear order such as current/top-level facts, then derived fields, then raw details.

Use the expanded continuity form for explicit resume/high-risk/cross-session requests, or whenever the user uses long-horizon cues such as "overnight", "keep going", "don't stop", "constant improvement", "hillclimb", "ratchet", or "fully exhaust options":

/goal <one measurable objective>.

Context discovery:
- Current task: <fresh current-session task>
- Known current state: <confirmed facts with file/session/artifact refs>
- Historical continuity: <prior session/compaction facts, explicitly marked historical>
- Stale branches to ignore: <superseded work, if any>
- Discovery rule: treat TODOs, compactions, prior sessions, and `.scratch` artifacts as pointers to re-verify, not as hardcoded required paths, stale findings, fixed scope, or mandatory execution order.

Scope:
- In scope: <bounded areas plus safe source-of-truth discovery and quality ratchet work>
- Out of scope: <non-goals and approval-required/unsafe/private/destructive routes>
- Scope may shift only when fresh evidence proves a better in-scope target; record the reason before continuing.

Constraints:
- <preserve invariants>
- <protected actions unavailable unless already authorized>
- <follow AGENTS.md/project workflow/tool rules>
- Use the normal session config without asking the user questions while the goal runs.
- Follow the normal parent-write, subagent, proof, review, progress, and verification contract; do not add a second goal-only orchestration layer.
- For every in-scope material decision that would normally ask, force substantial review by at least three distinct relevant advisors, gather more evidence as needed, choose the best supported answer, and record the decision, evidence, assumptions, uncertainty, and rejected alternatives. Never return `INCONCLUSIVE` or block on decision ambiguity.
- For nontrivial work, use the normal visible contract card and owner map, then final independent review against them.

Minimum acceptance:
1. <criterion with required proof>
2. <criterion with required proof>
3. <criterion with required proof>

Verification:
- <safe local commands, artifact checks, review checks, screenshots, logs, file:line refs, or other proof>
- Match verification scope to requirement scope; narrow checks cannot prove broad claims.
- Map each Minimum acceptance item to fresh evidence from transcript, artifacts, effective changes, checks, docs, or review.
- Complete the review/fix stage owned by `manager-workflow` and synthesize its evidence.
- Include final verification against the contract card, owner map, tests/docs evidence, scope and artifact hygiene, and forbidden artifacts.
- Account for generated/untracked artifacts, debug outputs, and implementation locations before GOAL_DONE.
- Do not run live/external/expensive/effectful/protected validation unless its exact action and boundary were already authorized.

Continuation policy:
- Work in smallest evidence-producing steps.
- After a failed check, inspect root cause before retrying.
- Do not redefine success around partial progress or an easier subset.
- Do not treat first passing checks, first working output, first benchmark win, or status/morning summary as completion.
- Re-read current goal/continuity notes after compaction or long interruption.
- After each meaningful step, choose the next safest useful in-scope action until the user explicitly ends the goal or no safe useful in-scope options remain.
- GOAL_DONE only when Minimum acceptance is proved and either the user explicitly asks to end/finish/ship the active goal or the runner can state with evidence that no safe useful in-scope option remains.

Blocked only if:
- A verified automatic command/tool/runtime guardrail blocks every viable safe path.
- A required tool, resource, credential, auth, access, or service is missing, and no safe non-asking workaround exists.
- A required protected action is not authorized and no safe alternative can complete the goal.
- Never use GOAL_BLOCKED for an unresolved engineering, product, or workflow decision; the forced decision-review gate must choose the best supported answer.
- For the protected-action class, emit exactly `GOAL_BLOCKED: required protected action not authorized; no safe alternative: action=<specific action>; effect=<required effect>; evidence=<evidence>`.
- For another allowed class, emit GOAL_BLOCKED with the specific blocker and proof that no safe non-asking next step exists.

Ambiguity handling

Research first. Collect unresolved material questions instead of interrupting the user one by one. Immediately before rendering, ask once for all still-unresolved related material decisions. Prefer a structured review UI when available, with each item limited to one focused decision; never combine unrelated questions into a broad multipart questionnaire. When only one decision remains, ask one focused question. A direct safety or permission blocker that prevents safe research must be surfaced immediately rather than deferred.

A pre-render clarification is required when missing information materially changes:

• the objective,
• in-scope vs out-of-scope work,
• acceptance criteria,
• safety/approval boundaries,
• verification standard,
• whether to preserve compatibility,
• whether external/private resources may be read,
• the exact target(s), action(s), expected effect, and environment boundaries of external mutations.

Do not ask for information tools can verify. Do not render while a material contract question remains unresolved.

Only make assumptions for mechanical, reversible defaults already implied by current instructions. Mark them as assumptions outside the /goal block if useful. Do not bake material unapproved assumptions into the command.

If verification is unknown but discovering it is a safe and necessary first step, encode that as the first Minimum acceptance item or first action:

Minimum acceptance:
1. Existing validation commands are identified from repo docs/config and summarized with exact paths.

Do not invent commands.

Progress and review loops

For nontrivial goals, include a progress checkpoint at the start of every distinct material work group or stage, plus material discoveries/blockers and the final boundary: state current objective, what was inspected or changed, key finding/hypothesis/risk, next action, and why it is the highest-value safe option. Do not encode per-tool, weekly, wall-clock, token-budget, or other fixed-cadence semantics unless the user explicitly asks and the runtime supports them.

For nontrivial implementation goals, include final review and must-fix loop criteria. GOAL_DONE is not valid while accepted must-fix review findings remain unless the user explicitly waives or defers them. Passing checks do not override a fresh accepted review blocker. When the user says "go on" inside an already-aut

Truncated - read the full file at https://github.com/som1shi/pi-config/blob/e32239068e30b2feac74882490efebf8f1a1dd39/skills/goal-crafter/SKILL.md.