Skill: zhanghengjing2/cleartask (version 1.0.0)

--- name: clear-task description: Transform broad, ambiguous, or early-stage user requirements into executable work through Stage1 requirement understanding, Stage2 clarification, a required user confirmation gate, and Stage3 internal expert-guided task packaging. Use when Codex needs to understand a user's idea, model a workflow/product/tool/game/document request, ask precise follow-up questions, recommend defaults, produce a user-confirmable requirement handoff, let the user revise the requirement description or requirement details, and only after explicit confirmation continue with Codex, Claude, OpenClaw, coding agents, writing agents, product agents, design agents, testing agents, or workflow-building agents. Do not show the Stage3 package by default; use it as internal execution context unless the user asks to inspect, export, or review it. --- # Clear Task Say it clear, do it right. ## Purpose Use this skill to turn an underspecified user request into an internal `AgentTaskGuidancePackage`, then execute the user's task using that package. Do not display the full Stage3 package unless the user explicitly asks to inspect, export, save, or review it. ## Workflow Run Stage1 and Stage2 first. After Stage2 produces the `UniversalRequirementHandoff`, stop and ask the user to confirm before Stage3. Do not run Stage3 or execute work until the user explicitly approves the Stage2 handoff. 1. Stage1: Build a rich `UniversalProcessModel`. 2. Stage2: Clarify missing details and produce `UniversalRequirementHandoff`. 3. Confirmation Gate: show a concise user-facing requirement summary and ask the user to confirm, revise the requirement description, or revise requirement details. 4. Stage3: Generate an internal `AgentTaskGuidancePackage` using expert-role task guidance and expert-role acceptance criteria. 5. Execute the task using the internal package. 6. Report the result, key decisions, created/changed files, and concise self-check. Do not add a Stage0 intake gate. If the request is invalid, unsafe, or impossible to model, mark it as out of scope inside Stage1/Stage2 and explain the blocker. ## Stage1 Model the user's request as a workflow or work process, even when the request is a product, document, game, analysis, or implementation task. Prefer a graph over a flat step list. Read `references/stage1-universal-process-model.md` when you need the full schema or need to output a Stage1 artifact. Minimum Stage1 output: - `request_summary` - `business_goal` - `scope` - `actors` - `inputs` - `outputs` - `workflow_graph.nodes` - `workflow_graph.edges` - `business_rules` - `assumptions` - `open_questions` - `source_evidence` Keep unconfirmed model inferences in `assumptions` or `open_questions`; do not present them as confirmed facts. ## Stage2 Use Stage2 to close the gaps that would materially change downstream work. Ask the fewest high-value questions needed. When the user asks for recommendations, choose reasonable defaults and record them under `accepted_defaults`. Read `references/stage2-clarification-handoff.md` when generating clarification questions or the final Stage2 handoff. Stage2 is ready for Stage3 when: - blocking questions are answered, or - blocking questions have accepted defaults, and - unresolved details are non-blocking or explicitly left to the downstream agent. Stage2 being ready does not authorize Stage3. It only means the requirement handoff is ready for user confirmation. ## Confirmation Gate After Stage2, always pause and ask for explicit user confirmation before Stage3. Do not continue from Stage2 to Stage3 in the same response. Show a concise user-facing confirmation summary using plain requirement language, not internal stage terminology: - `需求描述`: one short paragraph describing what the user wants. - `需求细节`: scope, deliverables, constraints, accepted defaults, assumptions, and non-blocking open questions. - `需要你确认`: ask whether to continue. Offer these user-facing choices: - `确认，继续` - `修改需求描述: ...` - `修改需求细节: ...` Treat only explicit approval as confirmation, such as "确认", "继续", "可以", "批准", "go ahead", or an equivalent clear instruction. If the reply is ambiguous, ask a short confirmation question and continue to pause. If the user asks to modify the requirement description: 1. Update the Stage1 `UniversalProcessModel`. 2. Re-check whether Stage2 changed because of the revised description. 3. Revise or regenerate the Stage2 `UniversalRequirementHandoff`. 4. Return to this confirmation gate. If the user asks to modify requirement details: 1. Update the Stage2 clarification/handoff content, including scope, defaults, assumptions, constraints, deliverables, and open questions as needed. 2. Do not run Stage3 automatically. 3. Return to this confirmation gate. If a revision introduces new blocking questions, ask only those questions, update Stage2 from the answers, then return to this confirmation gate. ## Stage3 Do not start Stage3 unless the user has explicitly confirmed the Stage2 handoff through the Confirmation Gate. Stage3 always produces an `AgentTaskGuidancePackage`, but this package is internal execution context by default. It does not choose whether the final downstream result should be code, PRD, PPT, Word, test plan, or another artifact. The executing agent decides that from the task package and continues the work. Stage3 must use expert roles: 1. Classify the task domain and downstream work mode. 2. Select one primary expert and supporting experts. 3. Generate expert task guidance. 4. Generate expert acceptance criteria. 5. Compose a consolidated package without inventing new requirements. Read: - `references/stage3-agent-task-guidance-package.md` for the internal package schema and execution policy. - `references/expert-roles-and-acceptance.md` for expert selection and acceptance criteria rules. ## Execution Policy After Stage3, continue execution when: - the user has explicitly confirmed the Stage2 handoff, - blocking questions are resolved or have accepted defaults, - the user asked for a concrete deliverable or outcome, - the task can be completed with available tools and workspace access. Pause and ask before execution when: - the user has not explicitly confirmed the Stage2 handoff, - Stage2 has unresolved blocking questions, - execution would unexpectedly modify many files or external systems, - the task requires credentials, paid services, network actions, or destructive operations, - the user explicitly asked only for analysis, planning, or the internal handoff package. ## Output Rules - Preserve traceability from user input, Stage1, Stage2, and expert recommendations. - Separate `confirmed_facts`, `accepted_defaults`, `assumptions`, and `expert_recommendations`. - Use blocking questions only for decisions that materially alter downstream work. - Acceptance criteria must be verifiable and include pass conditions. - Avoid vague criteria such as "good UX", "complete feature", or "high quality" unless converted into observable checks. - If expert guidance conflicts, keep the conflict in the package and suggest a conservative resolution. - Do not display the full `AgentTaskGuidancePackage` by default. - Use expert acceptance criteria for execution self-check and final concise reporting. ## Internal Package Shape Use this shape internally. Do not render it to the user unless explicitly requested. ```yaml AgentTaskGuidancePackage: title: objective: expected_outcome: downstream_agent_role: confirmed_scope: requirements: process_model: expert_task_guidance: consolidated_execution_plan: expert_acceptance_criteria: consolidated_acceptance_criteria: risks_and_edge_cases: unresolved_questions: assumptions: conflicts: traceability: suggested_next_prompt: ``` ## Default User-Visible Result Before Stage3, report only: - requirement description, - requirement details, - accepted defaults and assumptions, - remaining non-blocking questions, - a clear request to confirm, modify the requirement description, or modify requirement details. After execution, report only: - what was completed, - key decisions or defaults used, - created or changed files/artifacts, - self-check against must-pass criteria, - remaining caveats or non-blocking questions.

