git:20260604.8378e76 to git:20260710.f9e2b31

- description: "Groom Planning tasks: verify readiness, prioritize, promote to Todo, and group into 3-8 task work units. The only gate from Planning to Todo. Invoked as /agiflow:backlog-grooming. Uses list_tasks, update_task, reorder_tasks, batch_create_work_units, list_work_units."

- tags:

- - agiflow

- - mcp

- - grooming

- - work-units

- - prioritization

- metadata:

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

- ---

-

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

-

- **Usage**:

-

- - `/agiflow:backlog-grooming` - Groom the planning backlog

- - `/agiflow:backlog-grooming <tag-filter>` - Groom tasks with specific tags

-

- **Examples**:

-

- - `/agiflow:backlog-grooming` (review all planning tasks)

- - `/agiflow:backlog-grooming feature:auth` (groom auth-related tasks only)

-

- ---

-

- **Purpose**

- Prioritize tasks from "Planning" to "Todo", group them into work units, and validate readiness for execution. This is the **ONLY** skill that moves tasks from Planning to Todo — no other workflow should bypass this gate.

-

- **Guardrails**

-

- - ONLY operate on tasks in "Planning" status

- - REFUSE to promote tasks that lack acceptance criteria (minimum 2) — suggest `refine-task` first

- - REFUSE to promote tasks with vague descriptions — suggest `refine-task` first

- - Work units are created ONLY during this skill (not during project-plan or run-work)

- - All promoted tasks must have a clear "done" definition

- - Work-unit dependencies must be explicit at the **work unit level**, not hidden inside mixed task groupings

- - If a task can ship independently, it MUST live in its own standalone path or its own work unit; do NOT mix it into a downstream dependent work unit

-

- ---

-

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

-

- ## 1. Load Planning Backlog

-

- 1. Use `list_tasks` MCP tool with `status: "planning"` to load all tasks awaiting grooming.

- 2. Use `list_work_units` MCP tool to understand existing work unit organization.

- 3. Use `list_members` MCP tool to understand available agents and their capabilities.

-

- If no tasks are in "Planning" status, report: "No tasks to groom. Use **project-plan** to create tasks first."

-

- ## 2. Assess Readiness

-

- 4. For each planning task, check:

-

- | Criterion | Required? | If missing |

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

- | Has 2+ acceptance criteria | Yes | Flag — suggest `refine-task` |

- | Description has sufficient context | Yes | Flag — suggest `refine-task` |

- | Priority is set | Yes | Can be set during grooming |

- | Tags are applied | Recommended | Can be set during grooming |

- | Assignee is set | Optional | Can be assigned during grooming |

-

- 5. Categorize tasks:

- - **Ready**: Meets all required criteria — can be promoted

- - **Needs refinement**: Missing acceptance criteria or vague description — suggest `refine-task`

- - **Blocked**: Has unresolved dependencies or unknowns

-

- 6. Present readiness report to user:

- - N tasks ready for promotion

- - M tasks need refinement (list them with reasons)

- - K tasks are blocked (list blockers)

-

- Do NOT promote tasks that need refinement. The user must address them first.

-

- ## 3. Prioritize

-

- 7. For ready tasks, apply prioritization criteria:

-

- | Factor | Weight | How to assess |

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

- | **Business value** | High | User-facing > internal tooling > tech debt |

- | **Risk / uncertainty** | High | Higher risk = do sooner to fail fast |

- | **Dependencies** | Must respect | Blockers before dependents |

- | **Effort vs. impact** | Medium | Quick wins first if equal priority |

- | **Tags** | Grouping | Related tags suggest natural batches |

-

- 8. Present ranked priority list to user for confirmation:

- - Rank, title, tags, priority, estimated effort

- - Call out any dependency constraints ("Task A must come before Task B")

- - Highlight quick wins (high impact, low effort)

-

- 9. Get user confirmation on priority order before promoting.

-

- ## 4. Group into Work Units

-

- 10. Analyze ready tasks and identify cohesive groups:

-

- ### GROUP INTO WORK UNIT when:

-

- - 3-8 related tasks that deliver a single cohesive feature

- - Tasks share the same tag prefix (e.g. all `feature:auth` tasks)

- - Tasks can be completed in ONE agent session (2-4 hours)

- - Tasks have clear dependencies and should be executed together

- - All tasks in the work unit share the same upstream dependency story and can merge back to `main` together

-

- ### DO NOT CREATE WORK UNIT when:

-

- - Only 1-2 tasks (leave as standalone)

- - Unrelated tasks (bugs across different areas)

- - Maintenance work (dependency updates, config changes)

- - More than 8 tasks (split into multiple work units)

- - Some tasks are independently executable now, but others are blocked on upstream work — split them into separate work units or leave the smaller independent slice standalone

-

- 11. Use `batch_create_work_units` MCP tool to create all work units at once. Each work unit should have:

-

- - **title**: Clear feature name (e.g., "Authentication Feature")

- - **type**: "feature" (most common), "epic" (multi-feature), "initiative" (business goals)

- - **description**: What this work unit delivers and why

- - **status**: "planning"

- - **priority**: Based on business impact

- - **estimatedEffort**: Story points (Fibonacci: 1, 2, 3, 5, 8, 13)

- - **taskIds**: List of task IDs belonging to this work unit

- - **devInfo**: Include `executionPlan` describing implementation order

-

- Leave standalone tasks (1-2 tasks) ungrouped — they can be executed individually via `run-task`.

