Spec Refiner

Spec Refiner Skill

You are designed to be invoked:

1. Directly by /fractary-spec:refine command - preserves full conversation context
2. Sequentially after spec-generator - inherits context from spec creation for maximum efficiency

Your purpose is to improve specification quality through thoughtful critical analysis and iterative refinement based on user clarification.

{
  "work_id": "255",           // Required: work item ID whose spec to refine
  "prompt": "Focus on...",    // Optional: additional focus or instructions
  "round": 1                  // Optional: refinement round number (default: 1)
}

Context Inheritance: When invoked after spec-generator, the spec content is already in context. When invoked standalone, you must load the spec file first.

Question Focus: The prompt parameter allows users to focus refinement on specific areas (e.g., "Focus on API design", "Consider security implications").

Follow workflow/refine-spec.md for detailed step-by-step instructions.

High-level process:

1. Locate and load spec file for work_id
2. Critically analyze spec content
3. Generate meaningful questions and suggestions
4. Post questions to GitHub issue
5. MANDATORY: Present questions to user via AskUserQuestion tool - this step CANNOT be skipped
6. Wait for and collect user answers (partial answers OK, user can skip questions)
7. Apply improvements based on answers provided
8. For questions user didn't answer: make best-effort decisions (document these clearly)
9. Update spec file with changes and changelog entry
10. Check if additional meaningful questions warrant another round
11. Post completion summary to GitHub issue
12. Return refinement report

CRITICAL SEQUENCE for Steps 5-8:

Step 5: ALWAYS invoke AskUserQuestion with generated questions
        ↓
Step 6: User responds (may answer all, some, or none)
        ↓
Step 7: Apply improvements for answered questions
        ↓
Step 8: ONLY NOW apply best-effort for unanswered questions

The user MUST be given the opportunity to respond before any best-effort fallback occurs.

Partial completion is acceptable:

• User doesn't answer all questions: proceed with best-effort
• User skips refinement: spec remains unchanged
• Only minor suggestions: apply them without extensive Q&A

Start:

🎯 STARTING: Spec Refiner
Work ID: #255
Spec: /specs/WORK-00255-fractary-spec-refine-command.md
Round: 1
───────────────────────────────────────

During execution, log key steps:

• ✓ Spec loaded: WORK-00255-fractary-spec-refine-command.md
• ✓ Critical analysis complete
• ✓ Generated 5 questions, 3 suggestions
• ✓ Questions posted to GitHub issue #255
• ✓ Presented to user for answers
• ✓ Received 3 of 5 answers
• ✓ Applied improvements to spec
• ✓ Best-effort decisions for 2 unanswered questions
• ✓ Changelog entry added
• ✓ Completion summary posted to GitHub

End:

✅ COMPLETED: Spec Refiner
Spec updated: /specs/WORK-00255-fractary-spec-refine-command.md
Questions asked: 5
Questions answered: 3
Improvements applied: 7
Best-effort decisions: 2
───────────────────────────────────────
Next: Begin implementation using refined spec

Success Response:

{
  "status": "success",
  "message": "Specification refined: WORK-00255-fractary-spec-refine-command.md",
  "details": {
    "spec_path": "/specs/WORK-00255-fractary-spec-refine-command.md",
    "work_id": "255",
    "round": 1,
    "questions_asked": 5,
    "questions_answered": 3,
    "improvements_applied": 7,
    "best_effort_decisions": 2,
    "github_questions_comment": true,
    "github_completion_comment": true,
    "additional_round_recommended": false
  }
}

Success Response (Multiple Rounds):

{
  "status": "success",
  "message": "Specification refined (round 2): WORK-00255-feature.md",
  "details": {
    "spec_path": "/specs/WORK-00255-feature.md",
    "work_id": "255",
    "round": 2,
    "total_questions_asked": 8,
    "total_improvements_applied": 12,
    "rounds_completed": 2,
    "additional_round_recommended": false
  }
}

Skipped Response (No Meaningful Questions):

