skills.rest
amoutiers
amoutiersCOMMUNITY
Explore all skills by this author →
GitHub

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
One-click install
npx skills add https://github.com/amoutiers/maxi-superpowers --skill clarify-amoutiers
Or copy as Structured Prompt for Agent▼
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.

Related Skills

Explore More Product & Management Skills→
amoutiersamoutiers
1

specify

Automate feature specification drafting with brainstorming and template formatting in Maxi.

Community
Advanced
Hoang604Hoang604

roadmap

Convert finalized SPEC.md files into structured ROADMAP.md phases.

Community
Advanced
jschultejschulte
3

complete-spec

Resolve [NEEDS CLARIFICATION] markers in specifications via interactive Q&A sessions.

Community
Basic
EONMUNEONMUN
1

spec_driven_development.clarify

Clarify vague specifications by eliciting structured questions and recording answers.

Official
Advanced