pixelastic/ralph

Ralph

Overview

One issue, TDD, documented, reviewed, fixed, stopped. Do not commit. Do not continue to the next issue.

Working directory: $ARGUMENTS If $ARGUMENTS is empty, "this", ".", or "here" → use current working directory.

---

Step 1 — SETUP

Goal: Select the next issue and load context.

Exit criterion: Issue selected, guidance loaded, ready to implement.

Run ralph-start $ARGUMENTS and parse the JSON output:

• status: "finished" → display "All issues complete." and stop.
• status: "deadlocked" → display the message field and stop.
• status: "ready" → continue.

Read the file at the guidance path — accumulated knowledge from prior sessions.

Read the file at the issue path — the spec for this session.

Display a one-line recap of the selected issue.

---

Step 2 — RED

Goal: Write tests that fail — either because the feature doesn't exist yet, or because they demonstrate a bug.

Exit criterion: Test runs and fails.

If you have any ## Behavioral Tests from the issue:

• Read behavioral-tests.md
• Write tests in __tests__ folder, next to the file being tested.

If you have any ## Scaffolding Tests from the issue:

• Read scaffolding-tests.md
• Write tests in plans/<slug>/scaffold/<issue-filename>.bats

Run tests. If they passes immediately: tests are wrong. Rewrite them.

Do not write any production code in this step.

---

Step 3 — IMPLEMENT

Goal: Make the tests pass with minimal code, then verify the full suite.

Exit criterion: Linter clean, all tests green.

1. If a dedicated skill for your language exists, load it (zsh-writer, js-writer, skill-writer, etc)
2. Edit files inside the current git root (git-directory-root)
3. Write the simplest code that makes the tests pass. No more.
4. Refactor: remove duplication, improve names, extract helpers. Don't add behavior.
5. Lint all modified files with git-file-lint and fix any issues.
6. Run tests for all modified files using git-file-test. All tests must pass.

---

Step 4 — REVIEW & FIX

Goal: Get external feedback, apply it, verify nothing broke.

Exit criterion: All actionable feedback addressed, linter clean, tests green.

1. Run the /review skill using the Skill tool (not Bash tool)
   • Skill name: review
   • Args: ref:dirty and spec:<issue_path>
   • DO NOT use the Bash tool to run review
2. For each feedback item:
   • Actionable and in scope → fix it
   • Out of scope or not relevant → note it, will go in review-log.md (path from ralph-start output)
3. Lint all modified files with git-file-lint and fix any issues.
4. Run tests for all modified files using git-file-test. All tests must pass.

---

Step 5 — DOCUMENT

Goal: Leave full context for the next session.

Exit criterion: state.json, GUIDANCE.md (optional), COMMIT_HINT.md, and review-log.md (optional) updated.

All paths of the following files are from ralph-start output.

1. Update state.json: find the issue entry by id, set done: true, add recap — a short one-sentence summary of what was done.

2. Append to GUIDANCE.md under ## Discoveries:

   ### Issue XX — <title>
   - <non-trivial finding>
   

   Skip this step if there are no non-trivial findings.

3. Write COMMIT_HINT.md The file is free prose for the next commit message author. Cover:

   • Goal — what the issue set out to do (one sentence)
   • Done — what was actually implemented (what changed, what was skipped, any deviation)
   • Key files — the most important file-level changes (path + one-line reason)
   • Suggested type(scope) — e.g. feat(git-commit-message), chore(gitignore)

   Be specific enough that an agent can write a good commit message without re-reading the diff.

4. If review had skipped items, create or append at the end of review-log.md:

   ## Issue XX — <title>
   ### <feedback item>
   ```code block of the flagged code```
   **Problem:** <what the reviewer flagged>
   **Reason skipped:** <why it was dismissed>
   

---

Step 6 — STOP

Goal: Hand off to user.

Exit criterion: ralph-end called, session recap displayed.

• Run ralph-end $ARGUMENTS first

• Print the issue id, tldr, recap, and any discoveries logged.

Stop here. Do not commit. Do not start the next issue. Wait for the user.

---

Common Rationalizations

| Rationalization | Reality | |---|---| | "I don't need a specific skill, I know that language" | You don't know my style. Follow the standards of the skill. | | "I'll write the test after to go faster" | Tests-after prove nothing. Delete the code. Start with RED. | | "I'll do one more issue while I'm at it" | One issue. Full stop. | | "Review feedback is minor, not worth it" | Minor feedback ignored = minor bugs shipped. Fix it. | | "I don't need to read the guidance and issue files, I can start implementing" | You can't. Read both — guidance has prior discoveries; the issue has the acceptance criteria. | | "I should commit so the review has something to diff" | Do not commit. That's the user's job. | | "I should run review via the Bash tool" | Use the /review skill instead, Bash will go to the background and we need to wait for the review. |

Checklist

• [ ] Ran ralph-start, parsed output, handled finished/deadlocked
• [ ] Read guidance file and issue spec
• [ ] Declared test strategy before writing any test
• [ ] Behavioral tests written to __tests__/
• [ ] Scaffolding tests written to plans/<slug>/scaffold/, not tests/
• [ ] RED: wrote failing tests, ran them, confirmed they fail
• [ ] IMPLEMENT: minimal code, all behaviors covered
• [ ] Code written following the standards of the language skill (zsh-writer, js-writer, etc)
• [ ] Linter clean on modified files
• [ ] Tests green for modified files
• [ ] Ran /review via Skill tool and received output
• [ ] Pass ref:dirty and spec:<path> to the review skill
• [ ] Actionable feedback fixed or explicitly dismissed
• [ ] Linter + tests green for modified files after review fixes
• [ ] state.json updated with done: true + recap
• [ ] GUIDANCE.md discoveries appended (or skipped if none)
• [ ] review-log.md updated if skipped feedback exists
• [ ] Stopped — waiting for user to commit