Afc:clarify

/afc:clarify — Resolve Spec Ambiguities

> Identifies ambiguous or incomplete areas in spec.md and resolves them through user questions. > Answers are applied as inline updates to spec.md.

Arguments

• $ARGUMENTS — (optional) focus on a specific area (e.g., "security", "performance", "UI flow")

Project Config (auto-loaded)

!cat .claude/afc.config.md 2>/dev/null || echo "[CONFIG NOT FOUND] .claude/afc.config.md not found. Run /afc:init first — abort if missing."

Execution Steps

1. Load Spec

1. Read .claude/afc/specs/{feature}/spec.md — stop if not found
2. If a [NEEDS CLARIFICATION] section exists, process it first
3. Quickly check existing codebase for related patterns

2. Scan for Ambiguities

Scan across 10 categories:

| # | Category | What to find | |---|----------|-------------| | 0 | Necessity | Is this feature truly needed? Does it already exist? Is the cost justified by the benefit? | | 1 | Feature scope | Features with unclear boundaries | | 2 | Domain/data | Incomplete entity relationships or field definitions | | 3 | UX flow | Missing user journey steps | | 4 | Non-functional quality | Performance/security requirements without numeric targets | | 5 | External dependencies | APIs or libraries needing clarification | | 6 | Edge cases | Undefined boundary conditions | | 7 | Constraints/tradeoffs | Mutually incompatible requirements | | 8 | Terminology consistency | Same concept with different names | | 9 | Completion criteria | Success criteria that cannot be measured | | 10 | Residual placeholders | TODO/TBD/??? |

These categories serve as a comprehensive checklist, not a rigid classification. Adapt to the project's domain — skip categories irrelevant to the project type (e.g., skip 'UX flow' for CLI tools) and add domain-specific categories if needed (e.g., 'regulatory compliance' for healthcare/fintech projects).

3. Generate and Present Questions

• Generate questions ranked by their impact on spec quality — how much would the answer change the spec's direction or completeness? Present the most impactful questions first. The number of questions should match the actual ambiguity level: deeply ambiguous specs may need more questions, while mostly-clear specs need fewer. Do not artificially cap at a fixed number, but keep the set focused and avoid overwhelming the user (aim for the minimum needed to resolve critical ambiguities).
• Present one at a time via AskUserQuestion:
• Use multiple choice when possible (2-4 options)
• Include the meaning/impact of each option

4. Update Spec

After each answer:

1. Find the relevant section in spec.md and apply the inline update
2. Remove [NEEDS CLARIFICATION] tags if present
3. Add new FR-* entries if new requirements arise from the answer
4. Briefly notify the user of changes

5. Final Output

Clarification complete
├─ Questions: {processed}/{generated}
├─ spec.md updated: {changed areas}
├─ New requirements: {added FR count}
├─ Remaining [NEEDS CLARIFICATION]: {count}
└─ Next step: /afc:plan

Notes

• Question focus: Ask only what is needed to resolve critical ambiguities. Defer lower-priority questions to the plan phase rather than overwhelming the user.
• Verify after update: After updating spec.md, re-read the modified sections to confirm changes are consistent and no new [NEEDS CLARIFICATION] tags were introduced by the edit itself.
• Modify spec only: Do not touch plan.md or tasks.md.
• Avoid redundancy: Do not ask about items already clearly stated in spec.
• If $ARGUMENTS is provided: Focus the scan on that area.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jhlee0409
• Source: jhlee0409/all-for-claudecode
• License: MIT
• Homepage: https://www.npmjs.com/package/all-for-claudecode

Install and usage instructions live in the source repository linked above.