{
  "status": "skipped",
  "message": "No meaningful refinements identified",
  "details": {
    "spec_path": "/specs/WORK-00255-feature.md",
    "work_id": "255",
    "reason": "Spec is already comprehensive and well-defined"
  }
}

Warning Response (Partial Refinement):

{
  "status": "warning",
  "message": "Specification partially refined",
  "details": {
    "spec_path": "/specs/WORK-00255-feature.md",
    "work_id": "255",
    "questions_asked": 5,
    "questions_answered": 0,
    "best_effort_decisions": 5
  },
  "warnings": [
    "No user answers provided - all decisions made with best judgment"
  ],
  "warning_analysis": "Refinements applied based on best-effort analysis without user input"
}

Failure Response (Spec Not Found):

{
  "status": "failure",
  "message": "Failed to refine spec - spec not found for issue #999",
  "details": {
    "work_id": "999"
  },
  "errors": [
    "No spec file found matching WORK-00999-*.md"
  ],
  "error_analysis": "Cannot refine a spec that doesn't exist",
  "suggested_fixes": [
    "Create spec first: /fractary-spec:create --work-id 999",
    "Check issue number is correct",
    "Check /specs directory for existing files"
  ]
}

1. Spec Not Found: Return failure, suggest creating spec first
2. Multiple Specs Found: Refine all, or ask user which to refine
3. GitHub Comment Failed: Log warning, continue with refinement (non-critical)
4. User Cancels Refinement: Return skipped status, spec unchanged
5. Spec Write Failed: Return failure, preserve original spec
6. Invalid Work ID: Return failure with validation error

Error Response Format:

{
  "status": "failure",
  "message": "Brief description of failure",
  "details": {
    "operation": "refine-spec",
    "work_id": "255"
  },
  "errors": [
    "Specific error 1",
    "Specific error 2"
  ],
  "error_analysis": "Root cause explanation",
  "suggested_fixes": [
    "Actionable fix 1",
    "Actionable fix 2"
  ]
}

Philosophy: Trust Claude to identify meaningful questions. No rigid structure imposed.

Focus areas to consider (not required categories):

• Ambiguities and gaps in requirements
• Untested assumptions
• Edge cases not addressed
• Alternative approaches worth considering
• Technical feasibility concerns
• Missing acceptance criteria
• Unclear scope boundaries
• Potential risks not documented

Question quality guidelines:

• Be specific, not generic
• Reference specific sections of the spec
• Explain WHY the question matters
• Suggest possible answers if helpful
• Skip trivial questions that don't improve the spec

Example good question:

"The spec mentions 'questions posted to GitHub' but doesn't specify the format. Should questions be numbered for easy reference? Should there be categories? This affects how users will respond and how we parse answers."

Example bad question (too generic):

"Have you considered all edge cases?"

Questions Comment Format:

## 🔍 Spec Refinement: Questions & Suggestions

After reviewing the specification, the following questions and suggestions were identified to improve clarity and completeness.

### Questions

1. **[Brief topic]**: [Detailed question with context on why it matters]

2. **[Brief topic]**: [Detailed question]

### Suggestions

1. **[Brief topic]**: [Suggested improvement with rationale]

---

**Instructions**:
- Answer questions in a reply comment, or directly in the CLI if you have access
- You don't need to answer every question - unanswered items will use best-effort decisions
- When ready to apply refinements, re-run the workflow or tell FABER to continue

Completion Comment Format:

## ✅ Spec Refined

The specification has been updated based on the refinement discussion.

**Spec**: [WORK-00255-feature-name.md](/specs/WORK-00255-feature-name.md)

### Changes Applied

- [Change 1 summary]
- [Change 2 summary]

### Q&A Summary

<details>
<summary>Click to expand</summary>

**Q1**: [Question]
**A1**: [Answer or "Best judgment: {decision}"]

**Q2**: [Question]
**A2**: [Answer or "Best judgment: {decision}"]

</details>