# What Causes Poor Code Generation in Ralph Iterations and How to Prevent It

> Fix poor Ralph code generation. Learn how context overflow, stale knowledge, and state issues cause problems and keep your iterations clean by mastering atomic stories and quality checks.

- Repository: [Ryan Carson/ralph](https://github.com/snarktank/ralph)
- Tags: how-to-guide
- Published: 2026-04-13

---

**Poor code generation in Ralph iterations stems from context window overflow, stale knowledge bases, and broken state management, which you prevent by keeping user stories atomic, maintaining updated [`AGENTS.md`](https://github.com/snarktank/ralph/blob/main/AGENTS.md) and [`progress.txt`](https://github.com/snarktank/ralph/blob/main/progress.txt) files, and enforcing strict quality checks on every iteration.**

Ralph, an AI-driven development workflow from the snarktank/ralph repository, launches a fresh AI instance on every iteration to complete discrete user stories. When context windows overflow or project knowledge is not persisted between runs, the generated code degrades into incomplete or inconsistent implementations. Understanding the six specific failure modes documented in the source code helps you maintain high-quality output across long-running projects.

## Six Root Causes of Poor Code Generation

Ralph works by spawning a fresh Amp or Claude Code instance for each user story, committing the change, and updating the PRD and progress log. When any pillar of this workflow breaks, the generated code degrades.

### Context Window Overflow from Oversized Stories

When **user stories are too large for a single context window**, the LLM truncates earlier parts of the prompt, loses the PRD or pattern information, and produces incomplete or wrong code. According to the [`README.md`](https://github.com/snarktank/ralph/blob/main/README.md) (lines 70-79), you must split stories into atomic tasks such as "add a DB column + migration" or "add a UI component to an existing page" rather than bundling multiple features into one story.

### Missing or Stale AGENTS.md Entries

**Reusable patterns, gotchas, and conventions** must be recorded in [`AGENTS.md`](https://github.com/snarktank/ralph/blob/main/AGENTS.md) after each iteration. As noted in the [`README.md`](https://github.com/snarktank/ralph/blob/main/README.md) (lines 85-92), when this file lacks updates, subsequent iterations lose the contextual knowledge discovered in previous runs, causing the model to repeat mistakes or ignore project-specific conventions.

### Stale progress.txt Without Codebase Patterns

The [`progress.txt`](https://github.com/snarktank/ralph/blob/main/progress.txt) file must contain a **Codebase Patterns** summary at the very top. The [`prompt.md`](https://github.com/snarktank/ralph/blob/main/prompt.md) (lines 38-47) specifies that this block is read first on every iteration; without it, the model starts without distilled patterns, causing duplicated effort and inconsistent code style.

### Branch Mismatches Between PRD and Working Tree

Ralph works on the **wrong Git branch** when state drifts between iterations. The [`ralph.sh`](https://github.com/snarktank/ralph/blob/main/ralph.sh) script (lines 42-64) archives runs when `branchName` changes and forces a branch check at step 3 of the prompt workflow. Commits on unrelated branches break CI and cause the next iteration to see a stale codebase.

### Silent Quality Check Failures

When **type-check, lint, or tests** are skipped or ignored, broken code is committed. The next iteration inherits these errors, which the model may attempt to "fix" incorrectly, spiraling into poor output. The [`prompt.md`](https://github.com/snarktank/ralph/blob/main/prompt.md) (lines 76-81) enforces a Quality Requirements block that must be satisfied before marking a story complete.

### Disabled Auto-Handoff Configuration

Without **auto-handoff**, the model's context fills up mid-task, yielding partial code. The [`README.md`](https://github.com/snarktank/ralph/blob/main/README.md) (lines 76-84) documents enabling Amp auto-handoff in `~/.config/amp/settings.json` to trigger a fresh instance when context reaches 90% capacity, preventing truncation.

## Implementation Examples

The following patterns demonstrate how to configure Ralph to avoid these failure modes.

### Splitting Oversized Stories

Before refactoring, a story in [`prd.json`](https://github.com/snarktank/ralph/blob/main/prd.json) might bundle multiple features:

```json
{
  "userStories": [
    {
      "id": "S-001",
      "title": "Build the entire dashboard with authentication, charts, and filters",
      "passes": false
    }
  ]
}

```

Break this into atomic stories that fit within one context window:

```json
{
  "userStories": [
    {
      "id": "S-001a",
      "title": "Add authentication flow",
      "passes": false
    },
    {
      "id": "S-001b",
      "title": "Create dashboard layout component",
      "passes": false
    },
    {
      "id": "S-001c",
      "title": "Add chart widgets to dashboard",
      "passes": false
    },
    {
      "id": "S-001d",
      "title": "Add filter dropdowns",
      "passes": false
    }
  ]
}

```

### Updating AGENTS.md with Reusable Patterns

After completing a UI change, append discovered patterns to [`AGENTS.md`](https://github.com/snarktank/ralph/blob/main/AGENTS.md):

```markdown

# AGENTS.md

- When adding a new dropdown component, always import the shared `Dropdown` wrapper from `components/ui/Dropdown.tsx`.
- Remember to update `src/routes.ts` to include the new route in the navigation menu.

```

Save this file before committing so the next iteration reads these conventions automatically.

### Maintaining Codebase Patterns in progress.txt

Place the **Codebase Patterns** block at the top of [`progress.txt`](https://github.com/snarktank/ralph/blob/main/progress.txt) as specified in [`prompt.md`](https://github.com/snarktank/ralph/blob/main/prompt.md) (lines 38-47):

```markdown

## Codebase Patterns

- Use `sql<number>` template for aggregations
- Use `IF NOT EXISTS` in all migration scripts
- Export types from `actions.ts` for UI consumption

```

This ensures the AI reads distilled patterns first on every iteration.

### Configuring Amp Auto-Handoff

Prevent context overflow by adding this configuration to `~/.config/amp/settings.json` as described in the [`README.md`](https://github.com/snarktank/ralph/blob/main/README.md) (lines 76-84):

```json
{
  "amp.experimental.autoHandoff": { "context": 90 }
}

```

When the LLM's context reaches 90% of its limit, Amp hands off remaining work to a fresh instance, keeping generation focused.

## Summary

Poor code generation in Ralph iterations occurs when AI instances lose context or inherit broken states. To maintain high-quality output:

- Keep **user stories small and atomic** to fit within context windows ([`README.md`](https://github.com/snarktank/ralph/blob/main/README.md) lines 70-79)
- Update **[`AGENTS.md`](https://github.com/snarktank/ralph/blob/main/AGENTS.md)** with genuine reusable learnings after every iteration ([`README.md`](https://github.com/snarktank/ralph/blob/main/README.md) lines 85-92)
- Maintain the **Codebase Patterns** block at the top of [`progress.txt`](https://github.com/snarktank/ralph/blob/main/progress.txt) ([`prompt.md`](https://github.com/snarktank/ralph/blob/main/prompt.md) lines 38-47)
- Verify **branch alignment** before each run, enforced by [`ralph.sh`](https://github.com/snarktank/ralph/blob/main/ralph.sh) ([`ralph.sh`](https://github.com/snarktank/ralph/blob/main/ralph.sh) lines 42-64)
- Run all **quality checks** (types, lint, tests) before committing ([`prompt.md`](https://github.com/snarktank/ralph/blob/main/prompt.md) lines 76-81)
- Enable **auto-handoff** in Amp settings to prevent context truncation ([`README.md`](https://github.com/snarktank/ralph/blob/main/README.md) lines 76-84)

## Frequently Asked Questions

### What causes incomplete code in Ralph iterations?

Incomplete code occurs when user stories exceed the LLM's context window, causing early prompt truncation, or when auto-handoff is disabled and the model stops mid-task. According to [`prompt.md`](https://github.com/snarktank/ralph/blob/main/prompt.md) (lines 38-47), maintaining a concise Codebase Patterns block and splitting stories atomically prevents this truncation.

### How large should a user story be for Ralph?

User stories must be small enough to complete within a single context window. As documented in the [`README.md`](https://github.com/snarktank/ralph/blob/main/README.md) (lines 70-79), atomic tasks like "add a DB column + migration" or "add a UI component to an existing page" work best, while bundled features like "build entire dashboard" cause poor generation.

### Why does Ralph forget patterns between runs?

Ralph launches a **fresh AI instance on every iteration**, so it has no memory of previous runs unless you persist knowledge. The [`README.md`](https://github.com/snarktank/ralph/blob/main/README.md) (lines 85-92) emphasizes that updating [`AGENTS.md`](https://github.com/snarktank/ralph/blob/main/AGENTS.md) with reusable patterns after each iteration is critical to prevent the model from repeating mistakes.

### How do I prevent branch mismatch errors in Ralph?

The [`ralph.sh`](https://github.com/snarktank/ralph/blob/main/ralph.sh) script (lines 42-64) automatically archives runs when `branchName` changes, and the prompt workflow forces a branch check at step 3. Ensure your working tree matches the PRD's target branch before starting an iteration, and let the script handle state archiving when switches occur.