paqad-ai
Version:
Spec-driven development framework — AI agents that think before they type
46 lines (31 loc) • 2.84 kB
Markdown
# Documentation Sync Orchestration Rules
verified: 2026-11-02
This skill is the canonical entry point for "after my code change lands, which docs need updating?". It does not replace the per-domain skills below: it dispatches to them.
## Per-domain skills
| Domain | Delegate skill | Trigger |
| ------------- | ---------------------------- | ----------------------------------------------------------------------------------- |
| `api` | `api-doc-maintainer` | Endpoint added / removed / modified, payload changed, auth or rate-limit changed. |
| `integration` | `integration-doc-maintainer` | Event published / consumed, job changed, contract changed, fallback policy changed. |
| `module` | `canonical-doc-sync` | Module-level summary, business doc, technical doc became stale. |
| `error` | `error-catalog-maintainer` | New error code added, message changed, recovery path changed. |
| `glossary` | `glossary-maintainer` | New term, renamed term, deprecated term. |
The fast pre-filter `diff-doc-sync` runs first; only canonical doc paths it reports as stale are dispatched to the per-domain skills.
## Execution order
1. Run `diff-doc-sync` against the changed files. It returns the canonical doc set that is stale.
2. For each canonical path in the stale set, route by directory prefix:
- `docs/modules/*/api/**` → `api-doc-maintainer`
- `docs/modules/*/integration/**` → `integration-doc-maintainer`
- `docs/modules/*/error-catalog.md` → `error-catalog-maintainer`
- `docs/modules/*/index/**` and `docs/modules/*/features/**` → `canonical-doc-sync`
- `.paqad/glossary.md` (external: the project glossary, created on first use) or any path containing new domain terms → `glossary-maintainer`
3. Aggregate each delegate's `Updated Docs` and warning sections into a single report.
## Skipping a domain
Skip a domain when:
- `diff-doc-sync` reports no canonical paths in that domain are stale, AND
- the changed file list contains no implementation files known to drive that domain (e.g. no controllers means skip api).
## What this skill does NOT do
- It does not rewrite the docs itself: every actual edit is made by the delegate skill.
- It does not invent doc paths: it only routes paths returned by `diff-doc-sync`.
- It does not bypass any delegate's own escalation conditions; warnings from delegates surface in the consolidated report.
## When `target_domains` is provided
When the caller passes an explicit `target_domains` list, dispatch only to those domains' delegates. The pre-filter still runs, but its output is intersected with the requested domains.