Docs

Documentation Sync

Purpose

Use this skill to keep durable repository knowledge in sync with the current coding session.

The sources of truth are:

1. the current conversation
2. the current git changes
3. the existing dev-docs/*.md, relevant specs/*.md, and AGENTS.md

This skill is for durable knowledge, not changelog prose.

Repository docs and specs

• dev-docs/ contains precise and exhaustive Markdown documentation for each domain or system (top-level *.md files).
• docs/ holds the Mintlify product docs site (docs.json, topical folders such as getting-started/ and telemetry/, plus images/, logo/, favicons).
• Each domain doc file should cover how the domain or system is architected, built, designed, and structured.
• Keep domain docs organized by domain/system (for example: dev-docs/reliability.md, dev-docs/evaluations.md, dev-docs/annotations.md, dev-docs/scores.md, dev-docs/issues.md, dev-docs/simulations.md, dev-docs/organizations.md, dev-docs/projects.md, dev-docs/users.md, dev-docs/settings.md, dev-docs/spans.md).
• specs/ is a temporary folder used while a feature or system is under construction.
• Each spec or PRD in specs/ should have its own Markdown file and usually include a task list to track progress.
• Specs define exactly what, how, and why to build while the feature is under construction, so temporary overlap with docs is acceptable.
• Docs should describe the intended final system after all planned phases are complete, including post-MVP phases, precisely enough to remain authoritative after the corresponding spec is deleted.
• Docs should not be written as a snapshot of the repository's currently implemented state.
• If some part of the final design is still not fully specified, docs may say that the exact detail is still pending precise definition, but they should still be framed around the final intended system.
• When working on a spec, proactively ask clarifying questions and challenge assumptions, gaps, ambiguities, and trade-offs as needed to build the best possible spec.

Spec structure

Use this structure for specs:

# Name

> **Documentation**: `dev-docs/reliability.md`, `dev-docs/evaluations.md`, ...

... (here goes the exact and precise specification and the plan)

## Tasks

> **Status legend**: `[ ] pending`, `[~] in progress`, `[x] complete`

### Phase N - ...

- [ ] **P0-1**: ...

... (here goes more tasks)

**Exit gate**:

- ... (here goes the definition of complete for this phase)

... (here goes more phases)

• Each phase should usually map to its own GitHub PR, and each task inside should be a subtask of that PR.
• When implementation stabilizes, promote durable knowledge from specs/ into dev-docs/.
• Building the related dev-docs/ pages for the current spec is recommended.
• Optionally, each phase can be linked to a Linear task if configured by the user.

When to use this skill

Use this skill automatically before finishing a task when the session introduced, removed, or clarified durable knowledge such as:

• product behavior
• domain rules or business logic
• architecture or design changes
• repository structure or ownership changes
• schema, API, storage, query, or lifecycle changes
• explicit conventions, constraints, or prohibitions agreed in the conversation

Use it when the user explicitly asks to:

• update docs
• document the changes
• sync knowledge into dev-docs/
• update AGENTS.md
• capture design, architecture, or business logic decisions

If there is no durable knowledge change, do not edit docs just to summarize work. Say that no documentation update is needed.

Workflow

1. Inspect the session first

• Read the current conversation carefully.
• Extract durable decisions, not just code edits.
• Note additions, removals, renames, behavior changes, and explicit rules.
• Use the conversation as the filter for what belongs to the current session.

If the worktree contains unrelated changes, do not document them unless the user asked you to.

2. Inspect the repository evidence

• Review git status and git diff.
• Read the changed files that carry domain or architectural meaning.
• Compare code changes against the existing docs before editing them.
• If a relevant spec exists, read the sections that define the domain language and future-state behavior.

3. Classify the knowledge

• dev-docs/: domain or system knowledge about behavior, architecture, structure, responsibilities, interfaces, lifecycle, and business logic.
• AGENTS.md: stable repo-wide rules, conventions, constraints, and prohibitions that future agents should follow across sessions.
• specs/: temporary plans. Do not move speculative or incomplete ideas into dev-docs/ unless the implementation or the conversation made them durable truth.

4. Map changes to the correct docs

• Prefer updating existing domain docs first.
• Update every impacted doc, not only the most obvious one.
• Delete or rewrite stale sections when behavior was removed or replaced.
• Create a new doc in dev-docs/ only when the knowledge is durable and no existing doc is a reasonable home.

5. Write future-state documentation

• Document the repository as it should now be understood after the change.
• Explain the model, responsibilities, invariants, flows, and important constraints.
• Prefer precise durable statements over implementation trivia.
• Organize by domain, not by commit chronology.
• Avoid changelog wording such as "we changed", "in this PR", "recently", or dates.