path: references/expert-roles-and-acceptance.md
content: # Expert Roles and Acceptance Criteria

Use experts to generate professional task guidance and acceptance criteria. Experts provide domain quality; the Stage3 composer provides consistency. Expert outputs are internal by default and should be used to guide execution and concise self-check reporting.

## Expert Selection

Select one primary expert and zero or more supporting experts.

```yaml
expert_profiles:
  frontend_game:
    primary_expert: frontend_game_engineer
    supporting_experts:
      - game_designer
      - ux_designer
      - qa_engineer

  frontend_web_app:
    primary_expert: frontend_engineer
    supporting_experts:
      - ux_designer
      - qa_engineer

  backend_api:
    primary_expert: backend_architect
    supporting_experts:
      - api_designer
      - security_engineer
      - qa_engineer

  workflow_automation:
    primary_expert: workflow_architect
    supporting_experts:
      - integration_engineer
      - business_analyst
      - qa_engineer

  product_plan:
    primary_expert: product_manager
    supporting_experts:
      - ux_designer
      - business_analyst
      - qa_engineer

  document_or_content:
    primary_expert: technical_writer
    supporting_experts:
      - domain_expert
      - editor

  data_analysis:
    primary_expert: data_analyst
    supporting_experts:
      - data_engineer
      - qa_engineer
```

