---
name: chatondearu/technical-docs-sync
source: https://app.decimal.ai/s/chatondearu-technical-docs-sync@1/SKILL.md
source_sha256: e4896d98099a
---

# Technical documentation sync

## Principles

- **Source of truth**: application code, schemas, and runtime configuration actually used (including Docker Compose and Dockerfiles). Documentation only reflects them; never invent behavior.
- **Location**: user-facing technical docs live in **`doc/`** at the repository root (create it if missing). **Language: English only** for all `doc/**/*.md` files.
- **README**: keep the root README as a short overview plus **one clear link** to the doc index, e.g. `Full documentation: [doc/README.md](doc/README.md)`.

## Analysis order (efficient)

1. **Entry points**: app bootstrap, routers, CLI (`main.py`, `app/`, etc.).
2. **Public contracts**: request/response models, status codes, response content types, file formats.
3. **Deployment**: `Dockerfile`, `docker-compose.yml`, health checks, ports—values must match files, not assumptions.
4. **Environment variables**: document only what code reads (`os.getenv`, settings modules). If compose declares vars the app does not read yet, note that gap accurately (e.g. "set in Compose for future use" vs "consumed by …").
5. **Optional verification**: if the app exposes OpenAPI (`/openapi.json`), use it to align paths and schemas.

## Doc structure (adapt to project)

Prefer:

- `doc/README.md` — index and links to other pages.
- `doc/architecture.md` — components and data flow (add Mermaid only when the system is non-trivial).
- `doc/api.md` — HTTP API (methods, payloads, examples with real paths).
- `doc/deployment.md` — Docker, compose, production notes.
- `doc/configuration.md` — env vars, voice paths, feature flags.

Use **`doc/reference.md`** only for long tables or verbose material (progressive disclosure).

## Quality rules

- **`curl` examples** must use real paths, ports, and JSON fields from code.
- **Remove or update** stale sections; do not leave contradictory instructions between README and `doc/`.
- **Diff-first** (when the user provides a diff or file list): prioritize touched areas before broad rewrites.

## Relationship to AGENTS.md / internal specs

- Do not duplicate full user documentation inside agent-only specs. Prefer linking **`doc/`** from `AGENTS.md` when operators need the same facts.

## Additional material

For section templates and a longer checklist, see [reference.md](reference.md).