Auto-Update Content

Mental model

An auto-updating document is a living, LLM-edited document anchored to your initial draft. There are two inputs and they do two different jobs.

• content is the document itself — the starting text, structure, voice, and level of detail. The LLM treats it as authoritative on day one and only edits it when relevant code changes.
• description_or_goal is the editorial brief — what the document is about, what kinds of changes warrant updates, and what structure to preserve. The LLM never sees this at registration; it enters the picture only when an update fires, and it drives both which code changes are considered relevant and how the editor revises the prose.

Two consequences fall directly out of this:

1. Registration does nothing generative. The seed content is what readers see until the next auto-update fires (typically on the next push). If you register an empty or placeholder document, that placeholder is what's live.
2. Updates are conservative diff-driven edits, not regenerations. The editor is biased toward minimal changes — it preserves the document's existing structure and voice unless the changes really require otherwise. The structure and voice you ship at registration tend to stick.

How content and description_or_goal interact

At update time the editor sees: "Here's the current document. Here's its goal. Here are the code changes deemed relevant to that goal. Make minimal edits." Nothing else.

Recommendations

1. Write the initial content as the document you want to live with. Set the structure, headings, voice, and level of detail you want preserved. If you only need a skeleton, ship a real skeleton with section headers and one sentence each — not blank text.
2. Don't use description_or_goal to ask for the document. It is not a generation prompt. "Generate a doc about X" doesn't help; "Track X — update when files in path/ change signatures" does.
3. State the sections you want — explicitly. Phrasing like "I want these sections in the doc: A, B, C" or "Preserve the four-section layout (Setup, Local Dev, Tests, Deploy)" works. The editor honors structural directives well; vague briefs let structure drift across updates.
4. Make description_or_goal operational and scoped. Spell out:
   • What this doc is about (subject and audience).
   • Which files or areas are in scope (helps narrow which code changes are considered relevant to this document).
   • What kinds of changes warrant edits vs. what to ignore (signature changes? cosmetic refactors? new tests?).
   • What structural invariants to preserve (sections, table columns, ordering).
5. Anchor in the code, not in product or business concepts. Updates only fire on code changes, and only changes tied to your goal reach the editor. If your subject is "user pain points" or "Q3 roadmap", auto-update can't help — use a static document or a human-maintained doc.
6. Pick one codebase per auto-updating document (the system enforces this). If you need cross-codebase coverage, register one document per codebase and link them via prose.
7. Expect inertia. The editor is biased toward conservative edits. If you want aggressive restructuring, say so explicitly ("when the public API is reshaped, restructure the endpoint table accordingly") — and don't be surprised if it still favors small edits.
8. Pre-stabilize before registering. Register after a meaningful version has been processed — registration requires the codebase to have completed processing, and the first update compares against the version current at registration. Registering during onboarding or right after a noisy commit can produce a noisy first update.
9. Don't rely on auto-update for things outside the diff — uncommitted state, infra outside the repo, runtime metrics, design rationale, decisions not reflected in code.
10. Re-register when the document's purpose changes. description_or_goal is the only steering signal; if the goal shifts, the LLM won't know unless you change it.
11. Treat the seeded content as a contract. A clear, well-organized seed gets better updates than a long unstructured one. Headings the LLM can target locally beat one giant flowing paragraph.

Prompting an agent

In practice, most users don't call register_content directly. They prompt an agent with something like:

When you write a prompt like this, you are giving the agent two distinct instructions that map to the two inputs:

A good prompt is therefore one whose goal clause stands on its own as a recurring editorial brief (it will be reused at every update for the lifetime of the document), and whose exploration clause gives the agent enough to seed a solid first draft.

Review-gated flow

For documents you want to ship cleanly, consider breaking registration into three steps:

1. Have the agent draft a markdown file containing the proposed content_name, content, and description_or_goal.
2. Review and edit the draft. Remember: this seed is what readers see until the next push.
3. Approve, then ask the agent to register it via register_content.

Patterns that make a goal clause durable across updates

• Name the in-scope paths or files.
• Name what to ignore.
• Name structural invariants (sections you want, table columns you want, ordering).
• Specify granularity ("one row per script", "one sentence per workflow", "include only public APIs").

