Execute Outcome

Execute all Work Units (sub-issues) for an Outcome, handling dependencies intelligently.

Usage

/execute-outcome <outcome-issue-id>

Example: /execute-outcome BHU-139

Important: Using Linear MCP

Use Linear MCP tools as direct function calls, NOT bash commands.

Git Worktree Strategy

Parallel execution requires isolation. Each parallel Work Unit runs in its own git worktree.

main-repo/
├── .git/
├── src/
├── ...
└── .worktrees/              # Created during execution
    ├── wu-BHU-141/          # Worktree for WU 1
    │   ├── src/
    │   └── ...
    └── wu-BHU-142/          # Worktree for WU 2
        ├── src/
        └── ...

Why worktrees?

• Each agent modifies files independently
• Tests run in isolation (no interference)
• Git state stays clean (one branch per WU)
• Merge conflicts detected at integration, not during work

Setup requirements:

1. Add .worktrees/ to .gitignore (one-time setup)
2. Worktrees share the same .git directory — no duplicate clones
3. Dependencies (node_modules, .venv) must exist in worktree or be symlinked

Worktree Environment Setup

Before running /work in a worktree, ensure dependencies are available:

Python (uv/pip):

# Option A: Install in worktree (isolated, slower)
cd .worktrees/wu-BHU-141 && uv sync

# Option B: Symlink from main (shared, faster)
ln -s $(pwd)/.venv .worktrees/wu-BHU-141/.venv

Node (npm/pnpm):

# Option A: Install in worktree
cd .worktrees/wu-BHU-141 && npm install

# Option B: Symlink node_modules (careful with native deps)
ln -s $(pwd)/node_modules .worktrees/wu-BHU-141/node_modules

Recommendation: Use symlinks for speed. If a WU modifies dependencies, install fresh.

Workflow

Step 1: Fetch Outcome and Work Units

1. Fetch Outcome issue via mcp__linear-server__get_issue
2. List child issues (Work Units) via mcp__linear-server__list_issues with parentId
3. Display:

   Outcome: [title]
   
   Work Units found: N
   1. [WU-1 title] (proof: X, budget: Y)
   2. [WU-2 title] (proof: X, budget: Y)
   ...
   

Step 2: Determine Dependencies

Ask human:

Do any Work Units depend on others?

1. WU-1: [title]
2. WU-2: [title]
3. WU-3: [title]

Enter dependencies (e.g., "2→1" means WU-2 depends on WU-1):
Or type "none" if all are independent.

Build dependency graph from response.

Step 3: Plan Execution Order

Based on dependencies:

1. Topological sort to find valid order
2. Identify parallelizable groups (no interdependencies)
3. Present plan:

   Execution Plan:
   
   Batch 1 (parallel, 2 worktrees):
   - BHU-141: [title]
   - BHU-143: [title]
   
   Batch 2 (after batch 1):
   - BHU-142: [title] (depends on BHU-141)
   
   Proceed? [y/n]
   

Step 4: Execute Batches

For each batch:

If batch has 1 Work Unit:

• Execute inline using /work logic (no worktree needed)
• Commit directly to current branch

If batch has multiple Work Units (parallel):

1. Setup worktrees:

   # Get current branch name
   CURRENT_BRANCH=$(git branch --show-current)
   
   # Create worktree directory
   mkdir -p .worktrees
   
   # For each WU in batch, create worktree with feature branch
   git worktree add .worktrees/wu-BHU-141 -b wu/BHU-141 $CURRENT_BRANCH
   git worktree add .worktrees/wu-BHU-143 -b wu/BHU-143 $CURRENT_BRANCH
   

2. Launch parallel agents:

   For each Work Unit in the batch, invoke the Task tool:

   Task(
     subagent_type: "general-purpose"
     description: "Execute WU BHU-141"
     prompt: |
       Execute Work Unit BHU-141 in isolated worktree.
   
       ## Context
       - Issue ID: BHU-141
       - Worktree path: /absolute/path/to/.worktrees/wu-BHU-141
       - Base branch: wu/BHU-141
   
       ## Instructions
       1. cd to worktree: cd /absolute/path/to/.worktrees/wu-BHU-141
       2. Run /work BHU-141 workflow (fetch issue, TDD, implement, review)
       3. All file operations MUST happen in the worktree path
       4. All git commands MUST use: git -C /absolute/path/to/.worktrees/wu-BHU-141
       5. Commit format: [BHU-141] <type>: <description>
   
       ## Critical
       - NEVER modify files outside the worktree
       - Return verdict: APPROVED / NEEDS_CHANGES / BLOCKED_FOR_HUMAN
   )
   

   Launch all batch agents in parallel (single message with multiple Task calls).

