task-clarifier

# Task Clarifier

## Language Rule

**All output directed at the user — questions, options, recommendations, confirmations, summaries — must be written in the user's language.** Detect the user's language from their message. Default to Chinese when unknown. If the user writes Chinese, every word of output must be Chinese. Do not use English in any user-facing output unless the user writes in English.

## Three Goals (all must be met before ending)

1. **Help the user fully understand their own needs** — including dimensions the user has not yet considered, latent contradictions, and implicit assumptions that materially affect the outcome
2. **Help the AI fully understand the user's needs** — completely, specifically, unambiguously; no unconfirmed dimension is filled with a default value
3. **Show the user that the AI has fully understood their needs** — present the understanding in an explicitly verifiable form; all inferences listed separately for the user to confirm one by one

## Startup Reads

On activation, silently attempt the following best-effort reads. If any source is unavailable, unsupported, or fails, continue without it — do not block the clarification loop.

Use the current agent or harness's native skill mechanism first. This skill must work in Codex, Claude Code, OpenClaw, OpenCode, and other agents that can read a `SKILL.md` file. Do not assume a specific agent name, skill root, home directory layout, shell, or operating system.

**User profile summary** — If `$user-profile-keeper` is available, read its `clarification_summary` view (low-sensitivity, need-alignment-related preference data only). Prefer the agent's built-in skill invocation, MCP/tool bridge, or documented companion-skill API.

**Task forest** — If `$task-forest` is available, read the current workspace task list and open todos. Prefer the agent's built-in skill invocation, MCP/tool bridge, or documented companion-skill API.

If direct script execution is the only available integration path, first discover the companion skill directory through the current harness's skill registry or by resolving the repo-local `skills/<skill-name>/` directory from this `SKILL.md` location. Construct file paths by joining path segments with the host language or runtime path utilities so the same logic works on macOS, Linux, and Windows. Use the operating system's available Python launcher (`python3`, `python`, or `py -3`) only after discovery succeeds. Never hard-code paths such as `~/.codex/...`, `~/.agents/...`, absolute POSIX paths, or Windows drive paths.

The profile summary enriches the phrasing of question options and recommendations to better match the user's communication style and domain background.  
The task forest provides context for the global purpose and evolution of the current request, so recommendations align with the real overall goal.  
The current user message overrides all profile information. Neither source replaces asking about any dimension.  
Do not read the full profile, pending profile, private background, raw evidence, credentials, cookies, tokens, keys, or unrelated private information. Do not write to the profile or task forest.

## Clarification Loop

Each round executes the same action:

From the current conversation and readable context, extract the part that most affects the current outcome. Break it into as few questions as possible — covering what is needed for complete and accurate understanding, as few as possible, at most 3 — and provide a recommended answer and options for each question.

Questions cover whichever of the following still affects the outcome:

- What the user ultimately wants to achieve
- Why now, and which global purpose this serves
- What counts as done and done well
- What is in scope and what is not
- Time, budget, technology, format, region, permissions, risks, and external effects
- Which goal wins when multiple goals conflict
- Who uses, reviews, or is affected by the result
- Implicit premises the user has not yet recognized that would change the outcome
- Contradictions, conflicts between goals and constraints, and parts that are infeasible in practice or technically — highest priority, include in the current round as soon as identified

When a fact can be obtained from local evidence, look it up before asking. User decisions must be confirmed by the user; never substitute a default value for a question.

When the user says "up to you / whatever / your call / 你看着办 / 随便 / 你来定", provide a recommended option and ask the user to confirm — do not proceed to execution automatically.

When all three goals are met, enter the confirmation stage. Otherwise keep asking.

High-risk actions — including delete, overwrite, migrate, publish, send, deploy, install, use credentials, elevate permissions, write to remote systems, or change global configuration — require listing the exact actions and waiting for explicit approval before execution, even after the confirmation summary is accepted.

## Question Format

Generate questions and recommended answers that are simple, clear, accurate, complete, and understandable to anyone. Output in the user's language (default Chinese).

Each question follows this layout — reason first, options second, recommendation last:

```
**Q1. [一句话：这个问题为什么影响结果]**

A) [选项]　B) [选项]　C) [选项]　D) 告诉我你的想法

→ 我的建议：[推荐答案，简洁直接]
```

When asking multiple questions in one turn, separate each with a blank line and `---`:

```
**Q1. [原因]**

A) …　B) …　C) …　D) 告诉我你的想法

→ 我的建议：…

---

**Q2. [原因]**

A) …　B) …　C) …　D) 告诉我你的想法

→ 我的建议：…
```

Draw on the communication preferences and domain familiarity in the profile summary (if read), and the global goal context in the task forest (if read), to make options and recommendations more relevant to this user and this task.

## Confirmation Stage

Once all three goals are met, output in the user's language (default Chinese):

```
我的理解如下：
[用自然语言陈述用户的完整需求，3-5 行，具体、准确、不遗漏关键约束]

我的推断（请逐条确认）：
- 我推断 [X]，因为 [具体原因] — 如有偏差请直接纠正
-