micro-task-workflow Skill

Micro-task constraints and context budget management.

For complete workflow, see .claude/agents/orchestrator.md

When to Use This Skill

Understanding micro-task constraints
Escape hatch protocol when hitting context limits
Planning dependencies between tasks

The Problem: Context Exhaustion

Agents running out of context mid-task produce broken, incomplete work:

❌ OLD: Issue #100 "Implement Feature X"
├── Read 8 files to understand (~20% context)
├── Plan changes (~10% context)
├── Edit 4 files (~30% context)
├── Debug issues (~20% context)
├── Run tests (~15% context)
└── CONTEXT EXHAUSTED at 95% - work incomplete, uncommitted

The Solution: 50% Budget

✅ NEW: Issue #100 "Implement Feature X"
├── Micro-Task 100.1: Setup + config changes (45% context) ✓ committed
├── Micro-Task 100.2: Core implementation (45% context) ✓ committed
├── Micro-Task 100.3: Tests + documentation (45% context) ✓ committed
└── All work committed, PR ready

Micro-Task Constraints

Constraint	Limit	Rationale
File reads	≤ 5 files	Minimize exploration
File edits	≤ 3 files	Single logical change
Tool calls	≤ 80 total	~50% of context capacity
Commits	1-2	Checkpoint + final
Scope	Single concern	Complete in one session

Context Budget Breakdown

Phase	Budget	Purpose
Startup overhead	~20%	Load AGENTS.md, read issue, read source files
Productive work	~50%	Actual implementation
Safety margin	~30%	Unexpected complexity, debugging

Escape Hatch Protocol

At 60% context usage (or ~60 tool calls):

Commit current progress (even if incomplete):

bash

git add -A && git commit -m "WIP(#100): partial progress"
git push

Write session state to .claude/session-state.md
Sync beads:
bash
```
bd sync
```
Exit cleanly - do not continue until fresh session

Dependency Types

Serial micro-tasks (must run sequentially):

Same file modified by both (merge conflicts)
Output of one is input to another
Database schema changes before queries
API endpoint before frontend integration

Parallel micro-tasks (can run simultaneously):

Different files entirely
Same issue, independent concerns (e.g., tests vs docs)
Different issues with no shared files
Frontend and backend on different endpoints

Parallelization Rules

Scenario	Parallel?	Reason
Different issues, different files	Yes	No conflicts
Same issue, independent files	Yes	No conflicts
Same file modified	No	Merge conflicts
Sequential dependency	No	Output needed
Database migration + queries	No	Schema dependency

Worktree Strategy

Single worktree per issue (recommended):

All micro-tasks for issue #51 run in worktree 51-feature-name
Sequential micro-tasks commit to same branch
Squash to single commit before PR

Squash before PR: