Task Splitting Protocol

Split **L** and **XL** work into small, reviewable slices. Prevents AI sessions from turning into unbounded refactors.

Purpose

Split L and XL work into small, reviewable slices. Prevents AI sessions from turning into unbounded refactors.

See cost-gate.md for when splitting is mandatory and ai-execution-protocol.md for Patch Mode limits.

Splitting Principles

Order slices when possible:

1. RFC / design only
2. Contract / types only
3. State model only
4. UI integration only
5. API / data integration only
6. Tests / verification only
7. Docs sync only

Not every project needs all seven; skip empty phases.

Slice Definition

Each slice must document:

Name
Goal
Allowed Files
Forbidden Files
Max Diff Size
Validation Command
User-visible Behavior
Rollback Plan
Next Slice

Recommended Slice Sizes

Size	Files	Approval
Small patch	1–3	Normal
Normal patch	4–8	Normal (Patch Mode default)
Large patch	9–15	Explicit user approval
>15 files	—	Split again

Packages: Patch Mode defaults to max 2 packages touched per slice.

Scope Expansion Stop Rule

If implementation reveals wider scope than approved, stop immediately. Do not silently continue.

Output:

Scope expansion detected.
Original scope:
New required scope:
Why this is necessary:
Safer split:
Please choose: A) Approve expanded slice  B) New RFC  C) Defer

Wait for user choice.

Example: Add Remote App Registry (illustrative)

Slice	Goal
1	RFC only — data shape, failure modes
2	`app-contract` types + manifest fields
3	TanStack Query hook + mock in shell
4	Registry merge in `registry.ts`
5	Verify + `pnpm typecheck` / `pnpm lint`
6	Docs sync — `app-registry.md`, RFC Implementation Notes

Prox OS Slice Hints

Shell-only behavior (shortcuts, login gate): keep changes in apps/os-shell/src/shell/** without touching os-apps unless required.
New official app: manifest in packages/os-apps + registry + ShellAppIcon can be one slice if ≤8 files.
Window/Space behavior: prefer state slice (window-manager/store.ts) before visual polish across many components.
Docs: dedicated Docs Sync slice after code merges.

Task Splitting Protocol

On this page