detections-semantic/.cursor/skills/monorepo-document/SKILL.md

name, description

name

description

monorepo-document

Syncs unified documentation (`_docs/*.md` and equivalent) in a monorepo after one or more components changed. Reads `_docs/_repo-config.yaml` (produced by monorepo-discover) to know which doc files each component feeds into and which cross-cutting docs own which concerns. Touches ONLY documentation files — never CI, compose, env templates, or component directories. Use when a submodule/package added/changed an API, schema, permission, event, or dependency and the unified docs need to catch up.

Monorepo Document

Propagates component changes into the unified documentation set. Strictly scoped to *.md files under docs.root (and repo.root_readme if referenced as cross-cutting).

Scope — explicit

In scope	Out of scope
_docs/*.md (primary and cross-cutting)	.env.example, docker-compose.*.yml → use monorepo-cicd
Root README.md only if _repo-config.yaml lists it as a doc target (e.g., services table)	Install scripts (ci-*.sh) → use monorepo-cicd
Docs index (_docs/README.md or similar) cross-reference tables	Component-internal docs (<component>/README.md, <component>/docs/*)
Cross-cutting docs listed in docs.cross_cutting	_docs/_repo-config.yaml itself (only monorepo-discover and monorepo-onboard write it)

If a component change requires CI/env updates too, tell the user to also run monorepo-cicd. This skill does NOT cross domains.

Preconditions (hard gates)

1. _docs/_repo-config.yaml exists.
2. Top-level confirmed_by_user: true in the config.
3. docs.root is set (non-null) in the config.
4. Components-in-scope have confirmed: true mappings, OR the user explicitly approves an inferred mapping for this run.

If any gate fails:

• Config missing → redirect: "Run monorepo-discover first."
• confirmed_by_user: false → "Please review the config and set confirmed_by_user: true."
• docs.root: null → "Config has no docs root. Run monorepo-discover to re-detect, or edit the config."
• Component inferred but not confirmed → ask user: "Mapping <component> → <doc> is inferred. Use it this run? (y/n/edit config first)"

Mitigations (same M1–M7 spirit)

• M1 Separation: this skill only syncs docs; never touches CI or config.
• M3 Factual vs. interpretive: don't guess mappings. Use config. If config has an unresolved: entry for a component in scope, SKIP it (M5) and report.
• M4 Batch questions at checkpoints: end of scope determination, end of drift check.
• M5 Skip over guess: missing/ambiguous mapping → skip and report, never pick a default.
• M6 Assumptions footer every run; append to config's assumptions_log:.
• M7 Drift detection before action: re-scan docs.root to verify config-listed docs still exist; if not, stop and ask.

Workflow

Phase 1: Drift check (M7)

Before editing anything:

1. For each component in scope, verify its primary_doc and each secondary_docs file exists on disk.
2. For each entry in docs.cross_cutting, verify the file exists.
3. If any expected file is missing → stop, ask user whether to:
   • Run monorepo-discover to refresh the config, OR
   • Skip the missing file for this run (recorded as skipped in report)

Do NOT silently create missing docs. That's onboarding territory.

Phase 2: Determine scope

If the user hasn't specified which components changed, ask:

Which components changed? (a) list them, (b) auto-detect from recent commits, (c) skip to review changes you've already made.

For auto-detect, for each component in config:

git -C <path> log --oneline -20                    # submodule
# or
git log --oneline -20 -- <path>                    # monorepo subfolder

Flag components whose recent commits touch doc-relevant concerns:

• API/route files (controllers, handlers, OpenAPI specs, route definitions)
• Schema/migration files
• Auth/permission files (attributes, middleware, policies)
• Streaming/SSE/websocket event definitions
• Public exports (index.ts, mod.rs, __init__.py)
• Component's own README if it documents API
• Environment variable additions (only impact docs if a Configuration section exists)

Present the flagged list; ask for confirmation before proceeding.

Phase 3: Classify changes per component

For each in-scope component, read recent diffs and classify changes:

Change type	Target doc concern
New/changed REST endpoint	Primary doc API section; cross-cutting arch doc if pattern changes
Schema/migration	Cross-cutting schema doc; primary doc if entity documented there
New permission/role	Cross-cutting roles/permissions doc; index permission-matrix table
New streaming/SSE event	Primary doc events section; cross-cutting arch doc
New inter-component dependency	Cross-cutting arch doc; primary doc dependencies section
New env variable (affects docs)	Primary doc Configuration section only — .env.example is out of scope

Match concerns to docs via docs.cross_cutting[].owns. If a concern has no owner, add to an in-memory unresolved list and skip it (M5) — tell the user at the end.

Phase 4: Apply edits

For each mapping (component change → target doc):

1. Read the target doc.
2. Locate the relevant section (heading match, anchor, or primary_doc_section from config).
3. Edit only that section. Preserve:
   • Heading structure and anchors (inbound links depend on them)
   • Table column widths / alignment style
   • ASCII diagrams (characters, indentation, widths)
   • Cross-reference wording style
4. Update cross-references when needed: if a renamed doc is linked elsewhere, fix links too.

Phase 5: Skip-and-report (M5)

Skip a component, don't guess, if:

• No mapping in config (the component itself isn't listed)
• Mapping tagged confirmed: false and user didn't approve it in Phase 2
• Component internally inconsistent (README asserts endpoints not in code) — surface contradiction

Each skip gets a line in the report with the reason.

Phase 6: Lint / format

Run markdown linter or formatter if the project has one (check for .markdownlintrc, prettier, or similar at repo root). Skip if none.

Phase 7: Report + assumptions footer (M6)

Output:

monorepo-document run complete.

Docs updated (N):
  - _docs/01_flights.md — added endpoint POST /flights/gps-denied-start
  - _docs/00_roles_permissions.md — added permission `FLIGHTS.GPS_DENIED.OPERATE`
  - _docs/README.md — permission-matrix row updated

Skipped (K):
  - satellite-provider: no confirmed mapping (config has unresolved entry)
  - detections-semantic: internal README references endpoints not in code — needs reconciliation

Assumptions used this run:
  - component `flights` → `_docs/02_flights.md` (user-confirmed in config)
  - roles doc = `_docs/00_roles_permissions.md` (user-confirmed cross-cutting)
  - target branch: `dev` (from conventions.work_branch)

Next step: review the diff in your editor, then commit with
`<commit_prefix> Sync docs after <components>` (or your own message).

Append to _docs/_repo-config.yaml under assumptions_log::

  - date: 2026-04-17
    skill: monorepo-document
    run_notes: "Synced <components>"
    assumptions:
      - "<list>"

What this skill will NEVER do

• Modify files inside component directories
• Edit CI files, compose files, install scripts, or env templates
• Create new doc files (that's monorepo-onboard)
• Change confirmed_by_user or any confirmed: <bool> flag
• Auto-commit or push
• Guess a mapping not in the config

Edge cases

• Component has no primary doc (UI component that spans all feature docs): if config has primary_doc: null or similar marker, iterate through docs.cross_cutting where the component is referenced. Don't invent a doc.
• Multiple components touch the same cross-cutting doc in one run: apply sequentially; after each edit re-read to get updated line numbers.
• Cosmetic-only changes (whitespace renames, internal refactors without API changes): inform user, ask whether to sync or skip.
• Large gap (doc untouched for months, component has dozens of commits): ask user which commits matter — don't reconstruct full history.