clarify-and-goal

name	clarify-and-goal
description	Use when a task is ambiguous, needs Codex Plan mode, native user-question tooling, /goal setup, MCP elicitation handling, or when a subagent reports blocked, partial, low-confidence, or needs-user status.

Clarify and Goal

Purpose

Use this skill to turn ambiguous work, unclear acceptance criteria, or fuzzy test-quality expectations into native Codex questions, clear decision packets, and safe partial work. Keep long-horizon goals broad and measurable; push implementation detail into Task Master tasks, subtasks, and notes so the goal stays stable as new slices appear. Batch reasoning before tools: decide whether the slice is deterministic or decision-dependent before the first command, then prefer a Spark lane for the smallest bounded pass.

Use the installed $define-goal skill alongside this one when the main need is to shape or improve the actual goal text. This repo-local skill owns the Library Ops routing rules, native question path, and escalation contract. Broad goals stay broad and measurable. Concrete implementation detail belongs in Task Master tasks, subtasks, or notes before coding. If new slices appear, promote them into Task Master instead of widening the goal. When a slice branches, hand off a bounded child worker instead of widening the root-local pass.

Use command_runner, context_gatherer, and implementer as the first delegation lanes for command, evidence, and small implementation slices; keep root-local shell/file exploration available when the coordinator owns the slice or when a direct pass is the clearest proof path. When you delegate, say whether the worker is a fork or a fresh spawn, name the inherited context, prefer reuse over close+respawn, split overlapping slices into separate worktrees before conflicts appear, and include the expected commit scope plus local gate list before push. If a branch has been force-pushed, replaced, or superseded, refresh live PR checks and mergeability evidence against the current head before treating earlier results as current.

Current sources

Treat these as the durable repo-local sources for this workflow:

• AGENTS.md for coordinator posture and source order.
• docs/PRD.md and specs/001-core/ for requirements.
• .codex/agents/*.toml for agent routing metadata.
• .agents/skills/code-intelligence/SKILL.md for tool-routing boundaries.
• Read the matching SKILL.md entrypoint from .agents/skills/ directly. Do not use Serena memory reads or other proxy lookups to decide which skill or goal route applies.
• SETUP.md and package.json for the validation ladder.

Procedure

1. Read the current Task Master task, PRD section, relevant spec, and the matching SKILL.md entrypoint from .agents/skills/ directly.
2. Decide whether the issue is deterministic or decision-dependent. Treat unclear acceptance criteria, pass/fail evidence, or test-quality expectations as decision-dependent.
3. If deterministic, route the narrow command, evidence, or implementation slice to command_runner, context_gatherer, or implementer before broadening root-local work or running the next validation.
4. If decision-dependent and interactive Codex exposes native user-input tooling, use it with the Question packet shape.
5. If native user-input tooling is unavailable or non-interactive, print the Question packet and stop with needs-user.
6. If the task is long-running, route goal shaping through $define-goal and keep this skill focused on question/escalation routing.
7. If a subagent raised a concern, normalize it into an Escalation packet, stop the blocked branch, and pass it to the coordinator without continuing adjacent implementation work.
8. If the branch changed beneath you, refresh live PR checks and mergeability evidence before using older review or deployment claims.

Native Codex question preference

Start ambiguous work in /plan before choosing implementation steps.

Use the active Codex surface in this order:

1. request_user_input in interactive Plan mode when available.
2. ask_user_question when the active build exposes the questionnaire UI/tool.
3. MCP elicitation when tool_call_mcp_elicitation surfaces a server-originated request.
4. Plain Question packet in the transcript for non-interactive or unsupported surfaces.

Do not add removed or under-development feature flags merely to force a tool. Verify the active surface with codex features list.

Question packet

Question packet
Decision needed:
Why this blocks or changes risk:
Options:
  A. <option> — tradeoff
  B. <option> — tradeoff
Recommended default:
Confidence:
Can proceed without answer? yes/no
Safe partial work while waiting:
Files/tasks affected:
Validation after answer:

Escalation packet

Escalation packet
Status: clear | needs-user | blocked | partial
Confidence: 0.00-1.00
Finding:
Evidence:
Risk if ignored:
User question needed:
Recommended default:
Partial work safe to continue:
Owner agent:
Next validation:

Goal text, quantitative outcome shaping, and budget policy live in $define-goal. This skill should only hand goal work off there rather than owning a second goal template.