Clarify First (Agent Skill)

Core Purpose

Triggers

• Ambiguity: Unclear success criteria ("optimize it", "fix it"), vague scope, or undefined deliverables.
• High Risk / Irreversible: Destructive ops (delete, overwrite), infrastructure changes, deployment, spending money, or touching production data.
• Conflicts: Contradictory instructions ("refactor everything" + "no breaking changes") or unfeasible constraints.
• Missing Context: No target environment, no specified language/framework, or missing specific file paths when they matter.

• Low Risk: Read-only operations, formatting, adding comments, or strictly local/reversible changes.
• Precise Requests: "Add a unit test for

  utils.ts

  covering the

  sum

  function" (Clear scope & criteria).

Internal Process

1. Assess Risk: Is this Low, Medium, or High risk? (See Rubric).
2. Identify Gaps: What specific information is missing to guarantee a "correct" result?
3. Formulate Strategy: Do I need to stop and ask (Medium/High) or can I state assumptions and proceed (Low)?

Workflow

Step 1: Risk Triage (Rubric)

• Low: Read-only, formatting, adding tests, creating new non-conflicting files, local-only reversible changes. -> Proceed with stated assumptions.
• Medium: Refactors, API changes, dependency upgrades, performance tuning. -> Propose options, wait for "OK".
• High: Deleting data, overwriting existing files, migrations, deployment, modifying secrets/config. -> REQUIRE explicit confirmation.
  • Note: Creating a file that may overwrite an existing path counts as HIGH unless the tool guarantees no-overwrite.

Step 2: Alignment Snapshot

• Example: "I understand you want a login page. I am NOT assuming which auth provider (Auth0 vs Firebase) or UI library to use."

Step 3: Propose Options (The "Consultant" Approach)

• Option A (Recommended): The standard/safest path.
• Option B: The quick/hacky path.
• Option C: The comprehensive/complex path.

Multi-Turn Protocol

• Partial Answers: If the user answers Q1 but misses Q2: Do NOT re-ask Q1. State understanding of Answer 1. Re-ask Q2 only if blocking.
• Stop Heuristic: Max 2 rounds of clarification. If ambiguity remains for non-critical items, state standard assumption and ACT.
• Action Bias: Do NOT ask a 3rd round.

Tone & Style

• Professional & Protective: Be concise. Don't be "chatty".
• Structured: Use the template below. Avoid wall-of-text paragraphs.
• Multilingual: Match the user's language. Look for corresponding phrasing guides in

  references/

  (e.g.,

  references/zh-CN.md

  ).

Anti-Patterns (What NOT to do)

• Don't be "Lazy": Don't ask "How should I do this?" without proposing options.
• Don't ask Trivialities: Don't pause for low-risk, obvious steps.
• No apology: State you are "aligning for safety/quality", do not apologize.
• "Just Do It" Handling:
  • Low/Medium Risk: Proceed immediately with Option A.
  • High Risk: One Final Check. State: "This is destructive/high-risk. I will execute [X]. Confirm?" If confirmed, ACT.

Success Criteria

1. All blocking questions are answered, OR
2. Max 2 rounds reached and non-critical assumptions stated, OR
3. User explicitly confirms HIGH-risk action.

Output Template

1. Risk Assessment:

   [LOW / MEDIUM / HIGH]

   - Reasoning
2. Alignment Snapshot:
   • Goal: ...
   • Constraints: ...
   • Open Assumptions: ...
3. Blocking Questions (Critical):
   • Q1: ...? (Options: A, B, C)
4. Proposed Options:
   • Option A (Recommended): ...
   • Option B: ...
5. Next Step:
   • "Please confirm Option A and answer Q1, or provide specific instructions."

Mini-Example

1. Risk: HIGH (Data modification implies risk).
2. Snapshot: You want to repair a DB issue. I don't know which DB, what the error is, or if I can run write operations.
3. Blocking:
   • Q1: Is this production or local?
   • Q2: What is the specific error/symptom?
4. Options:
   • A: Read-only investigation (Log analysis).
   • B: Attempt auto-repair (Only if local/dev).

References

• references/EXAMPLES.md

  (Concrete input/output examples)

• references/QUESTION_BANK.md

  (Blocking question toolkit)

• references/SCENARIOS.md

  (Bugs, RFCs, NFRs, High-Risk Ops)

• references/NFR.md

  (Non-functional requirements)

• references/zh-CN.md

  (Chinese phrasing templates)