# MACP Task Brief Template

**Use this template for all MACP task briefs.** Workers that receive briefs not following this structure should flag it as an issue.

---

```markdown
# <Title>

**Branch:** `feat/<branch-name>`
**Repo worktree:** `~/src/<repo>-worktrees/<task-slug>`

---

## Objective

<1-2 sentences: what is being built and why>

---

## Task 1: <Component Name>

<Description of what to build>

### Requirements:
- <Specific, testable requirements>

### Key Functions/APIs:
<Code signatures or interface definitions>

### Constraints:
- <Language, dependencies, patterns to follow>

---

## Task 2: <Component Name>
<Same structure as Task 1>

---

## Tests (MANDATORY)

**Every brief MUST include a Tests section. Workers MUST write tests before or alongside implementation. Tests MUST pass before committing.**

### Test file: `tests/test_<module>.py`

### Test cases:
1. `test_<name>` — <what it verifies>
2. `test_<name>` — <what it verifies>
...

### Test runner:
```bash
python3 -m unittest discover -s tests -p 'test_*.py' -v
```

---

## Verification

1. All tests pass: `<test command>`
2. Python syntax: `python3 -c "import <module>"`
3. <Any additional verification steps>

## Ground Rules
- Python 3.10+ stdlib only (no pip dependencies)
- Commit message: `feat: <what changed>` (conventional commits)
- Push to `feat/<branch>` branch when done
```

---

## Brief Sizing Rules

| Brief Type | Max Items | Rationale |
|------------|-----------|-----------|
| **Build** (new code) | 2-3 | High cognitive load per item |
| **Fix** (surgical changes) | 5-7 | Low cognitive load, exact file/line/fix |
| **Review** | 1 | Naturally focused |
| **Test** (add tests) | 3-4 | Medium load, but well-scoped |

The key metric is **cognitive load per item**, not item count.
- Build = construction (high load)
- Fix = scalpel (low load)
- Review = naturally focused
- Test = moderate (reading existing code + writing test logic)