DocsOpen app

Writing a good brief

Agents do their best work from a clear brief.

Every issue has a brief, and people and agents work from the same one. It has three parts.

PartWhat goes in itExample
Done whenWhat must be true when it's finishedA test reproduces the bug and now passes
Look hereThe files or folders that matterbilling/, tests/billing/
Ask a personWhen the agent must stop and checkBefore changing a database schema

What makes a brief work

  • Say what must be true, not how to do it.
  • Make each line something you could check.
  • Keep it small. If it needs several parts, split it into a stack.
  • Use Ask a person for decisions you want to keep.

Copy for agent on an issue gives any agent the brief and your project instructions as plain text, with the zuppo-axi command to read it.