3. Wait and collect:

   • Wait for all agents to complete
   • Collect results (APPROVE/NEEDS_CHANGES/BLOCKED)

4. Integrate completed work:

   # For each successful WU, merge its branch
   git merge wu/BHU-141 --no-edit
   git merge wu/BHU-143 --no-edit
   

5. Cleanup worktrees:

   git worktree remove .worktrees/wu-BHU-141
   git worktree remove .worktrees/wu-BHU-143
   git branch -d wu/BHU-141
   git branch -d wu/BHU-143
   

Between batches:

• Report progress
• Ensure all merges from previous batch are complete
• If any Work Unit failed, ask human:

  BHU-141 failed review. Options:
  1. Retry BHU-141
  2. Skip BHU-141, continue with others (cleanup its worktree)
  3. Stop execution (cleanup all worktrees)
  

Step 5: Handle Merge Conflicts

After parallel batch completion, merges may conflict:

1. Detect conflict:

   git merge wu/BHU-141 --no-edit
   # If exit code != 0 and output contains "CONFLICT"
   

2. On conflict, report to human:

   Merge conflict integrating BHU-141.
   
   Conflicting files:
   - src/models/land.py
   - src/services/valuation.py
   
   Options:
   1. I'll resolve manually (pause execution)
   2. Abort BHU-141, keep other WUs
   3. Stop execution entirely
   

3. If human resolves:

   • Wait for human to run git add . && git commit
   • Verify merge complete: git status shows clean state
   • Continue with next merge or batch

4. Conflict prevention tips:

   • Work Units touching same files should be sequential, not parallel
   • During dependency mapping (Step 2), ask: "Do any WUs modify the same files?"

Step 6: Handle Blocked Items

If a Work Unit is BLOCKED_FOR_HUMAN:

1. Pause batch execution
2. Report the blocking issue
3. Keep worktree intact (human may need to inspect)
4. Wait for human decision
5. Resume or abort based on decision

Step 7: Update Outcome

After all Work Units complete:

1. Update Outcome issue status checklist:

   ## Status
   - [x] Work Units defined
   - [x] Work Units complete
   - [ ] Success metric verified
   

2. Report to human:

   ## Outcome Execution Complete
   
   Outcome: [title]
   
   Work Units: N/N complete
   - [x] WU-1: [title] - APPROVED
   - [x] WU-2: [title] - APPROVED
   - [x] WU-3: [title] - APPROVED
   
   Total lines changed: X
   Total decisions logged: Y
   
   Next: Verify success metric.
   

Error Handling

Cleanup on Abort

If execution is aborted (by human or error), always cleanup:

# List all worktrees created for this outcome
git worktree list | grep ".worktrees/wu-"

# Remove each worktree
git worktree remove .worktrees/wu-BHU-141 --force
git worktree remove .worktrees/wu-BHU-143 --force

# Delete orphan branches
git branch -D wu/BHU-141 wu/BHU-143

# Remove worktrees directory if empty
rmdir .worktrees 2>/dev/null || true

Never leave worktrees behind — they consume disk space and cause confusion.

Execution Modes

Sequential (safe):

/execute-outcome BHU-139 --sequential

Runs all Work Units one by one, no parallelism.

Parallel (fast):

/execute-outcome BHU-139 --parallel

Maximum parallelism based on dependency graph.

Default: Ask about dependencies, then optimize.

Progress Tracking

During execution, maintain state:

Outcome: BHU-139
Started: 2026-01-21 12:30
Base branch: feature/land-valuation

Batch 1/2 (parallel):
  Worktrees: .worktrees/wu-BHU-141, .worktrees/wu-BHU-143
  - [x] BHU-141: APPROVED → merged ✓
  - [x] BHU-143: APPROVED → merged ✓
  Worktrees cleaned up ✓

Batch 2/2 (sequential):
  - [~] BHU-142: IN PROGRESS...

Active worktrees: 0
Elapsed: 7 min

Worktree Status Commands

To inspect state during execution:

# List all worktrees
git worktree list

# Check branch status in a worktree
git -C .worktrees/wu-BHU-141 status

# View commits made in worktree
git -C .worktrees/wu-BHU-141 log --oneline -5