agent-skills/skills/clarify-feature-specification/SKILL.md

---
name: clarify-feature-specification
description: Use when an existing feature specification is materially ambiguous or incomplete and its highest-impact decisions must be resolved before technical planning without expanding scope.
---

# Clarify a Feature Specification

Clarification tightens an existing intent artifact. It does not create a new feature, choose an implementation, or turn optional ideas into scope.

## 1. Establish the authority and boundary

Read the entire current specification plus any project principles it claims to follow. If no specification exists, stop and request one; do not silently author a replacement.

Record the current in-scope and out-of-scope statements. Treat them as a fence. A proposed answer that adds a new actor, journey, business outcome, or integration is a scope change and requires explicit approval outside this workflow.

## 2. Build an ambiguity map

Mark each category `Clear`, `Partial`, or `Missing`:

- functional goals, boundaries, actors, and permissions;
- entity identity, relationships, lifecycle, and scale assumptions;
- primary, alternate, empty, error, and recovery flows;
- performance, reliability, availability, and observability outcomes;
- security, privacy, retention, and compliance obligations;
- external dependencies, formats, compatibility, and failure modes;
- conflicts, concurrency, throttling, and negative scenarios;
- terminology and canonical names;
- acceptance scenarios and measurable completion signals;
- placeholders and vague adjectives.

Create a candidate question only if its answer would materially alter architecture, data modeling, task decomposition, test design, user-visible behavior, operational readiness, or compliance validation. Exclude stylistic preferences, already answered points, and choices properly owned by the technical plan.

## 3. Prioritize a small batch

Score each candidate using:

```text
priority = impact × uncertainty × irreversibility
```

Use High/Medium/Low values rather than fake numeric precision. Prefer one scope or security question over several polish questions. Cap a clarification session at five accepted questions; use three when that resolves the material uncertainty.

Questions must be answerable as either:

- 2–5 mutually exclusive choices with consequences; or
- a short phrase explicitly limited to five words.

Ask one question at a time so later questions can be dropped or rewritten after each decision. Do not expose the whole internal queue.

## 4. Ask answerable questions

Use this form:

```markdown
**Question:** Who may approve a refund above the ordinary limit?

This determines the permission boundary and the acceptance scenarios for high-value refunds.

**Recommended:** Option B — requiring a second approver limits unilateral high-value changes while preserving a defined path.

| Option | Answer | Consequence |
|--------|--------|-------------|
| A | Any refund operator | Simplest flow; broadest authority |
| B | Two refund operators | Adds dual control and an intermediate state |
| C | Finance administrator only | Narrowest authority; may delay completion |

Reply with A, B, C, “recommended,” or a short alternative.
```

The question must be a complete interrogative, not a topic label such as “Refund permissions.” Explain why it matters before listing options. Recommend only when the existing context supports a best default; otherwise state the trade-off neutrally.

Validate the reply. If it does not map to an option or is too vague, ask a disambiguation without counting a new question. Accept “recommended” only when a recommendation was shown.

Stop when critical ambiguity is resolved, the user says to stop, or five answers have been accepted. Report high-impact deferred questions rather than exceeding the cap.

## 5. Integrate each answer immediately

After every accepted answer:

1. add one audit bullet under `## Clarifications` and a dated session heading;
2. edit the authoritative section where the decision belongs;
3. remove or replace the now-invalid ambiguous wording;
4. save the file before asking the next question.

```markdown
## Clarifications

### Session 2026-08-15

- Q: Who may approve a refund above the ordinary limit? → A: Two refund operators.
```

Route the decision by kind:

- functional answer → functional requirement;
- actor or sequence answer → journey and acceptance scenarios;
- entity answer → entity identity, relationship, or lifecycle;
- quality answer → measurable success criterion;
- failure answer → edge case or exception scenario;
- terminology answer → normalize the canonical term throughout.

Write the smallest testable change. Do not append a clarification while leaving contradictory alternatives elsewhere. If the answer changes settled scope, pause and label it a scope amendment rather than integrating it as routine clarification.

## 6. Validate after each edit

Check:

- exactly one clarification bullet exists per accepted answer;
- the answer appears in the normative section, not only the audit log;
- the triggering placeholder or vague phrase is gone;
- no earlier statement asserts a rejected alternative;
- IDs, heading hierarchy, and unrelated ordering are preserved;
- canonical terminology is consistent;
- no new actor, journey, or requirement slipped in without being implied by the answer.

If a requirements-quality checklist exists, re-evaluate it against the edited spec. Toggle only checklist state that the clarified text actually changes; preserve all other wording and formatting.

## 7. Report the result

Report:

- number of questions accepted;
- specification path;
- sections changed;
- categories resolved, clear, deferred, and still outstanding;
- any checklist items that changed state;
- whether planning can safely begin.

If no candidate meets the materiality threshold, say that no critical ambiguity warrants formal clarification. Do not invent questions to fill a quota.