Patterns / Specs

Spec-first task brief

Write the goal, inputs, outputs and done-criteria down before the agent touches anything.

The problem

A one-line request like "add login" leaves the agent to guess scope, stack, edge cases and what "finished" means. It will guess confidently, and you only find the wrong guesses after it has written a lot of code.

The pattern

Before starting a task, write a short brief with a fixed shape. The agent works from the brief, not from your chat history.

• Goal: one or two sentences on the outcome, not the implementation.
• Context: where the relevant code or data lives, and what already exists.
• Inputs and outputs: what goes in, what must come out, in what format.
• Constraints: stack, style, things that must not change.
• Done when: a short list of checkable conditions (see Acceptance criteria checklist).

If you cannot fill in a section, that is the real problem to solve first. The brief is cheap to rewrite; a wrong implementation is not.

Template

# Task brief

## Goal
<One or two sentences: what should be true when this is done, and why.>

## Context
- Relevant files/dirs: <paths>
- Existing behaviour: <what happens today>
- Related decisions: <links or one-liners>

## Inputs / outputs
- Input: <shape, source, example>
- Output: <shape, destination, example>

## Constraints
- Must use: <language, framework, library versions>
- Must not change: <public APIs, schemas, files>
- Style: <conventions to follow>

## Done when
- [ ] <checkable condition 1>
- [ ] <checkable condition 2>
- [ ] All existing tests still pass

## Out of scope
- <thing the agent should not do, even if tempting>

If anything in this brief is ambiguous or contradictory, stop and ask before writing code.

When not to use it

• Throwaway exploration where you genuinely do not know the goal yet. Explore first, then write the brief.
• Trivial one-line changes where the brief would be longer than the diff.