bootstrap/docs/MACP-BRIEF-TEMPLATE.md

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.

---

# <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>"

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)