Skip to main content
progress.txt is Ralph’s memory system. Each iteration appends its learnings here, building up knowledge that persists across fresh AI instances.

​
Purpose

Ralph spawns fresh AI instances each iteration with clean context. The progress.txt file provides:
  • Historical context - What was implemented in previous iterations
  • Codebase patterns - Discovered conventions and best practices
  • Gotchas - Mistakes to avoid
  • Thread references - Links to previous Amp threads for deeper context

​
File Structure

## Codebase Patterns
[Consolidated reusable patterns]

---

## [Date/Time] - [Story ID]
Thread: https://ampcode.com/threads/$THREAD_ID
[Implementation details]
[Learnings]
---

## [Date/Time] - [Story ID]
[Next iteration's entry]
---

​
Codebase Patterns Section

This section appears at the TOP of progress.txt and should be read FIRST by each Ralph iteration.
The ## Codebase Patterns section consolidates the most important, reusable learnings: 
## Codebase Patterns
- Use `sql<number>` template for aggregations
- Always use `IF NOT EXISTS` for migrations
- Export types from actions.ts for UI components
- The evaluation panel component is located in src/components/EvaluationPanel.tsx
- Task status field uses enum: 'pending' | 'in_progress' | 'done'

​
What to Include

DO include:
  • General, reusable patterns
  • Architectural conventions (e.g., “Use X pattern for Y”)
  • Location of key components or files
  • Type definitions and enums
  • Critical gotchas that apply broadly
DON’T include:
  • Story-specific implementation details
  • Temporary debugging notes
  • Information that’s only relevant to one story

​
Progress Entry Format

Always APPEND to progress.txt. Never replace or remove existing entries.
Each iteration appends a new entry using this format: 
## [Date/Time] - [Story ID]
Thread: https://ampcode.com/threads/$AMP_CURRENT_THREAD_ID
- What was implemented
- Files changed
- **Learnings for future iterations:**
  - Patterns discovered (e.g., "this codebase uses X for Y")
  - Gotchas encountered (e.g., "don't forget to update Z when changing W")
  - Useful context (e.g., "the evaluation panel is in component X")
---

​
Entry Fields

​
Date/Time
string
required
Timestamp of when the iteration completed.Example: 2024-03-15 14:30 or Mar 15, 2024
​
Story ID
string
required
The user story ID from prd.json that was implemented.Example: US-001
​
Thread
string
required
Link to the Amp thread for this iteration (Amp only).Format: Thread: https://ampcode.com/threads/$AMP_CURRENT_THREAD_IDPurpose: Future iterations can use the read_thread tool to reference previous work.
This field is only applicable when using Ralph with Amp. Omit for Claude Code.
​
Implementation summary
markdown
required
Brief description of what was implemented and which files were changed.
​
Learnings
markdown
required
Critical section documenting discoveries for future iterations.Must include:
  • Patterns discovered
  • Gotchas encountered
  • Useful context about the codebase

​
Example Entry

## Mar 15, 2024 14:30 - US-001
Thread: https://ampcode.com/threads/abc123def456
- Added priority column to tasks table
- Created migration file: migrations/002_add_priority.sql
- Updated types in src/types/task.ts
- Files changed:
  - migrations/002_add_priority.sql (new)
  - src/types/task.ts (updated)
  - src/db/schema.ts (updated)
- **Learnings for future iterations:**
  - This codebase uses numbered migration files (001_, 002_, etc.)
  - Always use `IF NOT EXISTS` in ALTER TABLE statements
  - Type definitions are exported from src/types/ and imported by both frontend and backend
  - The task type is used in 12+ components, so changes here ripple widely
---

​
Learnings Section Guidelines

The learnings section is CRITICAL. It helps future iterations avoid repeating mistakes and understand the codebase better.

​
What Makes a Good Learning

Pattern discovered:
  • “This codebase uses sql<number> template for aggregations”
  • “All server actions return { success: boolean, data?: T, error?: string }”
  • “UI components import types from actions.ts, not directly from db/schema”
Gotcha encountered:
  • “Don’t forget to update the filter options in TaskFilters.tsx when adding new status values”
  • “The migration runner requires manual restart of dev server”
  • “Enum values must match exactly between DB schema and TypeScript types”
Useful context:
  • “The evaluation panel is in component src/components/EvaluationPanel.tsx”
  • “Task status dropdown logic is shared between TaskCard and TaskEditModal”
  • “The tasks API endpoint uses cursor-based pagination, not offset”

​
What NOT to Include

  • “I ran npm install” (not useful to future iterations)
  • “Fixed a typo in line 42” (too specific)
  • “Everything works now” (not a learning)

​
Full Example

## Codebase Patterns
- Use numbered migrations (001_, 002_, etc.) with IF NOT EXISTS
- Export types from actions.ts for UI components
- All server actions return { success, data?, error? }
- Task filtering uses URL search params (?status=high&priority=pending)
- The TaskCard component is used in both ListView and BoardView

---

## Mar 15, 2024 10:00 - US-001
Thread: https://ampcode.com/threads/abc123
- Added priority column to tasks table
- Created migration: migrations/002_add_priority.sql
- Updated task type definitions
- Files changed:
  - migrations/002_add_priority.sql (new)
  - src/types/task.ts (updated)
  - src/db/schema.ts (updated)
- **Learnings for future iterations:**
  - Migration files use numbered prefix (001_, 002_, etc.)
  - Always use `IF NOT EXISTS` in ALTER TABLE statements
  - Task type is imported in 12+ components - changes ripple widely
  - Priority enum values: 'high' | 'medium' | 'low'
---

## Mar 15, 2024 11:30 - US-002
Thread: https://ampcode.com/threads/def456
- Added priority badge to TaskCard component
- Created new PriorityBadge component in src/components/
- Added color mapping: red (high), yellow (medium), gray (low)
- Files changed:
  - src/components/PriorityBadge.tsx (new)
  - src/components/TaskCard.tsx (updated)
  - src/styles/priorities.css (new)
- **Learnings for future iterations:**
  - TaskCard is used in both ListView and BoardView - changes affect both
  - Color tokens are defined in src/styles/theme.css
  - New components should be added to src/components/index.ts for easier imports
  - Browser verification showed badge alignment issue with long task titles - fixed with flexbox
---

​
Usage in Ralph Iterations

Each Ralph iteration follows this workflow:
  1. Read progress.txt - Check the Codebase Patterns section FIRST
  2. Review recent entries - Understand what previous iterations learned
  3. Implement the story - Apply patterns and avoid gotchas
  4. Update patterns - Add new reusable patterns to Codebase Patterns section
  5. Append progress entry - Document implementation and learnings
The Codebase Patterns section should be read before starting work. It contains the most important knowledge distilled from all previous iterations.

​
Thread References (Amp Only)

When using Ralph with Amp, each entry includes a thread URL: 
Thread: https://ampcode.com/threads/$AMP_CURRENT_THREAD_ID
Future iterations can use the read_thread tool to access the full conversation from that iteration: 
// In a future iteration
await read_thread({ threadId: "abc123def456" });
This provides deeper context beyond what’s in the progress summary.