docs-sync git:20260514.482b8ceA

Immutable. This exact content is served forever at /api/v1/blob/eda9822766e99d2b.

---
name: docs-sync
description: Before staging a commit in the cgg repo, verify that user-visible surface changes (CLI flags, output formats, supported languages, resolver behavior, performance numbers) are reflected in README.md, the embedded mermaid graphs, the SKILL.md files under skills/, and any benchmark scripts. Trigger when about to `git commit` or open a PR, or after editing crates/cgg/src/cli.rs, crates/cgg-lang/src/plugins.rs, crates/cgg-resolve/**, scripts/benchmark.sh, or any flag/help-text/output-format code path. The pre-commit hook already regenerates the two embedded mermaid blocks via scripts/update-readme-graphs.py — this skill covers everything else: prose, flag tables, language tables, and skill copy that the hook does not touch.
---

# docs-sync — keep cgg docs honest

`cgg` ships its own contract surface: a CLI, a set of output formats,
a language matrix, a resolver pipeline, and two embedded skill files
that teach agents how to use it. When code changes, those documents
drift. This skill is the checklist for catching that drift *before*
a commit lands.

## When this skill fires

Pre-commit, or right after editing any of:

- `crates/cgg/src/cli.rs` — new/renamed flags, defaults, help text
- `crates/cgg/src/main.rs` (the `run` orchestration) — phase order,
  audit shape
- `crates/cgg-lang/src/plugins.rs` and `crates/cgg-lang/src/plugins/**`
  — language support changes
- `crates/cgg-resolve/**` — resolver behavior, FFI detection,
  confidence levels
- `crates/cgg-format/**` — output format additions or schema changes
- `scripts/benchmark.sh` — benchmark targets

Skip when: the change is internal refactoring with no user-visible
effect (private helpers, test-only code, formatting).

## What the pre-commit hook already handles

`.githooks/pre-commit` regenerates the two embedded mermaid blocks in
`README.md` (between `<!-- cgg:begin:walk -->` / `cgg:begin:lang`
markers) by running the freshly built `cgg` and piping through
`scripts/update-readme-graphs.py`. **Don't hand-edit those blocks.**

This skill covers everything *outside* those markers.

## The checklist

Run these checks against your staged diff. Each row is "if the diff
touches X, verify Y."

| If you changed… | Verify… |
|---|---|
| A CLI flag (added/removed/renamed/default changed) | The flag table in `README.md` ("## CLI") matches `cgg --help`. The recipe sections in `skills/cgg/SKILL.md` still reference real flags. |
| Help text / flag descriptions | `cgg --help` output is what you intended; quoted examples in README and SKILL.md still parse. |
| An output format (added, schema changed) | The "Output formats" table in both `README.md` and `skills/cgg/SKILL.md` lists it with the right use case. |
| Language plugin added/removed | The "Supported languages" table in `README.md`, the count in the README intro ("Supported languages (N)"), and `scripts/benchmark.sh`'s `REPOS=( … )` list all agree. The `skills/cgg/SKILL.md` frontmatter description's language enumeration is accurate (or generic enough to not drift). |
| Resolver phase order or new resolver | The pipeline ASCII diagram in `README.md` ("## How it works") matches the order in `cgg::run`. `CLAUDE.md`'s "Architecture" section matches. |
| FFI detection (new attribute / language) | The FFI bullet under "## How it works" in `README.md` lists it. |
| Benchmark script (`scripts/benchmark.sh`) | Re-run `./scripts/benchmark.sh` and paste current numbers into the README benchmark table. Use `scripts/patch-readme-stats.py` if it applies. |
| Anything about caching / `.cgg-cache` | `skills/cgg/SKILL.md`'s "Performance and limits" section matches reality. |
| Audit format (`json`/`jsonl` shape) | README "## Audit / metrics" matches; SKILL.md's audit-diagnosis recipe still works. |

## Verification commands

Run these as part of the check:

```bash
# Real CLI surface — the source of truth
./target/release/cgg --help

# Count language plugins actually registered
rg -c 'plugin\.register' crates/cgg-lang/src/plugins.rs

# Benchmark targets vs language table
grep -c '^    "' scripts/benchmark.sh

# Find stale references in docs
rg --no-heading 'cgg [-]{1,2}[a-z]' README.md CLAUDE.md skills/
```

If any check turns up drift, fix the docs in the *same commit* as the
code change. A separate "docs catch-up" commit gets forgotten and the
README rots.

## Special-case: changing skills/cgg/SKILL.md itself

That file is installed into users' agent configurations by
`scripts/install-skill.sh`. Changes there ship to every user who
re-runs the installer, so:

- Keep the frontmatter `description:` accurate — agents use it to
  decide whether to invoke the skill. Drift here means the skill
  stops firing or fires on the wrong prompts.
- Don't reference CLI flags that don't exist (`cgg --help` is the
  source of truth).
- Test by running `scripts/install-skill.sh --dry-run` and reading
  the would-be output.

## What this skill does NOT do

- Does not run `cargo test` — the pre-commit hook does that.
- Does not regenerate mermaid graphs — the pre-commit hook does that.
- Does not auto-commit — surfaces the diff to fix; the human/agent
  edits and stages.
- Does not enforce style — there is no lint step beyond `cargo`'s.

The goal is "the README and SKILL.md describe what the code actually
does," not "every doc is rewritten every commit."