Generate a Ralph prompt for: [task description]
Success criteria: [how to verify]
Promise: [completion phrase]

# Task: [Clear Task Title]

## Objective
[1-2 sentence clear description of what needs to be accomplished]

## Context
[Brief background - what exists, why this is needed]

## Requirements
1. [Specific requirement 1]
2. [Specific requirement 2]
3. [Specific requirement 3]

## Success Criteria
- [ ] [Measurable criterion 1]
- [ ] [Measurable criterion 2]
- [ ] [Measurable criterion 3]

## Verification Steps
1. [How to verify criterion 1]
2. [How to verify criterion 2]
3. [How to verify criterion 3]

## TDD Approach
1. Write/identify failing tests for the requirement
2. Implement the solution
3. Run tests: `[test command]`
4. If tests fail, analyze output and fix
5. Repeat until all tests pass

## Completion
When ALL of the following are true:
- All success criteria met (checklist above)
- All tests passing
- No regressions introduced

Output: <promise>[COMPLETION_PHRASE]</promise>

## If Stuck
After multiple iterations without progress:
- Document what's blocking progress
- List approaches attempted
- Identify specific error or issue
- Do NOT output false promise - continue iterating or wait for max-iterations

## Verification Commands
```bash
# Run tests
npm test
# or
pytest tests/

# Check for errors
npm run lint
# or
ruff check .

# Verify specific functionality
curl -X GET http://localhost:3000/api/endpoint

## Example Prompts

### Example 1: Bug Fix

**Input:**
- Task: Fix authentication token refresh race condition
- Verification: Auth tests pass, no 401 errors in logs
- Promise: AUTH_FIX_COMPLETE

**Generated Prompt:**

```markdown
# Task: Fix Authentication Token Refresh Race Condition

## Objective
Fix the race condition in token refresh that causes intermittent 401 errors when multiple requests trigger refresh simultaneously.

## Context
The auth module in `src/auth/` handles JWT token refresh. When a token expires, multiple concurrent requests may all attempt to refresh, causing a race condition where some requests fail with 401.

## Requirements
1. Implement token refresh locking/queuing mechanism
2. Ensure concurrent requests wait for single refresh
3. Maintain backward compatibility with existing auth flow
4. Add tests covering concurrent refresh scenario

## Success Criteria
- [ ] All existing auth tests pass
- [ ] New concurrent refresh test passes
- [ ] No 401 errors in integration test logs
- [ ] Token refresh happens only once per expiration

## Verification Steps
1. Run auth tests: `npm test -- --grep "auth"`
2. Run concurrent refresh test: `npm test -- --grep "concurrent"`
3. Check logs for 401 after integration test
4. Verify single refresh in logs during concurrent requests

## TDD Approach
1. Write test for concurrent token refresh scenario
2. Verify test fails with current implementation
3. Implement locking mechanism
4. Run tests: `npm test`
5. If tests fail, analyze and fix
6. Repeat until all pass

## Completion
When ALL of the following are true:
- All auth tests passing (including new concurrent test)
- Integration tests show no 401 errors
- Single refresh verified in logs

Output: <promise>AUTH_FIX_COMPLETE</promise>

## If Stuck
After multiple iterations:
- Document the specific race condition behavior
- List locking approaches tried
- Identify where locks are failing
- Do NOT output false promise

# Task: Add Pagination to Users Endpoint

## Objective
Implement offset-based pagination for GET /api/users endpoint with page, limit, and total count.

## Context
The users endpoint in `src/routes/users.ts` currently returns all users. As the user base grows, this needs pagination for performance.

## Requirements
1. Accept `page` (default 1) and `limit` (default 20, max 100) query params
2. Return paginated response with metadata: { data: [], page, limit, total, totalPages }
3. Handle edge cases: invalid params, page beyond data, empty results
4. Add comprehensive tests for pagination

## Success Criteria
- [ ] GET /api/users returns paginated response
- [ ] `page` and `limit` query params work correctly
- [ ] Response includes correct metadata (total, totalPages)
- [ ] Edge cases handled gracefully
- [ ] All new pagination tests pass
- [ ] Existing user tests still pass

## Verification Steps
1. Run tests: `npm test -- --grep "users"`
2. Manual verification:
   - `curl localhost:3000/api/users?page=1&limit=10`
   - `curl localhost:3000/api/users?page=999&limit=10`
   - `curl localhost:3000/api/users?limit=200`

## TDD Approach
1. Write tests for pagination behavior
2. Verify tests fail
3. Implement pagination logic
4. Run tests: `npm test`
5. If failures, fix and retry
6. Test edge cases manually

## Completion
When ALL of the following are true:
- All pagination tests pass
- All existing user tests pass
- Manual verification shows correct behavior
- Edge cases handled (returns empty for page beyond data)

Output: <promise>PAGINATION_DONE</promise>

## If Stuck
Document:
- Which tests are failing and why
- What pagination approach was tried
- Specific error messages
- Do NOT output false promise

# Task: Convert Database Module to Async/Await

## Objective
Refactor all callback-based database operations in `src/db/` to use async/await pattern for improved readability and error handling.

## Context
The database module uses callback patterns from legacy code. Modern async/await improves code clarity and makes error handling more consistent.

## Requirements
1. Convert all callback-based functions to async/await
2. Replace callback error handling with try/catch
3. Update all callers to use await
4. Maintain identical external API behavior
5. No callback patterns remaining in db module

## Success Criteria
- [ ] All database functions use async/await
- [ ] No callback patterns in src/db/*.ts files
- [ ] All existing database tests pass
- [ ] All integration tests pass
- [ ] No TypeScript errors

## Verification Steps
1. Run tests: `npm test -- --grep "database"`
2. Search for callbacks: `grep -r "callback\|cb)" src/db/`
3. TypeScript check: `npm run typecheck`
4. Integration tests: `npm run test:integration`

## TDD Approach
1. Run all tests - ensure baseline passes
2. Convert one function at a time
3. Run tests after each conversion
4. If failures, fix before continuing
5. After all conversions, verify no callbacks remain

## Completion
When ALL of the following are true:
- All database tests passing
- grep for callbacks returns empty
- TypeScript compilation succeeds
- Integration tests pass

Output: <promise>ASYNC_REFACTOR_COMPLETE</promise>

## If Stuck
Document:
- Which function is causing issues
- The specific error or test failure
- What conversion approach was tried
- Do NOT output false promise

/ralph-wiggum:ralph-loop "[paste generated prompt]" --completion-promise "YOUR_PROMISE" --max-iterations 30