---
name: step-02-execute
description: Execute task(s) with dependency checks and rich tracking
next_step: steps/step-03-commit.md
---

# Step 2: Execute Task

> **CONTEXT OPTIMIZATION:** Read ONCE (first iteration). Subsequent iterations use compact-loop.md.

## YOUR TASK:

Execute the current task from prd.json. First iteration = ONE task. After that, compact loop handles batches.

**ULTRA THINK about the implementation.**

---

## EXECUTION RULES:

1. **ATOMIC CHANGES** — Complete and working
2. **USE MCP** — Validate with SmartStack MCP (once per batch)
3. **TRACK FILES** — Record every file created or modified
4. **CHECK DEPENDENCIES** — Verify before starting
5. **BATCH ALLOWED** — Same category, max 5 tasks

---

## EXECUTION SEQUENCE:

### 1. Verify Dependencies

```javascript
const prd = readJSON('.ralph/prd.json');
const task = prd.tasks.find(t => t.id === {current_task_id});
for (const depId of task.dependencies) {
  const dep = prd.tasks.find(t => t.id === depId);
  if (!dep || dep.status !== 'completed') {
    task.status = 'blocked'; task.error = `Dependency ${depId} not completed`;
    writeJSON('.ralph/prd.json', prd);
    STOP — return to step-01
  }
}
```

### 2. Mark In-Progress

```javascript
task.status = 'in_progress';
task.started_at = new Date().toISOString();
writeJSON('.ralph/prd.json', prd);
```

### 3. Understand and Execute

**ULTRA THINK:** What needs to be done? What files? What acceptance criteria? What category?

**Read `references/category-rules.md` for category-specific execution rules.**

Key category triggers:

| Category | Special Action |
|----------|---------------|
| `infrastructure` with `_migrationMeta` | Migration sequence: MCP suggest → add → update → build |
| `infrastructure` with seed data keywords | **MANDATORY**: Read `references/core-seed-data.md` |
| `frontend` | MCP-first: scaffold_api_client → scaffold_routes → pages |
| `test` | Generate via MCP → run → fix loop → 100% pass required |
| `validation` | Clean build → full test suite → MCP validate |

### 4. Implement

- Create/modify files following SmartStack conventions
- Track: `{files_created} = []`, `{files_modified} = []`
- Use MCP tools per category (see category-rules.md)

### 5. Post-Infrastructure Build Gate (BLOCKING)

**After completing ALL infrastructure tasks (configs + migration + seed data):**

```bash
dotnet build --no-restore
```

MUST pass before proceeding to application/api/test/frontend. Fix if fails.

### 6. Validate with MCP

```
mcp__smartstack__validate_conventions: checks: ["all"]

# Category-specific:
infrastructure → mcp__smartstack__check_migrations
api            → mcp__smartstack__validate_security
frontend       → mcp__smartstack__validate_frontend_routes
test           → mcp__smartstack__analyze_test_coverage
```

If validation fails: fix → re-validate → do NOT proceed until clean.

### 7. Check Acceptance Criteria

Verify against `{current_task_criteria}`. If not met: continue working. If impossible: document in `task.error`.

### 8. Build & Test Verification (BLOCKING)

**Backend — EVERY task (domain, infra, application, api):**
```bash
dotnet build --no-restore
```
If FAIL → read error output → identify file:line → fix code → rebuild → loop until exit code 0.

**Test category tasks — MANDATORY execution:**
```bash
TEST_PROJECT="tests/$(basename $(pwd)).Tests.Unit"
dotnet build "$TEST_PROJECT" --no-restore
dotnet test "$TEST_PROJECT" --no-build --verbosity normal
```
If FAIL → analyze failing test names → fix SOURCE CODE (not tests) → rebuild → retest.
**Loop until 100% pass — NEVER proceed with failing tests.**

**Frontend tasks — MANDATORY verification:**
```bash
npm run typecheck    # TypeScript compilation — MUST exit 0
npm run lint         # ESLint — MUST exit 0
```
If FAIL → read errors → fix TSX/TS files → re-run → loop until pass.

**Error resolution cycle (ALL categories):**
1. Read the FULL error output (not just first line)
2. Identify root cause: file path + line number
3. Fix the issue in source code
4. Rebuild: `dotnet build --no-restore` or `npm run typecheck`
5. If still failing → repeat from step 1
6. **NEVER** mark task completed with failing build or tests
7. **NEVER** skip the verification — it is BLOCKING

### 9. Update Task State

```javascript
task.files_changed = { created: {files_created}, modified: {files_modified} };
task.validation = {validation_result};
if ({task_failed}) { task.status = 'failed'; task.error = '{reason}'; task.completed_at = now; }
prd.updated_at = new Date().toISOString();
writeJSON('.ralph/prd.json', prd);
```

Note: `task.status` stays `"in_progress"` until step-03 confirms commit. Only `"failed"` is set here.

---

## CONSTRAINTS:

**DO:** Implement exactly what task describes, follow patterns, validate with MCP, track files, check criteria.
**DON'T:** Implement other tasks, refactor unrelated code, add extras, skip validation.

---

## NEXT STEP:

After task executed and validated, proceed to `./step-03-commit.md`
