annotations/.cursor/skills/monorepo-status/SKILL.md

name, description

name	description
monorepo-status	Read-only drift/coverage report for a monorepo. Reads `_docs/_repo-config.yaml` and compares live repo state (component commits, doc files, CI artifacts) against it. Surfaces which components have unsynced docs, missing CI coverage, unresolved questions, or structural drift. Writes nothing. Use before releases, during audits, or whenever the user asks "what's out of sync?".

Monorepo Status

Read-only. Reports drift between the live repo and _docs/_repo-config.yaml. Writes nothing — not even assumptions_log. Its only deliverable is a text report.

Preconditions (soft gates)

1. _docs/_repo-config.yaml exists — if not, redirect: "Run monorepo-discover first."
2. confirmed_by_user: true is NOT required — this skill can run on an unconfirmed config, but will flag it prominently.

Mitigations (M1–M7)

• M1/M7 This skill IS M7 — it is the drift-detection mechanism other skills invoke conceptually. It surfaces drift, never "fixes" it.
• M3 All checks are FACTUAL (file exists? commit date? referenced in config?). No interpretive work.
• M6 Assumptions footer included; but this skill does NOT append to assumptions_log in config (writes nothing).

What the report covers

Section 1: Config health

• Is confirmed_by_user: true? (If false, flag prominently — other skills won't run)
• How many entries have confirmed: false (inferred)?
• Count of unresolved: entries + their IDs
• Age of config (last_updated) — flag if > 60 days old

Section 2: Component drift

For each component in components::

1. Last commit date of component:

   git -C <path> log -1 --format=%cI   # submodule
   # or
   git log -1 --format=%cI -- <path>   # subfolder
   

2. Last commit date of primary_doc (and each secondary_docs entry):

   git log -1 --format=%cI -- <doc_path>
   

3. Flag as drift if ANY doc's last commit is older than the component's last commit by more than a threshold (default: 0 days — any ordering difference is drift, but annotate magnitude).

Section 3: CI coverage

For each component:

• Does it have files matching ci.expected_files_per_component[*].path_glob?
• Is it present in each ci.orchestration_files that's expected to include it (heuristic: check if the compose file mentions the component name or image)?
• Is it listed in ci.service_registry_doc if that file has a service table?

Mark each as complete / partial / missing and explain.

Section 4: Registry vs. config consistency

• Every component in the registry (.gitmodules, workspaces, etc.) appears in components: — flag mismatches
• Every component in components: appears in the registry — flag mismatches
• Every docs.root file cross-referenced in config exists on disk — flag missing
• Every ci.orchestration_files and ci.install_scripts exists — flag missing

Section 5: Unresolved questions

List every unresolved: entry in config with its ID and question — so the user knows what's blocking full confirmation.

Workflow

1. Read _docs/_repo-config.yaml. If missing or unparseable, STOP with a redirect to monorepo-discover.
2. Run all checks above (purely read-only).
3. Render the single summary table and supporting sections.
4. Include the assumptions footer.
5. STOP. Do not edit any file.

Report template

═══════════════════════════════════════════════════
 MONOREPO STATUS
═══════════════════════════════════════════════════

Config: _docs/_repo-config.yaml
  confirmed_by_user: <true|false>    [FLAG if false]
  last_updated: <date>               [FLAG if > 60 days]
  inferred entries: <count> of <total>
  unresolved: <count> open

═══════════════════════════════════════════════════
 Component drift
═══════════════════════════════════════════════════

Component            | Last commit | Primary doc age | Secondary docs | Status
-------------------- | ----------- | --------------- | -------------- | ------
annotations          | 2d ago      | 2d ago          | OK             | in-sync
flights              | 1d ago      | 12d ago         | 1 stale (schema)| drift
satellite-provider   | 3d ago      | N/A             | N/A            | no mapping

═══════════════════════════════════════════════════
 CI coverage
═══════════════════════════════════════════════════

Component            | CI configs | Orchestration | Service registry
-------------------- | ---------- | ------------- | ----------------
annotations          | complete   | yes           | yes
flights              | complete   | yes           | yes
satellite-provider   | missing    | no            | no

═══════════════════════════════════════════════════
 Registry vs. config
═══════════════════════════════════════════════════

In registry, not in config:    [list or "(none)"]
In config, not in registry:    [list or "(none)"]
Config-referenced docs missing: [list or "(none)"]
Config-referenced CI files missing: [list or "(none)"]

═══════════════════════════════════════════════════
 Unresolved questions
═══════════════════════════════════════════════════

- <id>: <question>
- <id>: <question>

═══════════════════════════════════════════════════
 Recommendations
═══════════════════════════════════════════════════

- Run monorepo-document for: flights (docs drift)
- Run monorepo-cicd for: satellite-provider (no CI coverage)
- Run monorepo-onboard for: satellite-provider (no mapping)
- Run monorepo-discover to refresh config (if drift is widespread or config is stale)

═══════════════════════════════════════════════════
 Assumptions used this run
═══════════════════════════════════════════════════

- Drift threshold: any ordering difference counts as drift
- CI coverage heuristic: component name or image appears in compose file
- Component last-commit measured via `git log` against the component path

Report only. No files modified.

What this skill will NEVER do

• Modify any file (including the config assumptions_log)
• Run monorepo-discover, monorepo-document, monorepo-cicd, or monorepo-onboard automatically — only recommend them
• Block on unresolved entries (it just lists them)
• Install tools

Edge cases

• Git not available / shallow clone: commit dates may be inaccurate — note in the assumptions footer.
• Config has confirmed: false but no unresolved entries: this is a sign discovery ran but the human never reviewed. Flag in Section 1.
• Component in registry but no entry in config (or vice versa): flag in Section 4 — don't guess what the mapping should be; just report the mismatch.
• Very large monorepos (100+ components): don't truncate tables; tell the user if the report will be long, offer to scope to a subset.