---
name: execute-task
description: Implement a planned task using strict TDD methodology. Use when executing tasks with planned:true and executed:false. Reads the task plan, writes tests first, implements code, and commits.
---

# Execute Task

Implement everything described in a planned task file using strict Test-Driven Development.

## Inputs

You will receive:
- **Task file path** (inside the active initiative's tasks directory)
- **Task ID and title**
- **Already-executed tasks** (what's been built)
- **Environment variables** available in `.env`
- **Constraints** (hard rules to follow)

## Methodology — Strict TDD

Follow this cycle for every piece of functionality:

1. **Write a failing test** that describes the expected behavior
2. **Implement the minimum code** to make the test pass
3. **Refactor** if needed while keeping tests green
4. **Repeat** for the next piece of functionality

Write unit/integration tests for backend logic, component tests for UI, and Playwright e2e tests that exercise the app through a real browser.

## Workflow

### Step 1 — Read the task plan

Read the task file. Understand:
- What needs to be built (overview, acceptance criteria)
- Architecture decisions (if any)
- Constraints and out-of-scope items

### Step 2 — Understand the existing codebase

If this is not the first task:
- Explore the existing project structure
- Understand established patterns (routing, components, styling, state, data layer)
- Build on top of existing code — do NOT recreate or overwrite files unless the plan explicitly says to

### Step 3 — Implement via TDD

For each acceptance criterion:
1. Write a failing test
2. Implement the code to pass it
3. Verify the test passes
4. Move to the next criterion

For UI changes:
- Provide a polished, modern look and feel
- Ensure responsive layout
- Handle loading, error, and empty states
- Use existing component patterns and design system

### Step 4 — Verify

1. **All tests must pass** — run the full test suite
2. **The project must build cleanly** — no build errors
3. **Manual verification** — if it's a UI change, verify it looks correct
4. **Run react-doctor** — use the `react-doctor` skill (`.cursor/skills/autobuilder/react-doctor/SKILL.md`):
   ```bash
   npx -y react-doctor@latest . --verbose --diff
   ```
   Fix all errors. Target score 75+. Do NOT commit if score is below 50.

### Step 5 — Commit

```bash
git add -A && git commit -m "<NNNN>: <short description>"
```

Where `<NNNN>` is the task's 4-digit number prefix (e.g. `0007`).

Do NOT run `git push` — pushing is handled externally by the build loop.

#### Anti-phantom-completion rules (read carefully — past iterations have violated these)

A task's commit is only valid if **all** of the following hold:

1. **The commit modifies non-task files.** A commit whose diff is *only* the task .md flag flip (`executed: false → true`) is invalid. Every task must produce real changes under `src/`, `tests/`, `mcp/`, docs, etc. — never just bookkeeping. Run `git show --stat HEAD` after committing to confirm.
2. **No cross-task batching.** Do not roll the implementation for tasks B, C, D into task A's commit. Each task's commit may only touch files directly required by *that* task's acceptance criteria. If you notice a file you're about to touch belongs to a later task's scope, stop and switch to that task.
3. **Per-task verification, every time.** Run the full test suite, build, and react-doctor **after each task's commit** — not once at the end across multiple tasks. The build loop's "Final verification" line should appear in the log once per task, not once total.
4. **If a task's work is already in the tree** (e.g. a previous commit over-scoped and shipped it):
   - Do NOT just flip the flag and commit. That's the failure mode this rule exists to prevent.
   - Instead, **audit the task's acceptance criteria individually** against the actual code. For each criterion: either confirm with a new test that proves the criterion holds (commit the test) or fill the gap (commit the code + test). Either way the commit has substantive non-task-file changes.
   - If after a careful audit there is truly nothing to add, flip the flag and add a paragraph at the bottom of the task file explaining which prior commit shipped the work and which acceptance criteria you verified by inspection. The commit will still be a one-file flag flip — only acceptable in this audited-and-documented case, and only after the audit paragraph is written. Note this clearly in the commit message: `<NNNN>: already shipped by <prior-sha>, audited and confirmed`.

A summary like "All N tasks committed" is meaningless unless `git log --stat -N` shows real code in every one of the N commits. Verify before claiming completion.

## Rules

- Follow the task plan precisely — it is your specification.
- Build on existing code. Do not recreate files that already exist.
- If the task has dependencies, they should already be implemented. Use their code.
- Use the `.env` credentials for real API testing when available.
- NEVER modify task files — they are read-only to you.
- NEVER run `git push`.
