Right-Sizing Executor

Break down plans into context-window-sized stories ready for execution.

Quick Start

1. Point it at your plan. Run /right-sizing-executor path/to/prd.md or paste a feature description directly.
2. Review the output. The skill produces tasks/execution-plan-[feature].md with dependency-ordered, right-sized stories. Each story fits in one context window.
3. Hand stories to agents (or yourself). Execute them in order. Each story has acceptance criteria you can verify before moving on.

Overview

AI agents work best on focused, well-scoped tasks. This skill takes any plan, PRD, or feature description and:

1. Evaluates each story/task for size
2. Splits anything too large for a single context window
3. Orders stories by dependency
4. Outputs an execution-ready plan

The Job

Input

Any of:

• A PRD markdown file (read from path)
• A feature description (pasted text)
• A list of tasks/stories
• A plan file from plan mode

Output

An execution plan saved to tasks/execution-plan-[feature].md with:

• Right-sized stories
• Dependency order
• Size estimates
• Execution notes

Commands

/right-sizing-executor [path-or-description]

Analyze and right-size the given plan.

/right-sizing-executor check [path]

Check an existing execution plan for sizing issues without rewriting it.

The Core Rule

Each story must be completable in ONE context window.

If you cannot describe the change in 2-3 sentences, it is too big.

Sizing Heuristics

Small (1 context window, no split needed)

• Schema/migration change only
• Add a single UI component to an existing page
• Update one server action or API endpoint
• Add a configuration file
• Write tests for an existing function
• Fix a single bug with known cause

Signal: Change touches 1-3 files, logic fits in head.

Medium (1 context window, might be tight)

• Backend logic with tests
• Full-page UI component with state
• API endpoint with validation and error handling
• Database query optimization with before/after verification

Signal: Change touches 3-5 files, has clear boundaries.

Large (split required)

• Multi-file refactor
• Feature with both backend and frontend
• "Build the entire X"
• Integration with external service
• Anything requiring multiple dependent steps

Signal: Change touches 5+ files, has internal dependencies.

Splitting Strategy

Step 1: Identify the vertical slices

Each slice should be independently verifiable.

Good slices (each can be checked independently):

1. Database schema + migration
2. Backend service/action
3. API endpoint
4. UI component
5. Integration/wiring
6. Tests

Bad slices (cannot be checked independently):

1. "All the types"
2. "All the utilities"
3. "Half the component"

Step 2: Order by dependency

Schema → Backend → API → UI → Integration → Tests

Earlier stories must NOT depend on later ones.

Step 3: Write acceptance criteria

Each story gets verifiable criteria. Not "works correctly" but specific checks:

• "Column exists in database with correct type and default"
• "API returns 200 with expected JSON shape"
• "Button renders and onClick triggers handler"
• "Typecheck passes"

Output Format

# Execution Plan: [Feature Name]

**Source**: [PRD path or description]
**Generated**: [Date]
**Total Stories**: [N]
**Estimated Complexity**: [Low/Medium/High]

---

## Dependency Graph

S-001 (schema) └─> S-002 (backend) └─> S-003 (API) └─> S-004 (UI)

---

## Stories

### S-001: [Title]
**Size**: Small
**Depends on**: None
**Description**: [2-3 sentences max]
**Files**: [expected files to touch]
**Acceptance Criteria**:
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Typecheck passes

### S-002: [Title]
**Size**: Small
**Depends on**: S-001
**Description**: [2-3 sentences max]
**Files**: [expected files to touch]
**Acceptance Criteria**:
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Typecheck passes

---

## Split Decisions

| Original Item | Decision | Reason |
|---|---|---|
| "Add user dashboard" | Split into 4 stories | Touches schema, API, 2 UI components |
| "Add status field" | Keep as-is | Single migration + column |

---

## Notes

- [Any context for the executor]

Size Check Signals

When evaluating if a story is too big, look for these red flags:

Complexity Scoring

Assign each story a 1-5 complexity score before sizing. This makes split decisions more consistent and gives executors a sense of effort.

Scoring Rubric

Score Interpretation

Example Scoring

"Add user profile page with avatar upload"

• Files: schema.sql, profile.service.ts, upload.service.ts, profile.route.ts, ProfilePage.tsx, AvatarUpload.tsx = 3 points (6 files)
• Layers: DB + backend + API + UI = 4 points
• External deps: S3 for avatar storage = 2 points
• State: user profile state in store = 1 point
• Total: 10 points. Split into at least 3 stories: schema + backend, avatar upload service, UI components.

Add the score to each story in the execution plan output:

### S-001: Add profile columns to users table
**Size**: Small | **Complexity**: 2

Multi-Language Projects

Monorepos often contain code in multiple languages (TypeScript frontend, Python backend, Go services, SQL migrations). Splitting heuristics need adjustment.

Language Boundary Rule

Treat each language as a hard split boundary. A single story should not require the executor to context-switch between languages, because:

• Different linting, testing, and build tools per language
• Context window gets consumed faster when loading toolchains for multiple languages
• Errors in one language are harder to debug while thinking in another

Splitting by Repo Structure

Dependency Order Across Languages

SQL migrations -> Backend service (any language) -> API layer -> Frontend -> E2E tests

If the backend is in Python and the frontend in TypeScript, you still follow this order. The integration story at the end verifies that the contract between languages holds (API request/response shapes match).

Common Mistakes

Mistake 1: The "God Story"

Bad: "Build the settings page"

This story touches the database (new preferences table), backend (CRUD endpoints), frontend (form components, validation, state), and possibly auth (permission checks). Complexity score: 8+.

Fix: Split into 4 stories:

• S-001: Add preferences table and migration (Small, complexity 2)
• S-002: Preferences CRUD service + API routes (Small, complexity 2)
• S-003: Settings form UI with client-side validation (Medium, complexity 3)
• S-004: Wire settings page to API, add permission check (Small, complexity 2)

Mistake 2: The "Horizontal Slice"

Bad: "Create all TypeScript types for the project"

Types without implementation cannot be verified. You will discover type errors only when you write the code that uses them, leading to rework.

Fix: Include types in each vertical story. S-001 defines the types it needs alongside the implementation that uses them.

Mistake 3: The "Premature Integration"

Bad: "Add Stripe payment flow" as a single story.

This mixes an external API integration (high risk, 2 points per dependency) with UI work and backend logic. If the Stripe sandbox is down, the entire story is blocked.

Fix: Split so the external dependency is isolated:

• S-001: Stripe service wrapper with mock responses and tests (isolate the risk)
• S-002: Payment backend logic using the wrapper (works with mocks)
• S-003: Payment UI (works with mock API)
• S-004: Integration test with real Stripe sandbox

Mistake 4: The "Under-Split"

Bad: Splitting a 3-file, single-layer bug fix into 3 stories.

Over-splitting wastes context on loading the same context repeatedly. If a fix is cohesive (same layer, same feature, same test run verifies it), keep it together.

Fix: Score it first. If complexity is 1-2, it is already right-sized. Do not split below complexity 2 unless the files are in different repositories.

References

See references/sizing-guide.md for detailed examples of well-sized vs poorly-sized stories.