satellite-provider/.cursor/skills/monorepo-status/SKILL.md

---
name: monorepo-status
description: 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:
   ```bash
   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):
   ```bash
   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.