tomevault-io Writing Excellent TASKS.md for Builder RALPH Loops
Overview
When FULLSEND decides to build a tool, it spawns a RALPH loop for Builder. The quality of the TASKS.md directly determines whether the RALPH loop succeeds or fails. This skill teaches you how to write tasks that Builder's Claude Code instances can execute autonomously.
The RALPH Loop Mental Model
Each task in TASKS.md will be executed by a fresh Claude Code instance that:
- Has NO memory of previous tasks (except via STATUS.md)
- Can only see: the task description, STATUS.md context, and the codebase
- Must complete autonomously without human intervention
- Must know exactly when it's "done"
This means each task must be self-contained and verifiable.
Task Anatomy
- [ ] TASK-001: [Action Verb] [Specific Target] [Measurable Outcome]
Good Examples
- [ ] TASK-001: Research GitHub API pagination and rate limits, document findings in STATUS.md
- [ ] TASK-002: Write core github_scraper function with pagination support in tools/github_scraper.py
- [ ] TASK-003: Add rate limiting (max 30 requests/minute) to github_scraper
- [ ] TASK-004: Run smoke test with octocat/Hello-World repo and verify dict return format
- [ ] TASK-005: Git commit and register tool in Redis
Bad Examples
- [ ] TASK-001: Set up the project # Too vague - what does "set up" mean?
- [ ] TASK-002: Make it work # No specificity
- [ ] TASK-003: Handle edge cases # Which edge cases?
- [ ] TASK-004: Test thoroughly # No concrete success criteria
The 7 Rules of RALPH Tasks
Rule 1: Start with Action Verbs
Every task starts with a concrete action:
- Research - Investigate APIs, docs, patterns
- Write - Create new code/files
- Add - Extend existing code with new functionality
- Fix - Resolve a specific issue
- Run - Execute tests/commands
- Update - Modify existing content
- Commit - Git operations
Rule 2: One Logical Unit Per Task
Each task should do ONE thing. If you find yourself using "and" or "then", split the task.
Too big:
- [ ] TASK-001: Write the scraper, add error handling, and test it
Just right:
- [ ] TASK-001: Write core scraper function with basic API calls
- [ ] TASK-002: Add try/except error handling with partial result returns
- [ ] TASK-003: Run smoke test with test repo
Rule 3: Include Success Criteria
The Claude Code instance needs to know when it's done. Include verification in the task or make it implicit.
Implicit verification (code tasks):
- [ ] TASK-002: Write github_scraper in tools/github_scraper.py following Builder tool contract
(Success = file exists with correct structure)
Explicit verification:
- [ ] TASK-004: Run smoke test, verify output is {result, success, error} dict format
Rule 4: Reference Concrete Paths
Claude Code navigates by file paths. Be explicit.
Vague:
- [ ] TASK-002: Write the tool
Concrete:
- [ ] TASK-002: Write github_scraper function in tools/github_scraper.py
Rule 5: Put Research First
If the task requires understanding external APIs, docs, or patterns, make research TASK-001.
- [ ] TASK-001: Research LinkedIn API rate limits and auth flow, document in STATUS.md
- [ ] TASK-002: Write linkedin_enricher using researched approach
This puts knowledge into STATUS.md where future tasks can read it.
Rule 6: End with Commit + Register
Builder's contract requires git commit and Redis registration. Make this the final task.
- [ ] TASK-00N: Git add tools/{tool_name}.py, commit with message "Add {tool_name} tool - {description}", register in Redis with HSET tools:{tool_name}
Rule 7: 4-8 Tasks is the Sweet Spot
- < 4 tasks: Probably too coarse, each task doing too much
- 4-8 tasks: Good granularity for autonomous execution
- > 8 tasks: Consider if you're over-engineering or building multiple tools
Task Templates by Tool Type
Simple API Tool (4-5 tasks)
# Tasks
Context:
- Tool: {tool_name}
- PRD: {brief description}
- Output: tools/{tool_name}.py
- [ ] TASK-001: Research {API} endpoints, auth, rate limits - document in STATUS.md
- [ ] TASK-002: Write core {tool_name} function with API calls in tools/{tool_name}.py
- [ ] TASK-003: Add error handling with partial result returns
- [ ] TASK-004: Run smoke test with realistic inputs, verify dict return format
- [ ] TASK-005: Git commit and Redis registration
Complex Scraper Tool (6-8 tasks)
# Tasks
Context:
- Tool: {tool_name}
- PRD: {brief description}
- Output: tools/{tool_name}.py
- [ ] TASK-001: Research {target} API/page structure, identify data extraction points
- [ ] TASK-002: Write core {tool_name} function with basic scraping logic
- [ ] TASK-003: Add pagination support (handle next_page tokens or page numbers)
- [ ] TASK-004: Add rate limiting (max N requests per minute)
- [ ] TASK-005: Add retry logic for transient failures (3 retries, exponential backoff)
- [ ] TASK-006: Add error handling returning partial results on failure
- [ ] TASK-007: Run smoke test with {test_target}, verify output format
- [ ] TASK-008: Git commit and Redis registration
Multi-File Tool (7+ tasks)
# Tasks
Context:
- Tool: {tool_name}
- PRD: {brief description}
- Output: tools/{tool_name}.py + tools/{tool_name}_utils.py
- [ ] TASK-001: Research {domain} patterns, plan module structure
- [ ] TASK-002: Write utility functions in tools/{tool_name}_utils.py
- [ ] TASK-003: Write main {tool_name} function importing utilities
- [ ] TASK-004: Add configuration handling (env vars or defaults)
- [ ] TASK-005: Add error handling and logging
- [ ] TASK-006: Run unit tests on utility functions
- [ ] TASK-007: Run integration smoke test on main function
- [ ] TASK-008: Git commit all files and Redis registration
STATUS.md: The Memory Bridge
Each RALPH iteration reads STATUS.md for context. Structure it to help future tasks:
# Status
## PRD Summary
Name: github_scraper
Description: Scrape GitHub stargazers with pagination
Inputs: repo (str), limit (int, optional)
Outputs: list of {username, profile_url, email}
## Research Findings
(TASK-001 will populate this)
- GitHub API: api.github.com/repos/{owner}/{repo}/stargazers
- Rate limit: 60/hr unauthenticated, 5000/hr with token
- Pagination: Link header with next page URL
## Implementation Notes
(Tasks will add notes here as they complete)
## Files Changed
(Track what was created/modified)
Common Pitfalls
Pitfall 1: Assuming Context
Wrong: "TASK-003: Continue building the scraper" Right: "TASK-003: Add pagination to github_scraper in tools/github_scraper.py"
Each task must stand alone - the Claude Code instance doesn't remember what "continue" means.
Pitfall 2: Vague Verification
Wrong: "TASK-004: Test the tool" Right: "TASK-004: Run smoke test with repo='octocat/Hello-World', limit=5, verify returns dict with result, success, error keys"
Pitfall 3: Missing Dependencies
If TASK-003 needs info from TASK-001, make sure TASK-001 writes that info to STATUS.md.
Wrong:
- [ ] TASK-001: Research the API
- [ ] TASK-003: Implement using the API patterns # What patterns? Where are they?
Right:
- [ ] TASK-001: Research the API, document endpoints and auth in STATUS.md
- [ ] TASK-003: Implement using API patterns from STATUS.md research section
Pitfall 4: Scope Creep
Each task should take ~1 Claude Code session. If you're describing multiple features or "and then also", split the task.
Quick Reference Checklist
Before finalizing TASKS.md, verify:
- Every task starts with an action verb
- Every task references specific file paths
- Every task has clear done criteria
- Research tasks come before implementation
- Final task includes git commit + Redis registration
- Total task count is 4-8
- No task uses "continue" or assumes prior context
- STATUS.md context section matches task needs
Converted and distributed by TomeVault — claim your Tome and manage your conversions.