/clarify-issue

Clarify ambiguities in GitHub issue: $ARGUMENTS

Argument Validation

• Ensure an issue URL or number was provided and prompt the user if not.
• Extract the issue number from the URL if a full URL was provided.

Context Gathering

Fetch the issue details using gh:

gh issue view "$ISSUE_NUMBER" --json number,title,body,url,labels,state

Parse the issue title and body to understand the current specification.

Ambiguity Detection

Analyze the issue against these nine categories to identify gaps:

1. Functional Scope & Behavior

   • What specific capabilities must be delivered?
   • What's explicitly out of scope?
   • How should the feature behave in normal conditions?

2. Domain & Data Model

   • What entities, attributes, and relationships are involved?
   • What validation rules apply?
   • Are there existing data structures to extend or new ones to create?

3. Interaction & UX Flow

   • What's the user journey or workflow?
   • What inputs are required and what outputs are produced?
   • How should errors or feedback be communicated to users?

4. Non-Functional Quality Attributes

   • What are the performance, security, or accessibility requirements?
   • What scale or load must be supported?
   • Are there compliance or regulatory constraints?

5. Integration & External Dependencies

   • What APIs, services, or systems must integrate?
   • What data formats or protocols are required?
   • Are there authentication or authorization requirements?

6. Edge Cases & Failure Handling

   • What happens with invalid, missing, or malformed input?
   • How should timeouts, network failures, or unavailable services be handled?
   • What error states need graceful degradation?

7. Constraints & Tradeoffs

   • What technical or business constraints exist?
   • What tradeoffs between speed, quality, scope are acceptable?
   • What's the priority if resources are limited?

8. Terminology & Consistency

   • Are terms used consistently throughout the spec?
   • Do any terms need clear definitions?
   • Are there naming conventions to follow?

9. Completion Signals

   • What defines "done" for this feature?
   • What testing is required?
   • What documentation must be updated?

For each category, assign a status:

• Clear: Well-defined and actionable
• Partial: Some information present but gaps remain
• Missing: No information or critically incomplete

Question Generation

Generate up to 5 targeted clarification questions that:

• Address the highest-impact ambiguities (Partial or Missing categories)
• Materially affect architecture, data modeling, testing, UX, operations, or compliance
• Exclude trivial stylistic preferences
• Can be answered with either:
  • Multiple-choice (2-4 options with clear descriptions)
  • Short-phrase responses

For each question:

• Clearly state what's ambiguous and why it matters
• If multiple-choice, identify and explain the recommended option
• Ensure answers will directly inform implementation decisions

Interactive Clarification

Use the AskUserQuestion tool to present clarifications:

1. Present questions one at a time (or in small batches if related)
2. For multiple-choice questions:
   • Set the recommended option based on best practices or issue context
   • Provide clear descriptions for each option explaining tradeoffs
   • Use multiSelect: false for mutually exclusive choices
3. For open-ended questions:
   • Provide example options with an "Other" choice
   • Keep option descriptions concise but informative

Example AskUserQuestion usage:

{
  "questions": [
    {
      "question": "What should happen when a user tries to perform this action without authentication?",
      "header": "Auth handling",
      "multiSelect": false,
      "options": [
        {
          "label": "Redirect to login",
          "description": "Send user to login page with return URL. Standard web app pattern."
        },
        {
          "label": "Show 401 error",
          "description": "Return 401 status. Better for API endpoints."
        },
        {
          "label": "Graceful degradation",
          "description": "Show limited functionality without auth. Good for public features."
        }
      ]
    }
  ]
}

Answer Integration

After receiving answers from the user:

1. Create clarifications file (if it doesn't exist):

   • Write to /tmp/claude/issue-$ISSUE_NUMBER-clarifications.md
   • Format with:

     # Clarifications for Issue #$ISSUE_NUMBER
     
     ## Date: YYYY-MM-DD
     
     ### [Category Name]
     
     **Q:** [Question text]
     **A:** [User's answer with reasoning if applicable]
     
     ---
     

2. Update existing clarifications (if file exists):

   • Use Read tool to load existing content
   • Use Edit tool to append new Q&A under today's date
   • Ensure no duplicate questions

3. Update the GitHub issue:

   • Write updated issue body to /tmp/claude/issue-$ISSUE_NUMBER-body.md
   • Add or update a ## Clarifications section at the end
   • Include date-stamped Q&A entries
   • Use Read tool to verify content
   • Update issue: gh issue edit $ISSUE_NUMBER --body-file /tmp/claude/issue-$ISSUE_NUMBER-body.md

4. Validate:

   • Check for contradictions with previous answers
   • Ensure terminology consistency
   • Verify formatting is preserved

Session Management

• Maximum 10 questions per session (stop earlier if all critical gaps addressed)
• Allow user to signal completion with "done", "stop", or "skip"
• If quota exhausted, report any remaining high-impact items

Completion Report

After clarification session ends, provide:

## Clarification Summary

**Questions asked:** X
**Questions answered:** Y
**Issue updated:** #$ISSUE_NUMBER

**Coverage by Category:**
| Category | Status | Notes |
|----------|--------|-------|
| Functional Scope | Clear/Partial/Missing | ... |
| Domain Model | Clear/Partial/Missing | ... |
| ... | ... | ... |

**Next Steps:**
- [Suggested action based on coverage]
- [Any remaining ambiguities to address]
- [Ready to proceed with implementation? Yes/No]

Important Rules

• NEVER ask trivial or stylistic questions that don't affect implementation
• NEVER speculate about tech stack unless blocking functional clarity
• ALWAYS respect "done"/"stop" signals
• ALWAYS update the issue incrementally after each answer to prevent data loss
• ALWAYS provide reasoning for recommended options in multiple-choice questions
• Keep questions focused and actionable
• Prioritize questions by implementation impact

Workflow Summary

1. Fetch issue with gh issue view → extract title and body
2. Analyze against 9-category taxonomy → identify ambiguities
3. Generate up to 5 high-impact clarification questions
4. Use AskUserQuestion tool → collect structured responses
5. Write clarifications to temp file → update issue with gh issue edit --body-file
6. Validate for consistency and contradictions
7. Provide coverage summary and next steps

Proceed with clarifying the issue following these guidelines.