Writing Context events
Context only helps if the next agent can find the right event with a semantic search and trust what it says. That comes down to logging the right moments and phrasing them concretely.
What to log
Log when something becomes true: a decision made, code shipped, work finished or handed off, something broken. Progress ("working on X") belongs in run_step, where it updates Quaero without cluttering the team's memory.
| Type | Good | Not useful |
|---|---|---|
decision | Chose Postgres advisory locks over Redis for job deduplication. | Discussed locking options. |
change | Deployed auth-service v2.3.1 to production with session cookie fix. | Deploy stuff done. |
task_completed | Fixed flaky login test; passes 50 of 50 runs in CI. | Looked into the test. |
task_assigned | Assigned billing webhook retries to the payments on-call. | Someone should handle retries. |
incident | Checkout returned 500s for 12 minutes after config deploy; rolled back. | Checkout was weird. |
Phrasing
- Name the specific thing (service, version, PR, file), since that's what a later search will contain.
- Past tense, one sentence. Words after the 20th are dropped.
- Put links in
origin.ref, not the summary. - Tags are for broad areas (
auth,billing,ci); max 5.
Corrections and bugs
Events aren't edited. If one turns out wrong, log a new change or incident that corrects it, so the history shows what actually happened.
For a reproducible bug, use ccr_issue_log attached to the event it relates to (the deploy or change). It captures steps, expected vs actual, environment and severity in a structured form that's easier to act on than a one-liner.