---
name: doc-writing-for-rag
effort: medium
description: "Writes high-density reference documentation optimized for RAG indexing. Uses compact templates, minimal frontmatter, cross-references to schemas.md/errors.md (paths from `paths.api_schemas`/`paths.api_errors` in `baldart.config.yml`). Load this skill when creating or rewriting files in `${paths.references_dir}`, `${paths.prd_dir}`, or when you hear 'endpoint template', 'compact docs', 'doc for RAG', 'dense documentation', 'signal/noise ratio'."
---

# Doc Writing for RAG

Writing protocol for reference docs optimized for LightRAG indexing. Validated on 45 files across 3 compression waves (−48% average lines, signal/noise from 45% to 80%+).

## Project Context

**Reads from `baldart.config.yml`:** `paths.references_dir`, `paths.api_schemas`, `paths.api_errors`, `paths.prd_dir`.
**Gated by features:** `features.has_api_docs` (schemas/errors workflow active when `true`; otherwise the skill skips schemas.md / errors.md cross-references and writes self-contained endpoint docs).
**Overlay:** loads `.baldart/overlays/doc-writing-for-rag.md` if present — project-specific domain list, schema naming conventions, frontmatter extensions.
**On missing/empty keys:** ask the user; do not assume defaults. See `framework/agents/project-context.md` § 3.

## Effort

**Baseline:** `effort: medium` (frontmatter). **Inline override:** pass
`effort=<low|medium|high|xhigh|max>` anywhere in the invocation to scale
reasoning depth for this run — detect it once at kickoff and strip the token
before consuming user input. Level→behavior mapping, parsing contract, and
precedence caveats: `framework/agents/effort-protocol.md`.


## When to Use

Load this skill when:

- **New reference doc** to write (e.g. new API domain, UI page, collection)
- **Major rewrite** of an existing file >1500 lines or with low signal/noise ratio
- **New API endpoint** to document in an existing file
- **Extending** `schemas.md` or `errors.md` with new schemas/codes

Do NOT load for:
- Incremental review of existing files (use `doc-reviewer-support` if installed — see Related Skills)
- Writing ADRs (different format, already dense — see writing-guide)
- PRD discovery/ideation (use the `prd` skill)
- Business/marketing copy (use the `copywriting` skill)

## Core Principles

1. **Cross-reference over repetition**: one concept explained ONCE, linked elsewhere
2. **Tables > prose** for structured information (endpoint params, error codes, schemas)
3. **Minimal frontmatter**: 4 fields (doc_type, domain, canonicality, last_updated). No audit_notes, freshness_status, stale_*, owner, status (derivable from git)
4. **Central support files**: `schemas.md` for reusable JSON schemas, `errors.md` for error codes
5. **Line count targets**: API ref <1500, PRD <1500, ADR <200, index <500
6. **Descriptive but dense**: preserve ALL semantic information, compress only verbosity

## Workflow — New API Endpoint

1. **Check schemas.md** (`${paths.api_schemas}`): does the response schema already exist? If yes, reuse it. If no, define it AFTER writing the endpoint, APPENDed to the appropriate domain section. (Skip when `features.has_api_docs: false`.)

2. **Check errors.md** (`${paths.api_errors}`): do the error codes already exist in the domain section? If yes, reuse them. If no, APPEND them in the domain section. (Skip when `features.has_api_docs: false`.)

3. **Write endpoint using compact template**:
   ```markdown
   ### POST /api/v1/domain/resource

   **Auth**: `<authWrapper>`  |  **Access**: `<ROLE_A>` + `<ROLE_B>`

   **Body**:
   | Field | Type | Required | Desc |
   |-------|------|----------|------|
   | storeId | string | yes | Store UUID |
   | name | string | yes | Display name |

   **Returns**: [ResourceResponse](./schemas.md#resourceresponse)
   **Errors**: RESOURCE_NOT_FOUND, INVALID_NAME ([errors.md](../errors.md#domain-domain))
   ```

4. **Correct relative paths** (depends on file location):
   - `api/*.md` → `./schemas.md` + `../errors.md`
   - `api/booking/*.md` → `../schemas.md` + `../../errors.md`
   - `api/survey/*.md` → `../schemas.md` + `../../errors.md`

5. **Verify line count**: if the file exceeds 1500 lines → split into sub-files per domain.

## Template Snippets

### Minimal frontmatter (mandatory)

```yaml
---
doc_type: reference
domain: booking
canonicality: canonical-source
last_updated: 2026-04-05
---
```

Other fields (owner, status, audit_notes, freshness_status, stale_*) are **derivable** from git blame / tooling → **do not write them**.

### Compact endpoint (mandatory)

```markdown
### VERB /path

**Auth**: hook  |  **Access**: roles

**Body** / **Query** / **Params**: 4-column table

**Returns**: [Schema](schemas#anchor)
**Errors**: CODE1, CODE2 ([errors.md](errors#domain))
```

### Cross-reference section (for repeated concepts)

Full explanation **once** in the file intro, then:
```markdown
See [§Store Access Control](#store-access-control) for gating details.
```

## Reference files (on-demand loading)

| Reference | When to load |
|-----------|--------------|
| `references/compact-templates.md` | Writing new endpoint/UI/PRD/collection |
| `references/schemas-and-errors.md` | Extending schemas.md or errors.md |
| `references/frontmatter-minimal.md` | Defining frontmatter for a new file |
| `references/line-count-targets.md` | File > threshold, deciding whether to split |
| `references/before-after-examples.md` | Want concrete Wave 1+2+3 examples |

## Related Skills

- `doc-reviewer-support` (OPTIONAL — not shipped with the framework): review checklists, invariant tables, navigation audit. If present, use its format; if absent, proceed without it and perform review inline.
- `prd`: PRD discovery & ideation (different scope)
- `copywriting`: marketing/UX copy
