goal-decision

Files (1)

• SKILL.md

SKILL.md (first lines)

# Goal Decision Skill

Use this skill before creating or recommending a Codex `/goal`. Your job is to classify the task, explain the decision briefly, and produce either a strong `/goal` or a better normal prompt.

## Core rule

Use `/goal` only when the task is a durable, evidence-checkable objective whose next step may depend on what Codex learns while working.

Do not use `/goal` merely because the task is large. Use it when there is:

1. a single coherent objective,
2. a verifiable completion condition,
3. an iteration loop or uncertain path,
4. enough repo, data, test, benchmark, log, issue, or source context to check progress,
5. clear constraints and boundaries,
6. a safe stopping condition for success, blockage, user approval, or budget exhaustion.

## Decision classes

Return exactly one of these classes:

- `USE_GOAL`: The task should be converted into a `/goal`.
- `USE_PROMPT`: A normal one-off prompt is better.
- `REFINE_FIRST`: The task may become a Goal, but required completion or verification details are missing.
- `PLAN_FIRST`: The task is broad or architectural enough that Codex should draft a plan first, then convert the approved plan into a Goal.
- `REQUIRE_HUMAN_APPROVAL`: The work includes high-risk operations and should not run autonomously without explicit checkpoints.

## Use `/goal` when

Prefer `USE_GOAL` when most of these are true:

- The task may take many steps or multiple turns.
- The finish line is clear enough to verify.
- The path is uncertain: Codex may need to inspect, run, patch, benchmark, retry, compare, or research.
- The task has a validation loop, such as tests, benchmarks, CI logs, screenshots, evals, generated artifacts, or a final audit report.
- The user would otherwise keep saying “continue,” “try the next fix,” “rerun tests,” or “keep going until done.”
- Failure modes can be handled with a blocked stop condition.

Good examples:

- Reproduce and fix a flaky test.
- Reduce latency below a threshold while keeping tests green.
- Migrate a package or framework while preserving public behavior.
- Investigate a CI failure until fixed or clearly blocked.
- Reproduce a paper, benchmark, or claim set and produce an evidence ledger.
- Optimize prompts against an eval suite until a target score or blocker.
- Implement a PLAN.md with milestone validation.

## Do not use `/goal` when

Prefer `USE_PROMPT` when any of these are true:

- The task is a one-line edit, one-off explanation, simple code review, small refactor, or direct answer.
- There is no meaningful continuation loop.
- Success can be judged immediately from one response.
- The request is a loose backlog or unrelated task bundle.
- The user only wants options, advice, or a draft, not persistent execution.
- The task has no accessible evidence surface.

Examples:

- “Explain this error.”
- “Rename this variable.”
- “Review this function for obvious bugs.”
- “Write a README paragraph.”
- “What does this command do?”

## Refine before Goal

Return `REFINE_FIRST` when the task is Goal-shaped but missing one or more essentials:

- target outcome,
- verification command or artifact,
- acceptable boundaries,
- constraints that must not regress,
- allowed approximation/proxy evidence,
- stop condition for blockers,
- human approval points.

Do not ask more than three clarification questions. If the missing details can be inferred safely, make conservative assumptions and label them.

## Plan before Goal

Return `PLAN_FIRST` when the objective is coherent but too broad to safely execute directly. This is common for:

- new product builds,
- major architecture changes,
- multi-module migrations,
- ambiguous UX implementation,
- large research projects without a claim inventory,
- any task where milestones must be approved before execution.

Output a `/plan` prompt or a plan-producing normal prompt. Do not output a final `/goal` unless the user supplied enough detail to make completion auditable.

## Human approval required

Return `REQUIRE_HUMAN_APPROVAL` when the task includes actions that should not proceed autonomously, including:

- production deploys,
- destructive data migrations,
- deletion or irreversible writes,
- credential, secret, billing, access-control, or permission changes,
- legal, medical, financial, security, or compliance-sensitive changes,
- changes affecting customer data,
- broad dependency upgrades with unknown blast radius,
- any command likely to mutate external systems.

In this case, propose a Goal only if it includes explicit approval gates before high-risk actions. Otherwise propose a safer investigation-only prompt.

## Scoring rubric

Score each dimension from 0 to 2:

- `objective_clarity`: Is there one coherent end state?
- `verification_surface`: Are tests, benchmarks, logs, artifacts, or source evidence available?
- `iteration_need`: Does progress require inspect-run-change-check loops?
- `scope_boundaries`: Are files, systems, tools, and constraints bounded?
- `autonomy_safety`: Can Codex continue safely without risky irreversible actions?

From andy4917/Agentic-workspace-software, Apache-2.0.

More from andy4917/Agentic-workspace-software