Write a useful brief

A useful brief connects one clear question to the context needed to investigate it. Your coding agent should write it from the conversation and relevant code, rather than asking you to repeat everything.

Give the explanation a focus

Include the question, audience, scope, and useful repository-relative paths or symbols. Add findings and uncertainties from your investigation, clearly distinguishing observed facts from hypotheses.

# Question
How does this queue retry failed jobs without processing them twice?

# Audience
Engineers familiar with background jobs but new to this repository.

# Scope
Follow a job through reservation, failure, retry, and completion.
Explain the guarantees and limitations supported by the code.

# Starting points
Use the queue implementation and retry tests we discussed.

# Context to verify
We suspect the reservation token prevents stale workers from completing
retried jobs. Verify this against the code rather than assuming it.

Replace general starting points with actual paths when you know them. Avoid prescribing every animation scene unless that is part of the request.

Pass the brief to Codeclip

Save a nonempty UTF-8 Markdown file of up to 32 KiB, preferably outside the source tree:

codeclip generate /path/to/repository \
  --brief /path/to/brief.md --json --wait

The full brief becomes the explanation request and is saved with the run, so resuming retains its context. Use either --brief or --prompt, not both.

Leave out the noise

Don’t include credentials, secrets, unrelated files, or a full conversation dump. Codeclip must verify claims against repository evidence. Extra context should help it find and explain the relevant behavior, not pre-decide the answer.