| name | ralph |
| description | MUST use for any non-trivial development task in restarters.net - implements iterative development with status tracking, session logging, validation, and one-task-at-a-time approach. |
Ralph Iterative Development Approach
1. Session Log (in .claude-session.md)
On start: Read .claude-session.md (gitignored local file, NOT CLAUDE.md) for the session log. If it references an active plan file, READ THAT PLAN FILE. Resume from where you left off.
During work: Update .claude-session.md after significant progress with date, status, completed items, next steps, blockers. Never write session log entries to CLAUDE.md — that file is committed to git and updating it makes open PRs go BEHIND.
Before context compaction: Update .claude-session.md with current state, uncommitted changes, running commands, exact next steps.
2. Break Down & Track
Create a status table: | # | Task | Status | Notes | with ⬜ Pending, 🔄 In Progress, ✅ Complete, ❌ Blocked. Work ONE task at a time. Update after each.
For parallel work across branches, add a Branch column. Always git branch --show-current before editing.
3. TDD for Bug Fixes
Write failing test FIRST → verify it fails → minimal fix → verify it passes. Tests written after code prove nothing.
4. Validate Before Marking Complete
Front-end: Chrome DevTools MCP. Emails: Mailhog at http://localhost:8025 (requires task docker:up-debug). Backend: task docker:test:phpunit. JS: task docker:test:jest. E2E: task docker:test:playwright.
5. Code Quality Review (before declaring done)
Check for: logic errors, security issues, performance problems, missing error handling. Verify consistency with existing patterns. No duplication — extract shared logic. Tests should test behavior, not implementation.
6. Completion Criteria
All subtasks ✅. All tests pass. Quality review done. Changes validated. No duplication introduced.
7. PRs
Format: Summary (bullets), Code Quality Review, Future Improvements, Test Plan. No AI attribution. Use gh api REST endpoints (not gh pr edit which uses broken GraphQL). Check for existing comments before updating PR body.
8. Following a Plan
Plan files in plans/active/ are the master progress tracker. Update status markers as you go. Re-read the plan after every resume/compaction — it contains steps you may have forgotten.
9. Database Migrations
Laravel migrations are the source of truth. Run with task docker:run:artisan -- migrate. For fresh installs: task docker:run:artisan -- migrate:fresh.
10. Docker Commands
Always use task commands — never docker-compose or docker exec directly.
task docker:up-core
task docker:shell
task docker:run:artisan -- <cmd>
task docker:run:bash -- "<cmd>"
task docker:test:phpunit
Now analyse the user's request and create your status table to begin work.
