clarify

Resolve ambiguous spec items by generating clarifying questions and updating the document in place.

1|Updated May 28, 2026

Search Tags:#documentation #specification #spec #questions #clarify #fr

Ready to run

npx skills add https://github.com/amoutiers/maxi-superpowers --skill clarify-amoutiers

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: clarify
Source: https://github.com/amoutiers/maxi-superpowers/tree/main/skills/clarify
Command: npx skills add https://github.com/amoutiers/maxi-superpowers --skill clarify-amoutiers

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Resolve open questions in an existing spec without rewriting it. Appends a ## Clarifications section and updates FRs in place.

Core Features & Use Cases

Prereqs: docs/maxi/constitution.md must exist — if missing, stop: "No constitution found. Run /maxi:constitution first."
Read and scan the in-flight spec from docs/maxi/specs/ to identify [NEEDS CLARIFICATION] markers, questions in FR descriptions, vague adjectives, and missing acceptance criteria.
Build a prioritized list of ambiguities and ask one question at a time, recording each answer and how it resolves the ambiguity.
Update spec.md in place: replace [NEEDS CLARIFICATION: ...] markers, append a ## Clarifications section with Q&A pairs, and set frontmatter updated date to today, then transition status to clarified.

Quick Start

Identify the open questions in the current spec and prompt the user with a single focused clarification question.

Frequently Asked Questions about clarify

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I resolve open questions in a project specification without rewriting the entire document?▼

To resolve open questions in a project specification, you can detect [NEEDS CLARIFICATION] markers and append a Clarifications section with Q&A pairs. This updates functional requirements in place while preserving the original document structure.

What are the prerequisites for clarifying an in-flight spec?▼

Clarifying an in-flight spec requires a docs/maxi/constitution.md file and the target spec located under docs/maxi/specs/. The target spec must have its status set to specified, otherwise the clarification workflow will halt.

How does the specification clarification process handle vague requirements and missing acceptance criteria?▼

The specification clarification process scans for vague adjectives and missing acceptance criteria, then builds a prioritized list of ambiguities. It prompts you with one focused question at a time, recording each answer to resolve the specific ambiguity.

What changes are made to the spec.md file after answering clarification questions?▼

After answering clarification questions, the spec.md file is updated in place by replacing [NEEDS CLARIFICATION] markers, appending a Clarifications section, updating the frontmatter date, and transitioning the status to clarified.

What happens if the docs/maxi/constitution.md file is missing when clarifying specs?▼

If the docs/maxi/constitution.md file is missing, the specification clarification process stops immediately and displays an error directing you to run the constitution setup first before proceeding.