refine-task

name: refine-task 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 . 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 — 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:

   ## 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:

   {
     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:

    {
      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:

    {
      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:

Common Refinement Patterns

API Endpoint Task

## 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

## 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