rfc-work-unit-planner

name	rfc-work-unit-planner
description	Decompose large engineering objectives into RFC-style, dependency-aware, independently verifiable work units with acceptance tests, rollback plans, merge order, and integration gates. Use for multi-session features, risky migrations, broad refactors, multi-agent work, or work too large for one safe implementation pass.

RFC Work Unit Planner

Use this skill when a task is too large or risky to implement as one uninterrupted edit.

Trigger Fit

Use it for:

• multi-session implementation;
• broad refactors;
• schema, auth, deployment, or permission migrations;
• multi-agent work;
• work that needs parallelizable units;
• projects where context loss would cause rework.

Do not use it for small fixes that can be completed and verified in one normal pass.

Output

Create a plan document under:

docs/roadmap/<slug>-work-units.md

If the repo has an existing planning folder, follow that convention.

Work Unit Schema

Each unit must include:

• id
• title
• goal
• depends_on
• scope
• out_of_scope
• files_or_areas
• acceptance_tests
• validation_commands
• risk_level
• rollback_plan
• handoff_context

Planning Workflow

1. Read project context, rules, docs, manifests, tests, and relevant code.
2. State the objective in one paragraph.
3. Identify invariants that must remain true after every unit.
4. Split work into units that can be reviewed independently.
5. Draw dependency order in text or Mermaid.
6. Mark units as serial or parallel.
7. Assign risk level:
   • L1: isolated docs or local code.
   • L2: multi-file behavior change.
   • L3: data, auth, permissions, deployment, destructive cleanup, or migration.
8. Define acceptance and rollback for every unit.
9. Add an integration gate after dependent units merge.
10. Add a final verification gate.

Merge Discipline

• Do not start a dependent unit before its dependency is verified.
• Re-run integration checks after every dependency group.
• Keep rollback plans concrete: revert files, disable flag, restore backup, rerun migration rollback, or remove config.
• Update the plan if a unit splits, stalls, or changes scope.

Handoff Context

Every unit should be executable by a fresh agent. Include:

• what to read first;
• why the unit exists;
• exact boundaries;
• expected commands;
• known risks;
• what not to change.

Avoid

• Creating a plan that is just a task list.
• Hiding dependencies.
• Merging high-risk work without an integration gate.
• Assigning parallel work that touches the same files or contracts.
• Writing rollback as "revert if needed" without specifics.