git:20260604.8378e76 to git:20260710.f9e2b31

- description: "Refine a task into a complete, autonomous-ready spec with SMART acceptance criteria, technical context, and AI-readiness checks. Use when a task is vague or keeps getting rejected. Invoked as /agiflow:refine-task <task>. Uses get_task, update_task, list_tasks, create_task_comment, list_artifacts."

- tags:

- - agiflow

- - mcp

- - refinement

- - acceptance-criteria

- metadata:

- mirrors: backend/apis/agiflow-api .../prompts/refineTask.md

- ---

-

- > Invoked as `/agiflow:refine-task`. In hosts without slash-prompts, this skill is triggered by matching intent and drives AgiFlow via its MCP tools.

-

- **Usage**:

-

- - `/agiflow:refine-task <task-slug-or-id>` - Refine specific task

- - `/agiflow:refine-task` - List and select from available tasks to refine

-

- **Examples**:

-

- - `/agiflow:refine-task DXX-2` (using slug)

- - `/agiflow:refine-task 01K8FABMNEJG1XTA9JGHSNFV40` (using ID)

- - `/agiflow:refine-task` (interactive selection)

-

- ---

-

- **Purpose**

- Refine task descriptions to provide sufficient context for AI agents to work autonomously. Well-refined tasks enable agents to understand scope, constraints, and expected outcomes without requiring human clarification.

-

- **Guardrails**

-

- - Refine only the task scope - do not expand or reduce the original intent.

- - Ensure all required context is explicitly documented, not implied.

- - Acceptance criteria must be concrete, measurable, and verifiable by an agent.

- - Identify and resolve ambiguities before marking task as refined.

-

- If a task slug/id is provided, load it with `get_task`; otherwise list available tasks with `list_tasks` for selection.

-

- ---

-

- ## AgiFlow Project Management Guidelines

-

- Follow the shared AgiFlow project-management guidelines in [`references/agiflow-agents.md`](../../references/agiflow-agents.md) — agent assignment, the task status workflow and transitions, work-unit best practices, and the tags strategy apply to this workflow.

-

-

- ---

-

- **Steps**

- Track these steps as TODOs and complete them one by one.

-

- ## 1. Task Selection & Loading

-

- **If task slug/id NOT provided:**

-

- 1. Use `list_tasks` MCP tool to show tasks needing refinement:

- - Filter by `status: "Planning"` or `status: "Todo"` for tasks not yet started

- - Look for tasks with minimal descriptions or vague acceptance criteria

- - Display: slug, title, priority, acceptance criteria count

- 2. Ask user to select which task to refine.

- 3. Once user selects, proceed with the selected task slug/id.

-

- **If task slug/id IS provided:** 4. Use `get_task` MCP tool with the provided slug/id to retrieve:

-

- - Task: title, description, priority, status, acceptance criteria

- - Comments: Any clarifications or discussions

- - Work unit context: If part of a work unit, understand the broader scope

-

- 5. Review the task to identify refinement needs:

- - Is the description clear and complete?

- - Are acceptance criteria specific and measurable?

- - Are dependencies and constraints documented?

- - Can an AI agent work on this without asking questions?

-

- ## 2. Analyze Context Requirements

-

- 6. Determine what context an AI agent would need:

-

- **Technical Context:**

- - Which files/modules are affected?

- - What existing patterns should be followed?

- - Are there related implementations to reference?

-

- **Business Context:**

- - What problem does this solve?

- - Who is the end user or beneficiary?

- - What are the success metrics?

-

- **Constraints:**

- - Performance requirements?

- - Security considerations?

- - Compatibility requirements?

- - Dependencies on other tasks?

-

- 7. Use codebase exploration to gather missing context:

- - Search for related files and patterns

- - Identify existing conventions

- - Find relevant documentation

-

- ## 3. Refine Task Description

-

- 8. Update task description via `update_task` to include:

-

- **Structure:**

-

- ```markdown

- ## Overview

-

- [1-2 sentences explaining the goal and why it matters]

-

- ## Skills

-

- [List skill names the executing agent should load before working on this task.

- Match skills to the task domain: e.g. `backend-development` for API work,

- `web-app-development` for frontend features, `react-native-development` for native UI,

- `unit-testing` / `integration-testing` / `e2e-testing` for test tasks,

- `frontend-design` for visual polish, `drizzle-migration` for schema changes, etc.

- Only include skills that are directly relevant to the implementation.]

-

- ## Technical Context

-

- - Related files: `path/to/file.ts`, `path/to/other.ts`

- - Pattern to follow: [reference existing implementation if applicable]

- - Dependencies: [list any prerequisite tasks or external dependencies]

-

- ## Implementation Notes

-

- [Specific guidance for implementation approach]

-

- ## Out of Scope

-

- [Explicitly list what should NOT be done to prevent scope creep]

- ```

-

- 9. Update description via `update_task`:

- ```typescript

- {

- description: 'Refined description following the structure above';

- }

- ```

-

- ## 4. Refine Acceptance Criteria

-

- 10. Evaluate each acceptance criterion using the SMART framework:

