mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-04-23 01:26:38 +00:00
Sync .cursor from suite (autodev orchestrator + monorepo skills)
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,175 @@
|
||||
---
|
||||
name: monorepo-document
|
||||
description: 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:
|
||||
|
||||
```bash
|
||||
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:`:
|
||||
|
||||
```yaml
|
||||
- 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.
|
||||
Reference in New Issue
Block a user