Create a custom expert when no listed profile fits. Name the expert by role, not by artifact type.

## Expert Focus

```yaml
frontend_game_engineer:
  focuses:
    - browser runtime behavior
    - rendering loop
    - input handling
    - state management
    - single-file or build constraints

game_designer:
  focuses:
    - core loop
    - controls
    - difficulty
    - win and lose conditions
    - feedback and game feel

ux_designer:
  focuses:
    - visible state
    - ease of use
    - layout clarity
    - accessibility basics

qa_engineer:
  focuses:
    - testability
    - edge cases
    - regression risks
    - pass and fail conditions

backend_architect:
  focuses:
    - service boundaries
    - data model
    - interfaces
    - reliability
    - maintainability

product_manager:
  focuses:
    - user goals
    - scope
    - priority
    - success metrics

technical_writer:
  focuses:
    - audience fit
    - document structure
    - clarity
    - completeness
```

## Acceptance Criteria Schema

```yaml
ExpertAcceptanceCriteria:
  expert_role: string
  criteria:
    - id: string
      category: string
      criterion: string
      why_it_matters: string
      verification_method: string
      pass_condition: string
      fail_examples: string[]
      priority: must | should | nice
      source_trace: string
```

## Rules

- Make every criterion verifiable.
- Include a concrete pass condition.
- Include fail examples when they clarify the boundary.
- Convert subjective quality into observable checks.
- Put unconfirmed or optional requirements under `should` or `nice`, not `must`.
- Tie criteria to Stage2 facts, accepted defaults, or expert recommendations.
- Keep expert recommendations separate from confirmed user requirements.
- Use criteria for implementation self-check and final concise reporting.
- Do not display full expert criteria unless the user asks to inspect the internal package or validation rubric.

## Bad Criteria

```yaml
- criterion: The UI should look good.
- criterion: The feature should be complete.
- criterion: The system should be robust.
```

## Better Criteria

```yaml
- criterion: The page shows current score, high score, selected difficulty, and start/pause/restart controls without requiring the user to read external instructions.
  verification_method: Open the page in a browser and inspect visible controls before starting the game.
  pass_condition: All listed controls and status values are visible in the first viewport.
```


path: references/stage1-universal-process-model.md
content: # Stage1 Universal Process Model

Use Stage1 to convert the user's raw request into a rich process model. The model must preserve enough structure for later clarification and downstream agent execution.

## Principles

- Model the request as a process, not just a summary.
- Prefer a graph of nodes and edges over a linear list.
- Capture inputs, outputs, actors, systems, rules, exceptions, and uncertainty.
- Do not collapse important workflow details for brevity.
- Mark inferred defaults as assumptions unless the user confirms them.

## Schema

```yaml
UniversalProcessModel:
  request_summary: string
  business_goal:
    primary_goal: string
    success_outcome: string
  scope:
    included: string[]
    excluded_or_unknown: string[]
  actors:
    - id: string
      name: string
      role: string
  external_systems:
    - id: string
      name: string
      purpose: string
      known_or_assumed: confirmed | assumed | unknown
  data_objects:
    - name: string
      description: string
      fields: string[]
      lifecycle: string
  inputs:
    - name: string
      source: string
      type: string
      required: true | false
      notes: string
  outputs:
    - name: string
      consumer: string
      type: string
      success_condition: string
  workflow_graph:
    nodes:
      - node_id: string
        title: string
        description: string
        node_type: input_collect | transform | classify | decide | human_review | external_api | database_operation | notification | output_generate | end | custom
        actor: string
        system: string
        trigger: string
        preconditions: string[]
        required_inputs: string[]
        actions: string[]
        produced_outputs: string[]
        business_rules: string[]
        validation_rules: string[]
        failure_modes: string[]
        retry_or_fallback: string[]
        unresolved_points: string[]
    edges:
      - from_node: string
        to_node: string
        condition: string
        edge_type: normal | conditional | exception | rejection | retry | custom
  business_rules: string[]
  human_touchpoints: string[]
  exceptions: string[]
  assumptions: string[]
  open_questions:
    - question: string
      target_field: string
      reason: string
      blocking_level: blocking | important | optional
  confidence: number
  source_evidence:
    - item: string
      source: user_text | model_inference | prior_context
      quote_or_reason: string
```

