Notables
A Notable is the "know this before you start" layer — temporary, repo-wide context that isn't tied to a single branch and doesn't belong in permanent docs.
Don't touch src/billing/** until PR #479 lands.
What they capture
Notables hold the caveats a teammate would tell you before you dived in — the things that are true for a while and then aren't:
- A migration in progress ("payments is moving to the v2 SDK; don't touch
src/billing/**until PR #479 lands"). - A deprecated pattern ("stop adding to the old event bus; the new one is in
src/events/"). - A flaky test ("
checkout.e2eis intermittently red; a retry is not a real failure"). - A security-sensitive area ("changes under
src/auth/**need a second reviewer").
Each defaults to about a 7-day expiry — long enough to outlast a migration or a sprint, short enough that it disappears once it stops being true.
Category and severity
A Notable is classified so agents can filter and weigh it. Category says what
kind of signal it is — migration, deprecation,
security, flaky-test, and so on. Severity
says how much it should weigh on planning, from low to
critical. A critical security Notable is something an agent should surface
prominently; a low deprecation note is a gentle nudge.
Not a docs replacement
Notables are deliberately temporary. They are not where architecture decisions, API contracts, or runbooks live — that's your real documentation. When a Notable references durable knowledge, it links out to the real doc rather than restating it. The rule of thumb: if it will still be true in a month, it belongs in your docs; if it's a caveat for right now, it's a Notable.
A Notable can be wrong, out of date, or planted. Use it to orient — "there may be a migration here, let me check PR #479" — never as an instruction to follow blindly. Verify against the repo and the linked docs before acting.
Activity Log vs Notable
The two primitives are easy to tell apart once you see them side by side:
| Activity Log | Notable | |
|---|---|---|
| Purpose | "I'm editing this now" | "Know this before you start" |
| Lifetime | ~24 hours | ~7 days |
| Trigger | An agent starts editing | A repo-wide caveat becomes true |
| Scope | A branch and specific paths | An area or concern |
| Ends on | PR merge, branch delete, done | The caveat resolves, or expiry |