Feedback Loops

Ralph is an autonomous agent that can run for hours or days without human intervention. This makes feedback loops absolutely critical. Without them, Ralph will accumulate broken code that compounds across iterations, eventually making the codebase unusable.

Ralph only works if there are automated quality checks. Without feedback loops, you’re flying blind.

Why Feedback Loops Matter

The Compounding Problem

Imagine Ralph completes 10 stories in a row:

Story 1 - Introduces a subtle bug (no tests catch it)
Story 2 - Builds on Story 1, inherits the bug
Story 3 - Bug causes a type error, ignored without typechecking
Story 4 - Type error breaks the build
Story 5 - Can’t even run due to broken build
Stories 6-10 - Pile more broken code on top

By Story 10, you have a mountain of broken code to untangle.

The Feedback Loop Solution

With proper feedback loops:

Story 1 - Introduces a subtle bug
Tests catch the bug - Agent fixes it before committing
Story 2 - Builds on correct code
Story 3 - Type error caught by typecheck
Agent fixes type error - Commit only happens after checks pass
Stories 4-10 - Continue on a solid foundation

Feedback loops catch problems immediately when they’re easiest to fix, not 10 iterations later when the cause is buried.

Required Feedback Loops

Ralph mandates quality checks before every commit:

1. Type Checking

Why it matters:

Catches type errors before runtime
Enforces contracts between modules
Prevents undefined errors and null pointer exceptions

How to implement:

# TypeScript
npm run typecheck  # or: tsc --noEmit

# Python
mypy src/

# Go
go build ./...

Type checking is non-negotiable. It’s the first line of defense against broken code.

2. Linting

Why it matters:

Catches common mistakes (unused variables, unreachable code)
Enforces code style consistency
Detects potential bugs (missing return statements, etc.)

How to implement:

# JavaScript/TypeScript
npm run lint  # or: eslint .

# Python
ruff check .

# Go
golangci-lint run

3. Unit Tests

Why it matters:

Verifies individual functions and modules work correctly
Catches regressions when changing existing code
Documents expected behavior

How to implement:

# JavaScript/TypeScript
npm test

# Python
pytest

# Go
go test ./...

Aim for at least 80% test coverage. The PRD can specify “Tests pass with > 80% coverage” in acceptance criteria.

4. Integration Tests

Why it matters:

Verifies components work together correctly
Catches issues at system boundaries
Tests database interactions, API calls, etc.

How to implement:

# JavaScript/TypeScript
npm run test:integration

# Python
pytest tests/integration/

# Go
go test -tags=integration ./...

5. Build Verification

Why it matters:

Ensures the project actually builds
Catches missing dependencies
Verifies deployment artifacts can be created

How to implement:

# JavaScript/TypeScript
npm run build

# Python
python -m build

# Go
go build -o bin/app ./cmd/app

Configuring Quality Checks

Edit the prompt template (prompt.md or CLAUDE.md) to specify your project’s quality checks:

## Quality Requirements

- ALL commits must pass your project's quality checks:
  - Type check: `npm run typecheck`
  - Lint: `npm run lint`
  - Unit tests: `npm test`
  - Integration tests: `npm run test:integration`
  - Build: `npm run build`
- Do NOT commit broken code
- Keep changes focused and minimal
- Follow existing code patterns

The agent reads this every iteration and runs these checks before committing.

Don’t skip quality checks to “save time.” Broken code in one iteration will waste far more time in future iterations.

Browser Verification for UI

For frontend stories, automated tests aren’t always enough. The UI might pass tests but look broken in the browser.

Amp with dev-browser Skill

If using Amp, the dev-browser skill allows the agent to verify UI changes:

## Acceptance Criteria
- Login form renders correctly
- Submit button is disabled when form is invalid
- **Verify in browser using dev-browser skill**

The agent will:

Load the dev-browser skill
Navigate to the relevant page
Interact with the UI (click buttons, fill forms, etc.)
Verify the changes work as expected
Take screenshots for the progress report

Always include “Verify in browser using dev-browser skill” in acceptance criteria for UI stories. A frontend story is NOT complete until browser verification passes.

Claude Code with MCP

Claude Code can use MCP (Model Context Protocol) servers for browser automation:

# Install a browser MCP server
npm install -g @anthropic-ai/mcp-browser

# Configure in Claude Code settings

Then include browser verification in acceptance criteria.

Manual Verification

If no browser automation is available, the prompt can instruct the agent to note that manual verification is required:

## Browser Testing (If Available)

For any story that changes UI, verify it works in the browser if you have 
browser testing tools configured.

If no browser tools are available, note in your progress report that manual 
browser verification is needed.

CI/CD Integration

For production use, integrate Ralph with your CI/CD pipeline:

GitHub Actions Example

name: Ralph Quality Checks

on:
  push:
    branches:
      - 'ralph/**'

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      
      - run: npm ci
      - run: npm run typecheck
      - run: npm run lint
      - run: npm test
      - run: npm run build
      
      - name: Comment on failure
        if: failure()
        run: |
          echo "Quality checks failed! Ralph should not have committed this."
          exit 1

CI is the ultimate feedback loop. Even if the agent’s local checks pass, CI provides an independent verification.

Pre-commit Hooks

Use pre-commit hooks as a last line of defense:

# .husky/pre-commit
#!/bin/sh
npm run typecheck
npm run lint
npm test