## Modeling Guidance

For implementation requests, include likely implementation flow without choosing unconfirmed technology unless obvious from user context.

For document-writing requests, model the content production workflow: audience, message, source material, sections, review, and final output.

For games, model the game loop, player input, state updates, rules, rendering, end conditions, and restart flow.

For business processes, model actors, approvals, systems, data movement, decisions, exceptions, and final outputs.

## Stage1 Quality Bar

Stage1 is acceptable when another agent can answer:

- What is the user trying to accomplish?
- What is in scope and uncertain?
- What are the main process nodes and transitions?
- What information is confirmed versus inferred?
- Which missing details should Stage2 ask about?


path: references/stage2-clarification-handoff.md
content: # Stage2 Clarification Handoff

Use Stage2 to ask targeted questions, absorb answers, recommend defaults when requested, and create a stable handoff for Stage3.

## Clarification Strategy

- Ask only questions that materially affect downstream work.
- Group related questions when it reduces user effort.
- Prefer 3-5 questions at a time for ambiguous requests.
- When the user asks for recommendations, choose defaults and explain briefly.
- Move non-blocking unknowns into `unresolved_questions.non_blocking`.

## Question Schema

```yaml
ClarificationQuestion:
  question_id: string
  target_field: string
  question: string
  reason: string
  blocking_level: blocking | important | optional
  suggested_options: string[]
  default_if_unanswered: string
```

## Handoff Schema

```yaml
UniversalRequirementHandoff:
  confirmed_facts: string[]
  confirmed_process_model: UniversalProcessModel
  clarified_scope:
    in_scope: string[]
    out_of_scope: string[]
    non_goals: string[]
  requirement_summary: string
  functional_requirements: string[]
  non_functional_requirements: string[]
  interaction_requirements: string[]
  data_requirements: string[]
  workflow_requirements: string[]
  business_rules: string[]
  accepted_defaults:
    - field: string
      value: string
      reason: string
  unresolved_questions:
    blocking:
      - question: string
        impact: string
    non_blocking:
      - question: string
        default_handling: string
  assumptions:
    accepted: string[]
    model_inferred: string[]
  risk_points: string[]
  rui: number
  ready_for_stage3: true | false
  traceability:
    - item: string
      source: user_answer | accepted_default | stage1_model | model_inference
      confidence: number
```

## Readiness Rules

Set `ready_for_stage3: true` only when:

- every blocking question has an answer or accepted default,
- the scope is explicit enough for downstream work,
- the expected outcome is clear,
- known assumptions are separated from confirmed facts.

Use `rui` as a rough residual uncertainty index:

- `0.0-0.2`: ready; only minor unknowns remain.
- `0.2-0.4`: probably ready if defaults are accepted.
- `0.4+`: ask more questions before Stage3.

## Default Recommendation Rules

When recommending defaults:

- choose the lowest-friction option for simple tasks,
- choose maintainable, conventional architecture for implementation tasks,
- avoid adding external dependencies unless they clearly improve the result,
- do not add unrequested premium features,
- mark every recommendation under `accepted_defaults` after user acceptance.


path: references/stage3-agent-task-guidance-package.md
content: # Stage3 Agent Task Guidance Package

Stage3 turns the Stage2 handoff into an internal package for downstream execution. Do not display the full package by default. Use it to continue the user's task immediately unless the user asks to inspect, export, save, or review the package.

## Internal Flow

```text
Stage3A TaskClassifier
Stage3B ExpertSelector
Stage3C ExpertTaskBriefGenerator
Stage3D ExpertAcceptanceCriteriaGenerator
Stage3E Stage3MainComposer
Stage3F ExecuteWithPackage
Stage3G ConciseResultAndSelfCheck
```

## Execution Policy

Continue execution after Stage3 when:

- blocking questions are resolved or have accepted defaults,
- the user asked for a concrete deliverable or outcome,
- the task can be completed with available tools and workspace access.

Pause before execution when:

- unresolved blocking questions remain,
- execution would unexpectedly modify many files or external systems,
- credentials, paid services, network access, or destructive operations are required,
- the user explicitly asked only for analysis, planning, or the internal package.