- - **Specific**: Clearly states what must be done

- - **Measurable**: Can be verified programmatically or by inspection

- - **Achievable**: Within scope of a single task

- - **Relevant**: Directly contributes to task goal

- - **Testable**: An agent can verify completion

-

- 11. Rewrite vague criteria to be specific:

-

- **Before (Vague):**

- - "Handle errors properly"

- - "Make it performant"

- - "Add tests"

-

- **After (Specific):**

- - "Return HTTP 400 with error message for invalid input; return HTTP 500 for server errors with logged stack trace"

- - "API response time < 200ms for p95 under 100 concurrent requests"

- - "Add unit tests covering: happy path, validation errors, edge cases (empty input, max length); maintain 80% coverage"

-

- **Deriving test cases from criteria:**

- For each acceptance criterion, ask:

- - What must be true for this to pass? (happy path test)

- - What could go wrong? (error path test)

- - What are the boundary conditions? (edge case test)

- - What test type fits? (Unit for validation logic, Integration for API/DB, E2E for user flows)

-

- 12. Update acceptance criteria via `update_task`:

- ```typescript

- {

- acceptanceCriteria: [

- { description: 'Specific criterion 1', checked: false },

- { description: 'Specific criterion 2', checked: false },

- // ... more criteria

- ];

- }

- ```

-

- ## 5. Add Implementation Hints (devInfo)

-

- 13. Document implementation hints via `update_task` devInfo:

- ```typescript

- {

- devInfo: {

- suggestedApproach: "Brief description of recommended approach",

- referenceImplementations: ["path/to/similar/file.ts:42"],

- potentialChallenges: ["List any known gotchas or tricky areas"],

- testingStrategy: "How to verify this works correctly",

- testCases: [

- "Happy path: valid input produces expected output",

- "Error path: invalid input returns clear error message",

- "Edge case: empty input, max length, special characters"

- ],

- testTypes: "Unit for validation, Integration for API calls, E2E for user flows"

- }

- }

- ```

-

- ## 6. Collect & Attach Artifacts

-

- 14. Ask the user if they have any supporting artifacts to attach:

- - Screenshots (UI bugs, current state, expected state)

- - Design mockups / wireframes (screen layouts, page flows)

- - Documentation (API specs, requirements docs, diagrams)

- - Reference images (competitor examples, inspiration)

-

- 15. If the user provides artifacts, determine the appropriate scope:

-

- **Project-level artifacts** (shared across tasks — upload to project):

- - Screen/page mockups and wireframes

- - Design system references

- - Architecture diagrams

- - Shared documentation (API specs, PRDs)

-

- Use `get_artifact_signed_url` with `action: "upload"` and the project's ID:

-

- ```

- → get_artifact_signed_url({ action: "upload", filename: "mockup-login-page.png", contentType: "image/png" })

- → User uploads file to the returned URL

- → update_artifact({ key: "<returned-key>", status: "uploaded" })

- ```

-

- **Task-level artifacts** (specific to this task — link to task):

- - Bug screenshots

- - Task-specific reference images

- - Reproduction steps recordings

-

- Use `get_artifact_signed_url` then link to the task:

-

- ```

- → get_artifact_signed_url({ action: "upload", filename: "bug-screenshot.png", contentType: "image/png" })

- → User uploads file to the returned URL

- → update_artifact({ key: "<returned-key>", status: "uploaded", taskId: "<task-id>" })

- ```

-

- 16. Reference attached artifacts in the task description or devInfo so agents know to check them.

-

- ## 7. AI-Readiness Validation

-

- Before completing refinement, run this type-aware readiness check. Infer the task type from tags and title.

-

- 17. **Check artifacts are referenced, not just uploaded:**

- - Use `list_artifacts` to find artifacts linked to the task or its project

- - For EACH artifact: verify it is explicitly mentioned in the task description or devInfo

- - An uploaded but unreferenced artifact is invisible to the executing agent — add a reference or flag it

-

- 18. **Type-specific readiness checklist:**

-

- **For UI/Frontend tasks** (tags: `feat:ui`, `feat:frontend`, or title indicates UI work):

-

- | Item | Verdict | Notes |

- | ------------------------------------------------------------------------------ | --------------------- | ----- |

- | Visual spec exists (mockup, wireframe, or detailed text description of layout) | PASS / FAIL / WARNING | |

- | Component states defined (default, loading, error, empty, disabled) | PASS / FAIL | |

- | Data shape specified (what props/API data does the component consume?) | PASS / FAIL | |

- | Interaction behavior described (click, hover, form submission, navigation) | PASS / WARNING | |

-

- **For API/Backend tasks** (tags: `feat:api`, `feat:backend`, or title indicates API work):

-

- | Item | Verdict | Notes |

- | ------------------------------------------------- | -------------- | ----- |

- | Endpoint path and HTTP method defined | PASS / FAIL | |

- | Request payload shape specified (or "no payload") | PASS / FAIL | |

- | Success response shape specified | PASS / FAIL | |

- | Error response codes and shapes specified | PASS / WARNING | |

