Working relationship
- Push back on ideas when you have good reason to — this leads to better documentation. Cite sources and explain your reasoning when you do.
- When intent is unclear, state your interpretation and planned approach before editing.
- Never lie, guess, or make up anything.
Project context
- Format: MDX files with YAML frontmatter
- Config:
docs.jsonfor navigation, theme, and settings — refer to the docs.json schema when modifying it - Components: Mintlify components
Content strategy
- Search for existing content before adding anything new. Avoid duplication unless there is a strategic reason for it.
- Check existing patterns before introducing new ones.
- Start by making the smallest reasonable change.
- Make content evergreen: avoid temporal language like “currently” or “as of now” (see STYLE.md for details).
Editorial policies
Standing “whether/what to document” decisions that a PR diff or release notes can’t convey on their own. Check a change against these before recommending or writing docs. If a change is covered by a hold or don’t-document policy, the correct output is “no docs needed / hold” with the policy cited — not the nearest plausible edit. The team curates this list: when a review establishes a new standing policy, add a line here with a one-sentence rationale, and remove one when it no longer holds (for example, when a held feature ships). Hold until released:- Self-hosting features wait for a release. Do not publish documentation for a self-hosting or data-plane change until it ships in a released Terraform module (
terraform-aws/google/azure-braintrust-data-plane) or Helm chart (helm) version. A merge to the monorepo does not reach self-hosted customers, and self-hosting docs are never auto-implemented. - Feature-flagged behavior is not GA. If a capability is gated behind a feature flag (for example, LaunchDarkly) or is otherwise not generally available, hold the docs until it ships by default, or mark it with
<Beta feature="..." />. Never document flag-gated behavior as generally available.
- Internal-only concepts stay out of user-facing prose. Superuser or Sysadmin roles, hardcoded internal overrides, internal service names, and internal-only configuration are not user-facing. Document the behavior a customer observes, not the internal mechanism that produces it.
- Preserve deferred content as deferred. Never uncomment or surface content the docs deliberately keep commented out or hidden. Commented-out blocks are held on purpose.
changelog-entry skill’s decision rule, not here.
Writing standards
- Add alt text to all images.
- Code samples should be complete and runnable where possible.