## Task Classification

```yaml
TaskClassification:
  work_mode: implement | write_doc | design | analyze | test | research | plan | refactor | custom
  domain:
    - frontend_web
    - backend_api
    - game
    - workflow_automation
    - data_analysis
    - product_design
    - business_process
    - prompt_engineering
    - document_writing
    - custom
  downstream_agent_role: coding_agent | writing_agent | research_agent | product_agent | design_agent | testing_agent | general_agent
  risk_level: low | medium | high
  rationale: string
```

## Expert Task Brief

```yaml
ExpertTaskBrief:
  expert_role: string
  focus: string[]
  task_guidance: string[]
  recommended_approach: string[]
  suggested_steps: string[]
  constraints: string[]
  risks: string[]
  edge_cases: string[]
  do: string[]
  do_not: string[]
```

## Internal Package Schema

This schema is for internal reasoning and downstream execution. Do not render it to the user by default.

```yaml
AgentTaskGuidancePackage:
  package_id: string
  title: string
  objective: string
  expected_outcome: string
  downstream_agent_role: string
  recommended_work_mode: string

  context:
    user_original_request: string
    clarified_requirement_summary: string
    background: string
    target_users: string[]
    operating_environment: string

  confirmed_scope:
    in_scope: string[]
    out_of_scope: string[]
    non_goals: string[]

  requirements:
    functional_requirements: string[]
    non_functional_requirements: string[]
    interaction_requirements: string[]
    data_requirements: string[]
    workflow_requirements: string[]
    business_rules: string[]

  process_model:
    actors: object[]
    systems: object[]
    inputs: object[]
    outputs: object[]
    workflow_graph: object

  expert_task_guidance:
    primary_expert:
      role: string
      guidance: string[]
      recommended_approach: string[]
      suggested_steps: string[]
      constraints: string[]
      risks: string[]
      edge_cases: string[]
    supporting_experts:
      - role: string
        guidance: string[]
        recommended_approach: string[]
        suggested_steps: string[]
        constraints: string[]
        risks: string[]
        edge_cases: string[]

  consolidated_execution_plan:
    recommended_approach: string[]
    suggested_steps: string[]
    dependencies_or_tools: string[]
    files_or_artifacts_to_create: string[]
    integration_points: string[]
    constraints: string[]
    do: string[]
    do_not: string[]
    ask_before_changing: string[]
    autonomy_level: execute_directly | ask_before_major_tradeoffs | plan_first | docs_only

  expert_acceptance_criteria:
    - expert_role: string
      criteria: object[]

  consolidated_acceptance_criteria:
    must_pass: object[]
    should_pass: object[]
    nice_to_have: object[]

  risks_and_edge_cases:
    risks: string[]
    edge_cases: string[]
    fallback_strategy: string[]

  unresolved_questions:
    blocking: string[]
    non_blocking: string[]

  assumptions:
    accepted_defaults: object[]
    model_inferred_assumptions: string[]
    expert_recommendations: string[]

  conflicts:
    - description: string
      affected_fields: string[]
      suggested_resolution: string

  traceability:
    - item: string
      source: string
      confidence: number

  suggested_next_prompt: string
```

## Composer Rules

- Consolidate expert content into a clear execution plan.
- Preserve expert-specific details under `expert_task_guidance`.
- Do not invent new user requirements while composing.
- Move new professional advice into `expert_recommendations`.
- Keep the final package directly usable as a prompt to another agent.
- Use the package to execute the task immediately when the execution policy allows it.
- Use `suggested_next_prompt` internally as the execution instruction; do not display it unless the user asks for the internal package.

## User-Visible Reporting

After execution, report:

- completed result,
- important decisions/defaults used,
- files or artifacts created/changed,
- concise self-check against must-pass criteria,
- caveats, skipped checks, or non-blocking questions.

Do not dump the full package, full workflow graph, or full expert criteria unless requested.


path: agents/openai.yaml
content: interface:
  display_name: "Clear Task"
  short_description: "Clarify, confirm, then execute with guidance."
  default_prompt: "Use $clear-task to clarify this idea, ask me to confirm the requirements, then build an internal expert-guided task package and execute after approval."


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)