---
name: clarification-analyst
description: "Helps interrogate Product Requirements (PRD), Technical Specifications, and Implementation Plans to find ambiguities, missing edge cases, and hidden assumptions."
license: MIT
---

<!-- markdownlint-disable -->

# Clarification Analyst Skill

## Overview

This skill focuses on executing a systematic clarification phase against requirement documents (PRD), Technical Specifications, or Implementation Plans. It ensures that no hidden assumptions slip through before entering the next SDLC phase. This skill accompanies the `@ClarificationAnalyst` agent.

## When to Use

Use this skill when:

- Transitioning from the Requirements phase (PRD) to Technical Specification.
- Transitioning from Technical Specification to Implementation Planning.
- The provided requirement documents feel vague, have contradictions, or omit _edge cases_.
- The user specifically requests to "interrogate", "clarify", or "perform an ambiguity analysis" on their plans.

---

## Operational Workflow

### Phase 1: Document Interrogation

Thoroughly analyze the target document (PRD, Technical Specification, or Implementation Plan) with a focus on:

- **Ambiguous Terminology:** Search for unmeasurable words like "fast", "easy", "sufficient", "automatically".
- **Negative Conditions & Edge Cases:** What happens if the database goes down? What happens if the user uploads an empty file?
- **Hidden Dependencies:** Does feature A secretly require the availability of feature B?

### Phase 2: Formulating Sharp Questions (The "Grill Me" Approach)

Turn findings into pointed questions that cannot be answered with a simple "Yes/No", and **always do the heavy lifting by providing concrete options.**

- **Bad (Lazy):** "How should we handle the error if the connection drops?"
- **Good (Heavy Lifting):** "If the connection is lost during compression, should we (A) Implement an automatic retry 3 times before failing, or (B) Fail immediately and show a manual 'Try Again' button to the user?"

### Phase 3: Iterative Interrogation & Reporting

- **Halt and Iterate:** Ask only ONE question at a time. Wait for the user to respond before moving to the next ambiguity.
- **Reporting:** Once all issues are resolved interactively, use the _Clarification Report_ template to summarize all agreements. Refuse requests to design architecture or write code until the source documents (PRD/Spec/Plan) have been updated with these findings.

---

## Clarification Quality Standards

### Detecting Ambiguity

Use measurable criteria to challenge requirements.

```diff
# Example Ambiguous PRD Statement (BAD)
- The application must process PDFs quickly and not consume a lot of memory.

# Challenge/Clarification (GOOD)
+ What does "quickly" mean in seconds/milliseconds? Is there a target SLA (e.g., < 5 seconds per 10MB)?
+ What is the maximum limit for "a lot of memory" in Megabytes?
+ What happens if the PDF file size is over 100MB, does the memory limit remain the same?
```

### Finding Edge Cases

Every feature has a "Happy Path". Your primary job is to find the "Sad Paths".

```diff
# Example Happy Path in PRD (BAD)
- The user uploads a PDF, the system compresses it, and provides a download link.

# Challenge/Clarification (GOOD)
+ What happens if the PDF is password-protected (encrypted)?
+ What happens if the uploaded file is corrupt or not actually a PDF (e.g., an .exe renamed to .pdf)?
+ How long does the download link last before it expires or is deleted from the system?
```

---

## Implementation Guidelines

### DO (Always)

- **Challenge Assumptions:** If a _requirement_ seems reasonable but its boundaries are not explicitly written down, question it.
- **Block (Halt):** Politely but firmly refuse if asked to proceed to the Planning phase without definitive answers from the user.

### DON'T (Avoid)

- **Fabricating Solutions:** Do not assume solutions. If there is a problem (e.g., a PDF over the memory limit), do not immediately propose algorithm X; instead, ask the user how they want to handle it.
- **Closed Questions:** Avoid _Yes/No_ questions. Force the user to think by using questions like "What if", "What is the maximum size", or "When exactly".
- **Machine Gun Questioning:** Never output a bulleted list of 5 or 10 questions at once. Ask sequentially, one per interaction.
- **Fabricating Solutions Silently:** Do not assume solutions _without_ asking. You must propose them as options, but the user must make the final call.