Step Decomposer

Breaks down an approved engineering goal or task brief into small, sequential execution steps. Ensures each step is independently testable before proceeding to the next.

1. Purpose

Convert a task objective into a sequence of small, verifiable actions. A "step" is an atomic unit of work touching one concern that takes under 5 minutes to verify.

2. When to Use

Use this skill when:

• An approved task brief or clear goal exists.
• The task involves multiple file edits, dependencies, or sequential commands.
• Preparing execution steps for autonomous or semi-autonomous execution.

3. When Not to Use

• Do not use to define or clarify scope; use task-brief.
• Do not use to report progress on in-flight work; use status-update.
• Do not use for general codebase exploration; use repo-inspector.

4. Required Inputs

• task_goal: A clear statement of the objective or approved task brief (string).
• target_files: Known files to be created or modified (list of paths).

5. Missing-Input Behavior

1. If task_goal is missing or empty: stop and ask: "Please provide the task goal or approved task brief to decompose."
2. If target_files are unknown: include Step 1 as an inspection step using repo-inspector to locate the files before editing.
3. Do not invent non-existent file paths.

6. Procedure

Follow these numbered actions:

1. Action 1: Identify Dependencies and Order
   • Determine what must happen first (e.g., config changes before code changes, code changes before test updates).
2. Action 2: Divide into Atomic Steps
   • Limit the total sequence to 3 to 7 steps.
   • Ensure each step touches at most 2 related files.
3. Action 3: Attach an Objective Verification Gate to Each Step
   • For every step, specify the exact command or inspection check to confirm completion (e.g., npm run lint, pytest tests/test_auth.py).
4. Action 4: Define Rollback Action for Each Step
   • State what command reverts the step if the verification gate fails (e.g., git checkout -- file.js).
5. Action 5: Emit the Execution Plan
   • Format the plan per Section 8.

7. Decision Rules

• If any single step requires more than 50 lines of code changes: split it into two sub-steps.
• If a step modifies database schemas or production configs: insert a manual approval checkpoint before that step.
• If all steps are complete: final step must run the full test suite.

8. Output Format

Emit the decomposed plan using this structured template:

### Execution Plan: [Task Title]

- **Total Steps**: [Count]
- **Target Files**: [Comma-separated file list]

#### Ordered Steps
1. **Step 1: [Short Title]**
   - **Action**: [Exact modification or command]
   - **Target**: `[file path]`
   - **Verification Gate**: `[command or check]` -> Expected: `[expected result]`
   - **Rollback**: `[revert command]`

2. **Step 2: [Short Title]**
   - **Action**: [Exact modification or command]
   - **Target**: `[file path]`
   - **Verification Gate**: `[command or check]` -> Expected: `[expected result]`
   - **Rollback**: `[revert command]`

#### Final Verification Gate
- `[Overall test command, e.g., npm test]`

9. Verification Checklist

• Every step has an explicit verification gate.
• Every step has a rollback instruction.
• Steps are strictly ordered by dependency.
• No step touches unrelated files.

10. Common Failures and Recovery

11. Stop or Escalation Conditions

Stop and ask the user when:

• The task goal contains contradictory requirements.
• External infrastructure or credentials are required before continuing.

12. Examples

Example 1: Successful Execution

Input:

Task: Add timeout option to HTTP client in src/http.ts and verify in tests/http.test.ts

Expected Observable Actions:

1. Produced 3 sequential steps.
2. Included verification commands and rollback commands.

Output:

### Execution Plan: Add HTTP Client Timeout Option

- **Total Steps**: 3
- **Target Files**: `src/http.ts`, `tests/http.test.ts`

#### Ordered Steps
1. **Step 1: Add Timeout Interface and Defaults**
   - **Action**: Add `timeoutMs?: number` to `RequestOptions` interface and set default to 5000ms.
   - **Target**: `src/http.ts`
   - **Verification Gate**: `npx tsc --noEmit` -> Expected: Exits code 0
   - **Rollback**: `git checkout src/http.ts`

2. **Step 2: Add Timeout Regression Test**
   - **Action**: Add test case expecting timeout error when request exceeds timeoutMs.
   - **Target**: `tests/http.test.ts`
   - **Verification Gate**: `npm test tests/http.test.ts` -> Expected: 1 failure (timeout not wired yet)
   - **Rollback**: `git checkout tests/http.test.ts`

3. **Step 3: Wire Timeout Signal to Fetch Call**
   - **Action**: Pass AbortSignal.timeout(timeoutMs) to internal fetch call.
   - **Target**: `src/http.ts`
   - **Verification Gate**: `npm test tests/http.test.ts` -> Expected: All tests pass
   - **Rollback**: `git checkout src/http.ts`

#### Final Verification Gate
- `npm test`

Example 2: Ambiguous or Missing Input

Input:

Task: "Refactor backend"

Output:

### Execution Plan: Blocked - Missing Scope

- **Status**: Escalation Required

The goal "Refactor backend" is too broad to decompose safely. Please provide:
1. Specific target module or files (e.g., `src/auth/` or `src/database/`).
2. Desired architectural change or behavioral constraints.
Alternatively, run `task-brief` first to establish scope.

Example 3: Expected Final Output

Output:

### Execution Plan: Add Environment Variable Validation

- **Total Steps**: 2
- **Target Files**: `src/config.ts`, `tests/config.test.ts`

#### Ordered Steps
1. **Step 1: Create Validation Function**
   - **Action**: Add `validateEnv()` throwing on missing `PORT` or `DATABASE_URL`.
   - **Target**: `src/config.ts`
   - **Verification Gate**: `npm run lint` -> Expected: Clean exit 0
   - **Rollback**: `git checkout src/config.ts`

2. **Step 2: Add Configuration Unit Tests**
   - **Action**: Test missing variable raises descriptive error.
   - **Target**: `tests/config.test.ts`
   - **Verification Gate**: `npx jest tests/config.test.ts` -> Expected: 2 passed
   - **Rollback**: `git checkout tests/config.test.ts`

#### Final Verification Gate
- `npm test`