Scope Breakdown with Workitems
Purpose: Size and split work items so each one fits in an agent's context window and finishes in one or two sessions.
Head WI + Children
A head work item carries the feature-level context (Figma link, BRD link, overall scope); children carry the atomic units — component, page, integration. The head WI is the place where the whole-screen Figma link, the BRD section reference, and the cross-cutting scope live. It does not get assigned to an agent; it acts as a parent and a reference container. The children each carry the slice of context they need plus a pointer to the head. When a reviewer or a future agent needs the wider picture, they walk up to the head; when they need to execute, they stay in the child.
A flat backlog with no heads accumulates duplicated context — the same Figma link in five places, the same BRD section in seven — and drifts the moment any of them is updated in one place but not the others. A backlog with heads stays coherent.
Who Breaks Work Down
The BA or analyst creates the head work item and the initial breakdown; Swifter can propose a breakdown automatically from Figma plus contract; the tech lead validates before work starts. The three-role pattern:
- BA / analyst authors the head WI from the BRD plus mockups. Drafts the child breakdown using the canonical eight-step pipeline as a checklist.
- Swifter can propose a breakdown automatically from a Figma file and a contract; the BA reviews and edits the proposal rather than starting from a blank page. This capability is new and worth testing on the first feature of a new engagement.
- Tech lead / architect validates the breakdown: are dependencies explicit? is each child atomic? is the contract attached where it needs to be? Validation happens before the first child is assigned.
The validation step is non-negotiable. A breakdown that looks reasonable but bundles two atomic units into one child will produce abandoned sessions; the cheapest place to catch it is on the whiteboard.
When to Split
If the work-item description starts saying "and also," split; if a page has independent widgets at different refresh cadences, split; if scope creeps across atomic units, split. Concrete split triggers:
- The "and also" trigger — the description grew a second clause after the main verb. Split into one WI per clause.
- The independent-widget trigger — a page contains widgets that fetch from different endpoints at different cadences (a header that loads on mount, a table that paginates, a side panel that polls). Each widget gets its own work item; the page WI composes them.
- The cross-step trigger — the description spans two of the canonical eight steps (for example, "build the page and integrate the API"). Split along the step boundary.
- The mixed-type trigger — the description spans two work-item types (for example, a component spec and a defect on a sibling component). Split along the type boundary.
- The cross-module trigger — the description touches both frontend and backend. Always split.
The rule generalises: when in doubt, split. Two small work items finish faster and more reliably than one ambiguous one.
Sizing Signals
A well-sized work item finishes in 1-2 sessions; the canonical arc per type sets the size budget — component is 1-2 sessions, page is 2-3, integration is 1, defect is 1.
| WI type | Canonical session count | Arc |
|---|---|---|
| Frontend Component | 1-2 | origin (often sufficient) → development |
| Frontend Page | 2-3 | origin → development (+ wiring if state / routing is non-trivial) |
| Defect | 1 | origin (autonomous triage) |
| Integration | 1 | origin (frontend developer) |
| Sync / Maintenance | 1 | origin (analyst) |
| Backend Endpoint | 2 | origin → developer_run_01 |
| Backend Guidelines | 1 | origin (backend architect) |
| Acceptance Criteria | 1 | origin (analyst) |
| Test Cases / Scripts | 1-2 | origin (tester) |
A work item that runs into a third session for a component or a fourth for a page is mis-sized. Stop, look at the description, and either trim the scope or split. The cost of finishing the third session is almost always greater than the cost of the split.
Over-Fragmentation Anti-Pattern
Spawning <title>-attempt-2, -attempt-3 because the description was right but the data source kept changing is a known failure; amend the work item in place. The pattern observed on the pilot — a reconciliation API spread across nine attempt-named work items because the underlying mock-data shape kept changing — is the cautionary tale. Each attempt opened a new chat session, lost the context of the previous one, and added another work item to the backlog without removing the old ones. The right move was to amend the existing work item's data references and rerun the same session.
The rule: when a work item fails for an input reason, fix the input and rerun in the same work item. Only spawn a new work item when the failure is in the description or the scope itself.
Dependencies and Blockers
State dependencies explicitly using "linked WI" or "blocked by" — pages depend on components, integration work items depend on page work items and backend endpoint work items. The dependency patterns:
- Page depends on Components — a page WI lists its child component WIs and is blocked until each component reaches a usable state (the analyst's placeholder is enough; production code is not required).
- Integration depends on Page (FE) and Endpoint (BE) — the integration WI links to both and is blocked until both are at least at mock-ready state.
- Endpoint depends on Contract — every endpoint WI references the contract artefact; if the contract changes, every dependent endpoint WI is flagged for review.
- Test depends on Acceptance Criteria — test cases reference the criteria by ID; if the criteria change, the tests are flagged.
- Defect depends on the affected WI — a defect WI cross-links to the WI that produced the broken artefact so future reviewers see the chain.
Implicit dependencies — "everyone knows X must finish first" — turn into mis-ordered execution within a week. Make them explicit.