Refinement

Refinement Skill

Validate ClickUp task readiness and suggest fibonacci story point sizing. For each task, checks that required elements (description and acceptance criteria) are present, suggests a size, and recommends improvements. Read-only — reports findings but does not modify ClickUp.

Argument Handling

/refinement <clickup-task-url>

• First argument (required): A ClickUp task URL
• Extract task_id from the URL using the path segment after /t/ (e.g., https://app.clickup.com/t/86b3yxxxx or https://flybreeze.clickup.com/t/2277049/OPS-7379)
• If the URL contains a workspace ID before the custom ID (e.g., /t/2277049/OPS-7379), extract both the team_id (2277049) and task_id (OPS-7379)
• Custom task IDs (e.g., OPS-7379): When calling mcp__clickup__get_task or mcp__clickup__get_task_comments, pass team_id: "2277049" alongside the task_id. This is required for the ClickUp API to resolve custom IDs.
• If the URL is a list/view URL (contains /v/l/) rather than a task URL (contains /t/), ask the user for a specific task URL instead
• If no URL is provided, use AskUserQuestion to request it

Procedure

Step 1 — Fetch the Task

Call mcp__clickup__get_task with the extracted task_id. From the response, note:

• name, custom_id, status, assignees, description (markdown), points
• subtasks array (if any)
• parent field (if this is a subtask)
• custom_fields (especially Task Type)

Step 2 — Determine Scope

• Parent/epic task (has subtasks): Fetch each subtask via mcp__clickup__get_task in parallel. Process each subtask individually through Steps 3-5. The parent itself is NOT validated or sized — epics don't carry points.
• Leaf task (no subtasks, no parent): Process this single task through Steps 3-5.
• Subtask (has a parent): Process just this task through Steps 3-5. Note the parent task name for context.

If the epic has many subtasks (10+), present the summary table first and ask the user if they want the full detailed breakdown for each.

Step 3 — Validate Readiness

For each task being processed, check two elements in the task description AND comments (fetch comments via mcp__clickup__get_task_comments):

1. User Story / Description

Accept EITHER format:

• Formal: "As a [role], I want [capability], so that [benefit]"
• Informal: A clear description that explains what needs to be done and why — someone reading it can understand the work without asking follow-up questions

Flag as MISSING only if the description is empty or too vague to act on (e.g., just a title with no elaboration).

2. Acceptance Criteria

Look for:

• A section labeled "Acceptance Criteria" or "AC" (case-insensitive)
• A bulleted or numbered list of testable conditions
• Check comments if not found in description

Flag as MISSING if no acceptance criteria can be identified anywhere.

Verdict

• All required elements present → READY for sizing
• Any required element missing → "This story isn't ready to be sized" with a list of what's missing

Step 4 — Suggest Size (Only if READY)

Suggest a fibonacci size: 1, 2, 3, 5, 8, 13

Analyze these signals:

Sizing guide:

Present the suggested size with a brief rationale citing the specific signals observed. Always note that sizing is a suggestion — the team makes the final call.

Step 5 — Suggest Improvements

For EVERY task (ready or not), provide actionable suggestions:

• No formal user story? Draft one based on the description (As a [inferred role], I want [what], so that [why])
• Vague or broad AC? Suggest more specific, testable criteria
• AC items that could be separate tasks? Recommend splitting
• Description lacks context/why? Suggest adding background
• 13 points? Suggest how to decompose into smaller stories
• Missing edge cases? Suggest error handling, empty states, or boundary conditions to consider

Output Format

Single Task

## Refinement: {task name}
**Task:** {custom_id} | **Status:** {status} | **Assignee:** {assignee name}
**Type:** {Task Type value} | **Parent:** {parent name or "None"}

### Readiness Check
| Element             | Status       | Details                              |
|---------------------|-------------|--------------------------------------|
| User Story          | OK/MISSING  | {extracted story or what's needed}    |
| Acceptance Criteria | OK/MISSING  | {count of criteria or what's needed}  |

**Verdict:** READY for sizing / This story isn't ready to be sized

### Suggested Size
**{N} points** — {rationale}

Signals:
- {signal 1}
- {signal 2}
- {signal 3}

### Suggestions
- {actionable improvement 1}
- {actionable improvement 2}

Epic with Subtasks

## Refinement: {epic name} (Epic)
**Task:** {custom_id} | **Subtasks:** {count}

| # | Subtask | Ready? | Size | Missing |
|---|---------|--------|------|---------|
| 1 | {name}  | Yes    | 3    | —       |
| 2 | {name}  | No     | —    | AC      |

**Summary:**
- Ready: {n} of {total} subtasks
- Not ready: {n} subtasks
- Total suggested points: {sum of sized subtasks}

{Per-subtask detailed breakdown using the single task format}

Team Context

• Fibonacci scale: 1, 2, 3, 5, 8, 13
• Historic distribution: 95% of story points cluster at 2, 3, and 5
• Sizing rule: Only leaf subtasks carry points — parent/epic tasks are never sized
• Task Type field ID: 721ae2d2-9979-4956-9cfa-d92f2ac06238
• External systems (complexity indicators): NOC, Navblue, Mint, Trax, Oracle, ACARS, Sabre, Amadeus, SITA, Workday, GE Fuel, Proverne, Airline Choice
• Workspace/Team ID: 2277049