---
name: step-03-commit
description: Commit changes, update prd.json and progress.txt
next_step: steps/step-04-check.md
---

# Step 3: Commit Changes

## YOUR TASK:

Commit the changes from the executed task, update prd.json and progress.txt.

---

## EXECUTION SEQUENCE:

### 1. Stage Changes

**Add modified files:**

```bash
git add {files_created} {files_modified}
```

**Verify staged changes:**

```bash
git status
```

### 2. Create Commit

**Commit with descriptive message:**

```bash
git commit -m "$(cat <<'EOF'
feat(ralph): {current_task_description}

Task {current_task_id}/{tasks_total} - Iteration {current_iteration}

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
EOF
)"
```

**Commit message format:**
- Type: `feat`, `fix`, `refactor`, `test`, `docs`
- Scope: `ralph` or specific module
- Description: Task description
- Footer: Iteration info

### 3. Update prd.json

**Mark current task as complete:**

```json
{
  "feature": "{task_description}",
  "current_iteration": {current_iteration + 1},
  "tasks": [
    { "id": 1, "description": "...", "passes": true },   // was false
    { "id": 2, "description": "...", "passes": false }   // next task
  ]
}
```

**Write updated prd.json:**

```javascript
const prd = readJSON('.ralph/prd.json');
const task = prd.tasks.find(t => t.id === currentTaskId);
task.passes = true;
prd.current_iteration++;
writeJSON('.ralph/prd.json', prd);
```

### 4. Update progress.txt

**Append learnings to progress.txt:**

```markdown
---

## Iteration {current_iteration}

### Task Completed
[{current_task_id}] {current_task_description}

### Files Changed
- Created: {files_created}
- Modified: {files_modified}

### Learnings
{What was learned during this task}
{Any issues encountered and how they were resolved}
{Patterns discovered that might help future tasks}

### Context for Next Task
{What the next iteration should know}
```

### 5. Verify Commit

**Check commit was created:**

```bash
git log -1 --oneline
```

**Expected output:**
```
abc1234 feat(ralph): {current_task_description}
```

### 6. Log Activity (if verbose)

**If {verbose_mode} = true:**

Append to `.ralph/logs/{date}.log`:
```
[{timestamp}] TASK COMPLETED
  Task: [{current_task_id}] {current_task_description}
  Commit: {commit_hash}
  Files: {file_count} changed
  Iteration: {current_iteration}
```

---

## OUTPUT FORMAT:

```
Changes Committed:

| Field | Value |
|-------|-------|
| Commit | {commit_hash} |
| Task | [{current_task_id}] ✅ |
| Iteration | {current_iteration} |
| Files | {file_count} changed |

prd.json: Updated task {current_task_id} to passes: true
progress.txt: Added iteration {current_iteration} learnings

-> Checking completion...
```

---

## ERROR HANDLING:

**If commit fails (pre-commit hook):**

1. Read hook error message
2. Fix the issue (lint, format, etc.)
3. Stage fixes
4. Create NEW commit (don't amend)
5. Proceed to step-04

**If prd.json write fails:**

1. Log error
2. Retry write
3. If still fails, output error and stop

---

## NEXT STEP:

After commit and updates complete, proceed to `./step-04-check.md`
