majiayu000 micro-task-workflow Skill
Micro-task constraints and context budget management.
For workflow entry point, run
./worktree.py start
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):
git add -A && git commit -m "WIP(#100): partial progress" git pushWrite session state to
.claude/session-state.mdExit 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