Patterns that break across updates

• One-shot phrasing ("Add a section about authentication"). Once the document has the section, the LLM keeps editing it from this brief; "add" stops being meaningful.
• Time-relative phrasing ("Cover changes since last release"). The LLM has no notion of release boundaries.
• Subjective adjectives without anchors ("Make it concise and friendly"). Fine, but won't shape diff selection.

Examples

Script Version Tracker

What the agent does:

1. Walks the repo and finds every script that defines a VERSION_NUMBER constant.
2. Summarizes the scripts in 1-2 sentences.
3. Builds a markdown table | Script | VERSION_NUMBER | from the findings.
4. Calls register_content with the table and summary as content, and the goal verbatim as description_or_goal.

On the next push that touches a VERSION_NUMBER, the change is flagged as relevant; the editor preserves the table structure and updates the affected row(s).

Public REST API Surface

Database Schema Reference

Workflow Map

Feature Flag Inventory

Onboarding Runbook

Direct-API examples

These show the shape of an actual register_content call — what an agent ultimately produces from the higher-level prompts above.

Public REST API Surface

content_name: "rest-api-reference"
auto_update: true
codebase_names: ["our-backend"]

content: |
  # Public REST API Reference

  ## Authentication
  All endpoints require a Bearer token issued by /auth/login.

  ## Endpoints

  ### Users

  #### POST /v1/users
  - Body: email, name
  - Returns: 201 with id, email, name, created_at
  - Errors: 409 if email exists

  ## Versioning
  All routes are mounted under /v1. Breaking changes ship as /v2.

  ## Errors
  Standard error envelope: code, message, context.

description_or_goal: |
  Track the public v1 REST API surface defined under
  backend/app/api/routes/v1/. For each endpoint include method, path,
  request body shape, response shape, and required scopes. I want these
  sections in the doc: Authentication, Endpoints (grouped by resource),
  Versioning, Errors. Update when routes are added, removed, or their
  request/response shapes change. Ignore tests and internal helpers.

Database Schema Reference

content_name: "db-schema-reference"
auto_update: true
codebase_names: ["our-backend"]

content: |
  # Database Schema

  ## Conventions
  All timestamps are timezone-aware UTC. Primary keys are UUIDs.

  ## Tables

  ### users
  - id (uuid, pk)
  - email (text, unique, not null)
  - created_at (timestamptz, default now())

  ## Cross-Cutting Constraints
  All FKs cascade-delete to organization scope.

description_or_goal: |
  Document the production database schema for tables defined in
  packages/driver_db/database/models/. One section per table with bullet
  columns including type, nullability, default, and foreign keys. I want
  these sections at the top: Conventions, Tables, Cross-Cutting Constraints.
  Reflect added/removed tables, added/dropped columns, and column type
  changes. Ignore index-only migrations and migration script renames.

Anti-patterns

• Empty or one-line content with a long description_or_goal — registration leaves a near-empty document live until the next auto-update, and the editor has no structure to preserve.
• description_or_goal written as a generation prompt ("Write a comprehensive guide to ...") — the editor never generates from scratch; it edits.
• One-shot phrasing in the goal ("Add a section on auth", "Document the recent refactor") — the goal is reused on every update; "add" and "recent" stop making sense after the first run.
• Asking for content not in code — runtime metrics, customer feedback, product strategy, oral history.
• Cross-codebase scope — not supported for auto-updating documents. One codebase per registration.
• Re-registering on every change — names are globally unique; if you need to change the goal, remove and re-register.
• Expecting day-one polish — the first auto-update after registration is when the LLM actually engages. If your seed content is rough, it stays rough until the next push.

Pre-flight checklist before registering

• Codebase has been processed at least once.
• content is the document you'd be okay shipping as-is — structure, headings, voice in place.
• description_or_goal names the in-scope paths or files.
• description_or_goal says what kinds of changes count and what to ignore.
• description_or_goal calls out the sections you want preserved (e.g., "I want these sections in the doc: A, B, C").
• description_or_goal reads naturally as a recurring brief, not a one-shot instruction.
• The document's subject is derivable from code changes. If not, register a static document instead.