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

name, description

name	description
clarify-feature-specification	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:

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:

**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.

## 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.