This prevents commits from succeeding if quality checks fail, even if the agent tries to skip them.

What Happens When Checks Fail?

The prompt template instructs the agent:

6. Run quality checks (e.g., typecheck, lint, test - use whatever your 
   project requires)
7. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]`

If checks fail:

The agent sees the error output
The agent fixes the issues
The agent re-runs the checks
Repeat until checks pass
Only then commit

The agent should NEVER commit code that doesn’t pass quality checks. The prompt explicitly prohibits this.

Common Pitfalls

1. No Tests

❌ Bad:

{
  "acceptanceCriteria": [
    "Login form renders",
    "Form submits to /api/login"
  ]
}

✅ Good:

{
  "acceptanceCriteria": [
    "Login form renders",
    "Form submits to /api/login",
    "Tests verify form validation",
    "Tests verify successful login flow"
  ]
}

2. Flaky Tests

Flaky tests (tests that randomly fail) will block Ralph indefinitely:

# Iteration 1: Test passes, story commits
# Iteration 2: Same test fails randomly, blocks progress
# Iteration 3: Agent tries to fix "broken" code that isn't actually broken

Fix flaky tests before running Ralph. They’re worse than no tests.

3. Slow Checks

If quality checks take 10 minutes to run, each iteration takes 10+ minutes:

# 10 minutes per iteration × 10 iterations = 100 minutes

Optimize your checks:

Run unit tests in parallel
Use incremental type checking
Cache dependencies in CI

4. Accepting Failures

Never let Ralph commit failing code “temporarily”: ❌ Bad practice:

## Acceptance Criteria
- Login form renders
- Tests pass (skip if tests are broken)

This defeats the entire purpose of feedback loops.

Advanced Feedback Loops

Performance Benchmarks

Include performance requirements:

{
  "acceptanceCriteria": [
    "API responds in < 100ms (p95)",
    "Page loads in < 2s (p95)"
  ]
}

Security Scans

Add security scanning to quality checks:

# Check for vulnerable dependencies
npm audit

# Static security analysis
npm run security-scan

Accessibility Checks

For UI work, verify accessibility:

# Run axe-core tests
npm run test:a11y

Debugging Feedback Loop Issues

If Ralph keeps failing quality checks:

Check the error output - What specific check is failing?
Check progress.txt - Has the agent documented the issue?
Run checks manually - Can you reproduce the failure?
Check test flakiness - Does it fail consistently?
Check test coverage - Are the tests actually testing the right thing?

Summary

Feedback loops are what make autonomous agents reliable:

Type checking catches type errors
Linting catches code quality issues
Unit tests verify functionality
Integration tests verify system behavior
Build verification ensures deployability
Browser testing verifies UI correctness
CI/CD provides independent verification

Without these loops, Ralph will produce broken code that compounds across iterations. With them, Ralph can run autonomously for hours or days, producing high-quality, tested, working code.

Invest time in setting up robust feedback loops before running Ralph. It will save you exponentially more time later.

Get Started

Core Concepts

Workflow

Skills

Guides

Feedback Loops

Feedback Loops

Why Feedback Loops Matter

The Compounding Problem

The Feedback Loop Solution

Required Feedback Loops

1. Type Checking

2. Linting

3. Unit Tests

4. Integration Tests

5. Build Verification

Configuring Quality Checks

Browser Verification for UI

Amp with dev-browser Skill

Claude Code with MCP

Manual Verification

CI/CD Integration

GitHub Actions Example

Pre-commit Hooks

What Happens When Checks Fail?

Common Pitfalls

1. No Tests

2. Flaky Tests

3. Slow Checks

4. Accepting Failures

Advanced Feedback Loops

Performance Benchmarks

Security Scans

Accessibility Checks

Debugging Feedback Loop Issues

Summary

Build docs developers (and LLMs) love

Get Started

Core Concepts

Workflow

Skills

Guides

Documentation Index

​Feedback Loops

​Why Feedback Loops Matter

​The Compounding Problem

​The Feedback Loop Solution

​Required Feedback Loops

​1. Type Checking

​2. Linting

​3. Unit Tests

​4. Integration Tests

​5. Build Verification

​Configuring Quality Checks

​Browser Verification for UI

​Amp with dev-browser Skill

​Claude Code with MCP

​Manual Verification

​CI/CD Integration

​GitHub Actions Example

​Pre-commit Hooks

​What Happens When Checks Fail?

​Common Pitfalls

​1. No Tests

​2. Flaky Tests

​3. Slow Checks

​4. Accepting Failures

​Advanced Feedback Loops

​Performance Benchmarks

​Security Scans

​Accessibility Checks

​Debugging Feedback Loop Issues

​Summary

Build docs developers (and LLMs) love

Feedback Loops

Why Feedback Loops Matter

The Compounding Problem

The Feedback Loop Solution

Required Feedback Loops

1. Type Checking

2. Linting

3. Unit Tests

4. Integration Tests

5. Build Verification

Configuring Quality Checks

Browser Verification for UI

Amp with dev-browser Skill

Claude Code with MCP

Manual Verification

CI/CD Integration

GitHub Actions Example

Pre-commit Hooks

What Happens When Checks Fail?

Common Pitfalls

1. No Tests

2. Flaky Tests

3. Slow Checks

4. Accepting Failures

Advanced Feedback Loops

Performance Benchmarks

Security Scans

Accessibility Checks

Debugging Feedback Loop Issues

Summary