delegation-brief-authoring
verifiede3f6b6cd-1059-4d14-96ad-15a997076d01
Use when delegating work to agents or colleagues — craft briefs with machine-checkable done criteria, negative constraints, scope boundaries, and artifact expectations so acceptance is never a judgment call.
Metadata
Skill file
# Delegation Brief Authoring
**Use when** delegating work to an agent, junior dev, or colleague where the output must be machine-checkable and acceptance must not be a judgment call.
## Anatomy of a Correct Brief
Every brief MUST contain these five sections. Missing any one = the brief is incomplete.
| Section | Content | Example |
|---------|---------|---------|
| **Context (Why)** | One paragraph: the problem, why now, what unblocks | "The auth service times out after 30s under load >100 rps because connection pooling is disabled..." |
| **Scope (What)** | Exact deliverables and explicit exclusions | "Add pooling to AuthClient.java. Do NOT touch rate-limiting, do NOT add new dependencies, do NOT reformat unrelated files." |
| **Constraints** | Style, libs, must-preserve, must-not-introduce | "Keep same class name. No new deps. Max 100ms p99 added latency. Must pass existing suite." |
| **Done (Verify)** | A single shell command that returns exit 0 on success | `pytest tests/auth/test_pooling.py -x -v` |
| **Artifacts** | Exact file paths the delegate should produce/modify | "src/auth/AuthClient.java, tests/auth/test_pooling.py" |
## Negative Constraints — The "Don't" List
The most common delegation failure mode is the delegate doing extra work you didn't ask for. Prevent it explicitly:
```markdown
## Forbidden Actions
- Do NOT reformat any file outside src/auth/
- Do NOT add new dependencies to pyproject.toml
- Do NOT change the public API signature of authenticate()
- Do NOT touch database migration files
- Do NOT create documentation or README changes
```
## Making "Done" Machine-Checkable
"Done" must be a single shell command. The delegate runs it; if exit code 0, the work is accepted. If not, it isn't.
### Bad (judgment call):
> "Make the code cleaner" or "Improve performance"
### Good (machine-checkable):
```bash
pytest tests/auth/ -x --strict-markers && ruff check src/auth/ --select ALL
```
For performance work, bake a benchmark threshold:
```bash
python -m timeit -s "from src.auth import AuthClient" "AuthClient().authenticate('x')" 2>&1 | awk '/loops/{if($1<1000) exit 1}'
```
## The "Verify" Command Should
1. **Run tests**: `pytest tests/<scope>/ -x -v`
2. **Run linters**: `ruff check src/<scope>/`
3. **Check no new deps**: `git diff --stat pyproject.toml | grep -c '+'` (should be 0)
4. **Check file scope**: `git diff --stat -- ':(exclude)src/<scope>/*'` (should be empty)
## Templated Brief
```markdown
## Context
[One paragraph: why, what's broken, what it unblocks]
## Scope
[Bullet list: exactly what to change]
[Explicit list of files/dirs to touch]
## Out of Scope (DO NOT TOUCH)
- [File/dir]
- [Concern]
## Constraints
- [Style/performance/dep constraints]
## Done Command
[Single command returning exit 0]
## Artifacts
- path/to/changed/file.py
- path/to/new/test_file.py
```
## Guardrails
- Never accept work from a brief that lacks a "Done" command
- If the delegate touches files outside the Artifacts list, the brief was incomplete — fix it, don't blame them
- A brief that says what but not "what NOT to do" is a lawsuit waiting to happen
- Machine-checkable doesn't mean "no human review" — it means "no ambiguity"
## Pitfalls
| Pitfall | Fix |
|---------|-----|
| Brief says "refactor X" but doesn't exclude Y | Add explicit "Out of Scope" section |
| Done is "looks good to me" | Replace with `pytest` + `ruff` one-liner |
| Delegate reformats the world | Add "Do NOT run formatters on any file outside scope" |
| Constraints contradict each other | Test them: run the Done command before delegating |
| Too many files in scope | Split into multiple briefs, one per concern |
## Verify / Checklist
- [ ] All five sections present (Context, Scope, Constraints, Done, Artifacts)
- [ ] "Done" command actually passes on a clean branch before delegating
- [ ] Negative constraints explicitly list forbidden files/actions
- [ ] Artifacts list matches the actual files the Done command touches
- [ ] Brief is under 300 words (if longer, split it)
- [ ] Run `git diff --stat` after delegation and confirm only Artifact paths changedAttached files
No attached files.