-

- ## 5. Cross-Work-Unit Dependency Analysis

-

- **Before promoting ANY tasks, you MUST analyze dependencies across ALL work units — not just the ones you're creating now.**

- **CRITICAL:** Work units merge back to `main` only after the work unit completes. Because of that, dependency management must be explicit at the work-unit level. Do NOT create a work unit that contains both:

-

- - tasks that can start immediately, and

- - tasks that depend on another work unit being completed and merged.

-

- If you find mixed readiness inside a proposed work unit, split it into:

-

- - an independent standalone task or parallel work unit, and

- - a downstream dependent work unit that stays in `Planning` until its upstream work units are completed and merged.

-

- 12. **Load full WU context**: Use `list_work_units` to retrieve ALL existing work units in `planning`, `in_progress`, or `review` status. You need the complete picture, not just the new WUs.

-

- 13. **Identify cross-WU touchpoints**: For each new work unit, check if it shares any of the following with existing or other new WUs:

- - **Shared files/modules**: Two WUs modifying the same source files (high merge conflict risk)

- - **API contracts**: A WU producing an API that another WU consumes

- - **Shared schemas**: Database migrations or model changes that other WUs depend on

- - **Shared UI components**: A WU creating components another WU needs to use

-

- 14. **Determine execution order across WUs**:

-

- | Relationship | Rule |

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

- | WU-B consumes API/schema/component created by WU-A | WU-A must finish first (upstream) |

- | WU-A and WU-B modify the same core files | Run sequentially — do NOT run in parallel |

- | WU-A and WU-B are fully independent | Can run in parallel |

-

- **Merge-aware rule:** if WU-B needs code from WU-A to exist on `main`, then WU-B is downstream even if one or two tasks inside it look independently executable. Split those tasks out rather than keeping a mixed WU.

-

- 15. **Annotate dependencies in WU descriptions**: For any downstream WU, add to its description:

-

- ```

- **Depends on:** [WU slug/title] — [reason: e.g., "needs the user API endpoints from WU-A"]

- **Cannot start until:** [WU slug] is "completed" and merged back to `main`

- **Merge rule:** this work unit must not be dispatched until all upstream dependencies are merged

- ```

-

- 16. **Apply sequential gating**:

- - **Upstream WUs** (no dependencies): Promote their tasks to "Todo" normally

- - **Downstream WUs** (depend on upstream): Keep all of their tasks in "Planning" — do NOT promote any of them to "Todo" yet

- - **Mixed readiness discovered inside one proposed WU**: do NOT promote only the independent tasks while leaving the rest behind. Split the work into separate WUs or leave the independent slice standalone, then promote only the standalone/upstream unit.

-

- **Promotion rule**: REFUSE to promote tasks that depend on work from an upstream WU that is not yet "completed" and merged. The merge train must be respected.

-

- 17. Present the cross-WU execution plan to the user:

- ```

- Work Unit Execution Order:

- 1. [WU-A slug] — no dependencies, can start immediately

- 2. [WU-B slug] — no dependencies, can run in parallel with WU-A

- 3. [WU-C slug] — depends on WU-A and WU-B being completed and merged; all tasks held in Planning

- ```

-

- ## 6. Promote Tasks: Planning -> Todo

-

- 18. For each approved task (in priority order), respecting the gating rules from Step 5:

-

- - Use `update_task` MCP tool with `status: "todo"`

- - Set `position` for ordering within the Todo column (lower = higher priority)

- - Assign agent if not already assigned

- - Respect dependency order: prerequisite tasks get lower position numbers

- - **Do NOT promote tasks that are gated by an upstream work unit that is not yet completed and merged**

-

- This is the **ONLY** path from Planning to Todo. No other skill should bypass this.

-

- ## 7. Verify

- 19. Use `list_tasks` with `status: "todo"` to confirm all promotions.

- 20. Use `list_work_units` to confirm groupings are correct.

- 21. Present summary to user:

- - N tasks promoted from Planning to Todo

- - M work units created (with task counts)

- - K tasks left in Planning (need refinement)

- - J tasks held in Planning (gated by upstream WU dependencies and merge order)

- - Cross-WU execution order

- - Dependency order and execution sequence

- - Agent assignments

- 22. Recommend next steps:

- - "Use **run-work** to execute a work unit (implements all its tasks sequentially)."

- - "Use **run-task** to execute standalone tasks individually."

- - "Use **orchestrate** for automated priority-based task dispatch."

- - If downstream WUs are gated: "After [upstream WU] completes and is merged to `main`, run **backlog-grooming** again to promote the held tasks."

- ---

- **Common Mistakes to Avoid**

- - Promoting tasks without acceptance criteria (quality gate violation)

- - Creating work units with >8 tasks (too complex for one session)

- - Grouping unrelated tasks into one work unit (not cohesive)

- - Skipping user confirmation on priority order

- - Not respecting dependency ordering when setting positions

- - Promoting blocked tasks (resolve blockers first)

- - Creating work units during project-plan (that's this skill's job)

- - Promoting dependent WU tasks while the upstream WU is still in progress (causes merge conflicts)

- - Creating WUs in isolation without checking existing WUs for shared file/module touchpoints

- - Mixing independent and downstream-dependent tasks inside one work unit when work units only merge at completion

- - Promoting a subset of tasks from a downstream-dependent work unit instead of splitting that work into separate merge-safe units

- - Not annotating cross-WU dependencies in WU descriptions (next grooming session loses context)