- | Auth/permission requirements noted | PASS / WARNING | |

-

- **For Data/Schema tasks** (tags: `feat:db`, `chore:migration`, or title indicates schema work):

-

- | Item | Verdict | Notes |

- | ----------------------------------------------- | -------------- | ----- |

- | Table/column changes described | PASS / FAIL | |

- | Data types and constraints specified | PASS / FAIL | |

- | Relationships and foreign keys documented | PASS / WARNING | |

- | Migration strategy noted (additive vs breaking) | PASS / WARNING | |

-

- **For all tasks:**

-

- | Item | Verdict | Notes |

- | --------------------------------------------------------- | -------------- | ----- |

- | Acceptance criteria are SMART (not vague) | PASS / FAIL | |

- | File paths or patterns to follow are specified | PASS / WARNING | |

- | Out-of-scope boundaries are explicit | PASS / WARNING | |

- | Dependencies on other tasks are documented | PASS / WARNING | |

- | Required skills listed in description (## Skills section) | PASS / WARNING | |

-

- 19. **Determine readiness verdict:**

- - **Ready**: All PASS, no FAIL items — task can be promoted

- - **Needs-More-Info**: Has WARNING items but no FAIL — task can proceed with caveats noted for the agent

- - **Not-Ready**: Has any FAIL item — flag what's missing and ask the user to provide it before promotion

-

- 20. If verdict is **Not-Ready**, document the specific gaps in a task comment and do NOT mark the task as refined. The user must address the FAIL items first.

-

- ## 8. Verify Refinement Quality

-

- 21. Review the refined task by asking:

- - [ ] Can an agent understand the goal without clarification?

- - [ ] Are all file paths and references explicit?

- - [ ] Is the scope clearly bounded (what's in vs. out)?

- - [ ] Can each acceptance criterion be verified objectively?

- - [ ] Are dependencies and blockers identified?

- - [ ] Are relevant artifacts attached AND referenced in description/devInfo?

- - [ ] Does the AI-readiness check pass for this task type?

-

- 22. If any answer is "no", iterate on that section.

-

- ## 9. Document Refinement

-

- 23. Use `create_task_comment` to add refinement summary:

-

- ```

- **Task Refined**

-

- Changes made:

- - [List what was clarified or added]

-

- Key context added:

- - [Important context that was missing]

-

- Artifacts attached:

- - [List any artifacts uploaded, with scope: project-level or task-level]

-

- AI-Readiness: [Ready / Needs-More-Info / Not-Ready]

- [If Needs-More-Info or Not-Ready, list specific gaps]

- ```

-

- 24. If task is now ready for agent execution, no status change needed (remains "Todo").

- If further human input is required, document what's needed in the comment.

-

- ---

-

- **Refinement Quality Checklist**

-

- Before completing refinement, verify:

-

- | Criterion | Status |

- | -------------------------------------------------------- | ------ |

- | Clear goal statement | |

- | Technical context (files, patterns) | |

- | Explicit scope boundaries | |

- | SMART acceptance criteria | |

- | Test cases for critical criteria (happy + error paths) | |

- | Dependencies documented | |

- | Implementation hints provided | |

- | Required skills listed in ## Skills section | |

- | Artifacts attached AND referenced in description/devInfo | |

- | Type-specific readiness checklist passes (no FAIL items) | |

- | No ambiguous language | |

-

- **Common Refinement Patterns**

-

- ### API Endpoint Task

-

- ```markdown

- ## Overview

-

- Add GET /api/users/:id endpoint to retrieve user profile.

-

- ## Technical Context

-

- - Route file: `src/routes/users.ts`

- - Pattern: Follow existing `GET /api/organizations/:id` in `src/routes/organizations.ts:45`

- - Schema: Use existing `UserSchema` from `src/schemas/user.ts`

-

- ## Implementation Notes

-

- - Use existing `UserRepository.findById()` method

- - Return 404 if user not found

-

- ## Out of Scope

-

- - User creation (separate task)

- - Authentication changes

- ```

-

- ### UI Component Task

-

- ```markdown

- ## Overview

-

- Create UserAvatar component displaying user profile picture with fallback initials.

- ## Technical Context

- - Component path: `src/components/UserAvatar/index.tsx`

- - Pattern: Follow `src/components/OrganizationLogo/index.tsx`

- - Design system: Use `@agimonai/frontend-web-ui` Avatar primitive

- ## Implementation Notes

- - Accept size prop: 'sm' | 'md' | 'lg'

- - Fallback to initials when no image URL

- - Use semantic colors from design system

- ## Out of Scope

- - Image upload functionality

- - Edit mode

- ```

- ---

- **Common Mistakes to Avoid**

- - Leaving implicit assumptions undocumented

- - Using vague terms like "properly", "correctly", "efficiently"

- - Acceptance criteria that require subjective judgment

- - Missing file paths or references

- - Not specifying what's out of scope

- - Expanding task scope during refinement

- - Adding acceptance criteria that belong to different tasks

- - Not verifying the task can be completed autonomously