micro-task-workflow

name	micro-task-workflow
description	Micro-task development patterns with 50% context budget. Use for task decomposition, context management, escape hatch protocols, and orchestration patterns.

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):

1. Commit current progress (even if incomplete):

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

2. Write session state to .claude/session-state.md

3. Sync beads:

   bd sync
   

4. 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:

git rebase -i main           # Squash all commits
git push --force-with-lease