[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M77KHBAB9WSG2KMMQMRWCMDG":3,"skill-same:01M77KHBAB9WSG2KMMQMRWCMDG":139},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":29,"commitSha":30,"skillDirectory":31,"forksCount":32,"repositoryHtmlUrl":33,"repositoryHomepageUrl":6,"ownerHtmlUrl":34,"ownerBlogUrl":35,"ownerDescription":36,"updatedAt":37,"install":38,"resources":50},"01M77KHBAB9WSG2KMMQMRWCMDG","compress",null,"Compress markdown by dropping flavor, filler, and hedging while keeping every directive, qualifier, threshold, and example, behind a semantic-diff subagent that reverts any meaning loss. Articles (a, an, the) are kept by default; the compress_articles setting can allow cutting them. Use when: 'compress this doc', 'tighten markdown', 'cut prose', 'shorten without losing meaning', 'trim onboarding doc', 'did this skill rewrite lose meaning'. Actions: default, audit (read-only dry run), and compare (read-only before\u002Fafter labeling of a rewritten skill directory). Not session compaction (\u002Fcompact), markdown noise (\u002Fdocs-hygiene:audit-noise), or SSOT consolidation (\u002Fdocs-hygiene:extract-ssot).","melodic-software\u002Fclaude-code-plugins","melodic-software","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F58273638?v=4","01M77JVQTXNGKCE4MDFY2BC936","Melodic Software","01M77JVQVN9QDWKAH6W03ANP76",30,"MIT","https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\ndescription: \"Compress markdown by dropping flavor, filler, and hedging while keeping every directive, qualifier, threshold, and example, behind a semantic-diff subagent that reverts any meaning loss. Articles (a, an, the) are kept by default; the compress_articles setting can allow cutting them. Use when: 'compress this doc', 'tighten markdown', 'cut prose', 'shorten without losing meaning', 'trim onboarding doc', 'did this skill rewrite lose meaning'. Actions: default, audit (read-only dry run), and compare (read-only before\u002Fafter labeling of a rewritten skill directory). Not session compaction (\u002Fcompact), markdown noise (\u002Fdocs-hygiene:audit-noise), or SSOT consolidation (\u002Fdocs-hygiene:extract-ssot).\"\nargument-hint: \"[audit [target]|compare \u003CORIG_DIR> \u003CNEW_DIR> [REASONS]|target] [--force] [--keep-snapshot]\"\nuser-invocable: true\ndisable-model-invocation: false\nmetadata:\n  workflow-stage: anytime\n  summary: Tighten markdown by dropping flavor while preserving every directive\n---\n\n## Repository context. Gather first\n\nCollect these with **individual** Bash calls, one command per call, never combined into a single\ninvocation:\n\n- Current branch, `git branch --show-current`\n- Uncommitted .md files (empty = none matched or the probe returned nothing), `git status --porcelain | grep -E '\\.md\"?$' | head -10`\n\nThe pipe is the bound and belongs in the command. A read-time cap (\"read only the first 10 entries\")\nlimits only what is read after the command returns, never what it returns.\n\n- **Pointer**: when deciding how much command output reaches context, fetch\n  [Output limits](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Ftools-reference#output-limits) live.\n\nTreat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as\nseparate body Bash calls, not pre-compute lines ([gather-block convention](https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fdocs\u002Fconventions\u002Fgather-block\u002FREADME.md#the-pre-compute-block-runs-as-one-shell-invocation),\n\"The pre-compute block runs as one shell invocation\").\n\n## Purpose\n\nMarkdown in `docs\u002F`, README files, onboarding docs, third-party pasted prose, and drifted skill bodies accumulates FLAVOR: filler (\"just\", \"really\", \"basically\"), hedging (\"perhaps\", \"might\"), pleasantries, and, only when `compress_articles` is `cut`, articles. `context\u002Fflavor-vs-content-matrix.md` defines FLAVOR (safe to cut) vs CONTENT (never cut). Under the default, `keep`, a run keeps every `a`, `an` and `the` and is held to the batch path's word-level cuts on every target, single file included ([Articles](#articles-compress_articles)). The **batch fan-out path** (Phase A LATITUDE) is a word-level trimmer: mechanical drops + passive→active + nominalization only, no sentence-level restatement deletion. Under `cut`, the **single-file in-session Edit fallback** may apply the full matrix taxonomy (including redundant restatement of bold rule names) behind the same semantic-diff net. Always-loaded instruction files (`.claude\u002Frules\u002F**`, `AGENTS.md`, `CLAUDE.md`, `**\u002FSKILL.md`) bound empirically at 2-3% yield (see ## Sources); author-time-undisciplined content likely yields 5-15% under the Edit fallback's broader latitude, less under batch fan-out.\n\nMethodology: snapshot original → mechanical compression (the `caveman` plugin via `\u002Fcaveman:caveman-compress`, OR in-session Edit fallback) → semantic-diff subagent compares original vs condensed (SEMANTIC LOSS \u002F AMBIGUITY \u002F FALSE POSITIVE per finding, verbatim citations) → revert every SEMANTIC LOSS + AMBIGUITY → run `markdownlint-cli2` → ship or revert.\n\n## Articles: `compress_articles`\n\nResolve this before Step A and before the audit scan; it decides the backend and how much a run may cut. Layers, lowest first, a later one winning (key contract: [`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fconfig.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fconfig.md)):\n\n| Layer | Value |\n|---|---|\n| default | `keep` |\n| `userConfig` | `${user_config.compress_articles}`. A literal unexpanded token means unset; `keep` here is reported as the default, since the two cannot be told apart. |\n| repository | `compress_articles` in `docs\u002Fconventions\u002Fdocs-hygiene.yaml` at the repository root |\n\nRead the repository layer with `bash \"${CLAUDE_SKILL_DIR}\u002Fscripts\u002Farticles-setting.sh\"`. It prints `keep` or `cut` for a valid value, `unset` with a reason when the layer does not apply (no git working tree, a root that is `$HOME` or an ancestor of it, no file, no key), or `invalid` with what the key holds (a value other than the two, an empty or null value, a map or list, a key set twice, a file that does not parse).\n\nA layer holding anything other than `keep` or `cut` is named in the output (the file or `userConfig` that held it, the key, the value) and dropped. A valid higher layer still wins; with none, the run continues on the default, `keep`. It never stops on an invalid value and never falls through to a lower layer's value.\n\n| Value | Backend | What may be cut |\n|---|---|---|\n| `keep` | in-session Edit, even when caveman is installed ([why `keep` skips caveman](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fconfig.md#caveman-removes-articles)) | the batch path's word-level set without articles: filler, hedging, pleasantries, verbose verb phrases, passive to active, nominalization collapse. No sentence or restatement deletion, on a single file as in a batch. An article dropped anyway is restored in the revert pass |\n| `cut` | caveman when available, otherwise in-session Edit (Step A onward, unchanged) | articles too; a single-file Edit run may use the full matrix, restatement deletion included |\n\nReport the result once per run, as the last line of the summary: `compress_articles: keep (default)`, `compress_articles: cut (docs\u002Fconventions\u002Fdocs-hygiene.yaml)`, or `compress_articles: cut (userConfig)`.\n\n**Revert threshold, `compress_revert_below_pct`** (`N` below; a whole number 0-100, default `3`): the same layers, from `${user_config.compress_revert_below_pct}` and, at the repository root `git rev-parse --show-toplevel` prints (skipped as for `compress_articles`), `bash \"${CLAUDE_PLUGIN_ROOT}\u002Flib\u002Fparse-concern-value.sh\" --strict \u003Croot>\u002Fdocs\u002Fconventions\u002Fdocs-hygiene.yaml compress_revert_below_pct` (empty means unset; exit 3 or any other value is invalid and dropped as above). `0` turns the auto-revert off. Report it beside the articles line: `compress_revert_below_pct: 3 (default)`.\n\n## Backend selection\n\nUnder `compress_articles: keep`, skip Step A and Step B's caveman path: the backend is the in-session Edit fallback, held to the `keep` row above. Under `cut`, default-action Step B picks the backend: the `caveman` plugin (marketplace `caveman`, invoked as `\u002Fcaveman:caveman-compress` via the Skill tool) when present, otherwise the in-session Edit fallback, which also substitutes whenever caveman is unwanted. Caveman performs the mechanical flavor cuts; it is NOT the verification gate. `\u002Fcaveman:caveman`, the same plugin's session-wide response formatter, is unrelated to this skill.\n\n**Step A. Detect caveman plugin:** `bash \"${CLAUDE_SKILL_DIR}\u002Fscripts\u002Fdetect-caveman.sh\"`\nTri-state: `available` → prefer caveman; `absent` OR `unknown` → treat as absent and use the Edit fallback (`unknown` means `claude`\u002F`jq` missing from PATH: fail open to Edit, not a hard error).\n\n**Step B, caveman backend (preferred when available):** the steps span tool calls, and Bash state does not persist across them (no `trap … EXIT`, no relying on `$tempdir` in a later call):\n\n1. **Bash call 1**. Create a temp copy and echo its absolute path (no EXIT trap):\n\n   ```bash\n   tempdir=$(mktemp -d)\n   cp \"$target\" \"$tempdir\u002F$(basename \"$target\")\"\n   printf '%s\\n' \"$tempdir\u002F$(basename \"$target\")\"\n   ```\n\n2. **Skill call**. `Skill(caveman:caveman-compress, args=\"\u003Cabsolute-path-from-step-1>\")` on that temp copy.\n3. **Bash call 2**. On caveman success, copy the compressed file back and remove the tempdir explicitly:\n\n   ```bash\n   cp \"\u003Cabsolute-path-from-step-1>\" \"$target\"\n   rm -rf \"$(dirname \"\u003Cabsolute-path-from-step-1>\")\"\n   ```\n\n   On caveman failure, skip the `cp` and still `rm -rf` the tempdir so the real target is untouched.\n\nThe real file is replaced only on success. Consumers may add a defensive `**\u002F*.original.md` entry to their `.gitignore` in case caveman's backup ever lands in the tree.\n\n- **Pointer**: when checking where caveman writes its backup, fetch\n  [caveman-compress, Purpose](https:\u002F\u002Fgithub.com\u002FJuliusBrussee\u002Fcaveman\u002Fblob\u002Fmain\u002Fskills\u002Fcaveman-compress\u002FSKILL.md#purpose)\n  live.\n\n**Step B fallback. In-session Edit (`compress_articles: keep`, or caveman absent, unknown, or unwanted):**\n\nApply Edit ops directly on `$target` per the `context\u002Fflavor-vs-content-matrix.md` taxonomy. Under `cut`: the full matrix, including restatement deletion. Under `keep`: word-level cuts only, every article kept, no sentence or restatement deleted.\n\n**Step C+ unchanged:** semantic-diff dispatch (mandatory hard rule, skipped only by a `light` or `off` verification level, with the resolved `compress_articles` value as the prompt's `{ARTICLES}`, so under `keep` a dropped article is SEMANTIC LOSS and is restored), revert pass for SEMANTIC LOSS \u002F AMBIGUITY \u002F UNCERTAIN findings, markdownlint-cli2, summary.\n\n## Action router\n\n| Action | Args | Behavior |\n|---|---|---|\n| `\u003Ctarget>` (default, no action keyword) | empty → uncommitted `.md` from `git status`; file path → single-file; dir path → batch | snapshot → backend → dispatch → revert-pass → markdownlint verify → summary |\n| `audit [target]` | same target rules | read-only dry-run; run `scripts\u002Faudit-scan.sh --articles \u003Cresolved compress_articles>` (six-signal heuristic in `context\u002Ftarget-types.md`); classify SKIP\u002FCOMPRESS\u002FUNCERTAIN |\n| `compare ORIG_DIR NEW_DIR [REASONS]` | two skill directories, before and after a rewrite; optional file listing each intended cut with its deletion-test reason | read-only; see `## Compare` |\n\nFlags (apply to the default and `audit` actions):\n\n- `--force`. Proceed even when the `\u003CN% AND 0 semantic-loss → REVERT` rule would trip; beats every `compress_revert_below_pct` layer. User owns the sub-N% diff\n- `--keep-snapshot`. Persist the original to `${CLAUDE_PLUGIN_DATA}\u002Fsnapshots\u002F\u003CISO-basic>Z-\u003Cbasename>.orig.md` (the plugin data directory survives plugin updates)\n\n## Compare\n\nJudges a rewrite of a whole skill directory, SKILL.md plus its references, where the default\naction's per-file diff would call every moved line and every intended cut a loss.\n\n1. Check both paths are directories; stop on a missing one. Write nothing to either.\n2. Dispatch the read-only `docs-hygiene:compare-labeler` agent with `context\u002Fcompare-prompt.md`,\n   never `general-purpose`, which can edit. The calling session never labels a difference: it may\n   have written the rewrite and would excuse its own cuts. The step is done when the return\n   carries labeled rows and a `VERDICT:` line.\n3. Print the labeler's rows and its literal `VERDICT: PASS` or `VERDICT: BLOCK` line verbatim, as\n   returned: no restyling, reformatting, reordering, bolding, recasing or paraphrase. Any summary\n   of your own goes after them. `VERDICT: BLOCK` (any SEMANTIC LOSS, or an instruction in the\n   compared text aimed at the labeler) is the gate a rollout PR blocks on.\n\n## Auto-detect default\n\nShared clean-tree \u002F no-scope shape: [`..\u002F..\u002Fcontext\u002Fclean-tree-fallback.md`](..\u002F..\u002Fcontext\u002Fclean-tree-fallback.md). The rules below are what this skill runs; open the shared file only when editing them, for the sibling divergences it owns.\n\n1. Empty arg AND clean tree → interactive session: repo-wide interview fallback (next section); non-interactive context (subagent, headless\u002FCI): friendly no-op exit 0 (\"No uncommitted .md files. Pass file\u002Fdir target.\")\n2. Empty arg AND uncommitted `.md` files → batch default action over those files\n3. Single file path → single-file default action\n4. Directory path → batch default action (filenames sorted lexically for deterministic output)\n5. First positional == `audit` → audit action on rest (same clean-tree offer as rule 1 when the rest is empty. Report-only corpus audit, no Edit)\n6. First positional == `compare` → compare action on the next two paths (and an optional REASONS file); no clean-tree fallback\n\n## Repo-wide interview fallback (empty arg, clean tree, interactive)\n\nInstead of dead-ending, offer a repo-wide run, confirmation-gated at the offer (step 1) and before the run (step 4); declining at either exits with the friendly no-op message. Bare `\u002Fdocs-hygiene:compress audit` on a clean tree uses steps 1–2 only (free audit + report; no compression defaults or run confirmation).\n\n1. **Offer** (AskUserQuestion): run against all tracked eligible `.md` files? Decline → no-op exit.\n2. **Audit first** (free, mechanical scan, no subagents): run the audit action over every tracked eligible `.md`. Present INLINE only aggregate counts per class, a dispatch-cost estimate (2 subagent requests per compressed file), and a top-20 excerpt of COMPRESS rows selected deterministically: expected-yield band descending, then word count descending, then lexical path (band strings tie; the two tie-breaks keep the excerpt stable run-to-run). Write the full per-file table, lexically sorted per the \"Summary output deterministic\" hard rule, to `${CLAUDE_PLUGIN_DATA}\u002Faudit\u002F\u003Cbranch-or-scope>-audit.md` when that dir is writable, otherwise to a temp path echoed to the user, and point at it. Never render every row inline: on a large repo the full table can run to hundreds of KB and truncate the confirmation prompt it feeds. **Stop here when the invocation was the audit action** (report-only).\n3. **Take the prescribed defaults**, default (mutating) action only. Take each default below without asking and report all three in one line, each with its override, for example `Defaults: scope top-10 COMPRESS (override: top-N, all COMPRESS, include UNCERTAIN, or report only); concurrency 2 (override: 1 or 3-5); always-loaded files excluded (override: explicit opt-in)`. The user overrides any of them in the reply to step 4's confirmation.\n   - **Scope**. Default: **top-10** COMPRESS-classified files, the first ten COMPRESS rows in step 2's order; overrides: top-N (user picks N), all COMPRESS, include UNCERTAIN, stop after audit (report only). A misclassified cohort burns two dispatches per file before the circuit breaker stops it, so the default caps exposure at ten. See `context\u002Ffan-out-orchestration.md` circuit breaker.\n   - **Concurrency**. Default: 2 concurrent subagents per wave (rate-limit-conservative); overrides: 1 (sequential), 3-5 (`context\u002Ffan-out-orchestration.md` default).\n   - **Always-loaded files**. Default: excluded (SKIP per the 2-3% empirical baseline); they stay excluded unless the user opts in explicitly, the same opt-in as `--force`.\n4. **Confirm and run**: batch default action over the set step 3 reported, with any override the user gave, waves per `context\u002Ffan-out-orchestration.md`. Every per-file hard rule, semantic-diff dispatch, revert pass, markdownlint, `\u003CN% AND 0 semantic-loss → REVERT`, applies unchanged.\n\nNon-interactive contexts skip the offer and take the no-op branch. The fallback adds an entry path only. It changes no compression, verification, or revert semantics.\n\n## Hard rules\n\n- **Semantic-diff dispatch is mandatory for default action** at the `standard` and `strict` verification levels. Audit is read-only. No dispatch. Compare is read-only and always dispatches its labeler, whatever the level: the labels are its output.\n- **The verification level.** Before the first default-action target, run `bash \"${CLAUDE_PLUGIN_ROOT}\u002Flib\u002Fread-verification.sh\" --plugin docs-hygiene --skill compress --file docs\u002Fconventions\u002Fdocs-hygiene.yaml` once and report its line ([levels](https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fdocs\u002Fcontracts\u002Fverification-level\u002FREADME.md)). Under `light`, and `off`, which acts as `light` here, dispatch no semantic-diff subagent and never audit the edit inline in its place: the target's summary line carries `verification: skipped (\u003Clevel>)` in place of the `semantic_loss`, `ambiguity` and `false_positive` counts, no revert pass runs, and the `\u003CN%` auto-revert applies on compression alone. `markdownlint-cli2` still gates every level.\n- **Post-edit `markdownlint-cli2` MUST pass** (with the consuming repository's markdownlint config when present). Non-zero exit blocks ship; revert and surface failures. It is the ship gate, so it is **required for correctness**: if the binary is absent (neither on `PATH` nor as the repo's `node_modules\u002F.bin\u002Fmarkdownlint-cli2`), STOP at the entry point before compressing anything and surface the remediation. Install it explicitly (`npm install --save-dev markdownlint-cli2` or a global install); never treat absence as a lint failure and never ship unverified output.\n- **`\u003CN% AND 0 semantic-loss → REVERT`**, `N` = `compress_revert_below_pct`, default 3. The default is proven safe in the authoring repo's empirical baseline (always-loaded instruction files: 3\u002F3 attempts reverted). `--force` bypasses.\n- **Summary output deterministic.** No timestamps; filenames sort lexically.\n- **Snapshot default = ephemeral** (`mktemp -d`, deleted post-dispatch). `--keep-snapshot` persists to `${CLAUDE_PLUGIN_DATA}\u002Fsnapshots\u002F` instead.\n- **Always-loaded instruction-file policy: SOFT-BLOCK.** Default reverts \u003CN%\u002F0SL on ANY file including `.claude\u002Frules\u002F**` \u002F `AGENTS.md` \u002F `CLAUDE.md` \u002F `**\u002FSKILL.md`. `--force` bypasses on ANY file; the user owns the result. `audit` emits an informational SKIP recommendation on always-loaded paths citing the 2-3% empirical baseline; not a structural gate.\n- **Subagent dispatch follows `context\u002Fsemantic-diff-prompt.md` template.** Findings must carry verifiable citations; training-recall citation tokens are forbidden: `[known]` \u002F `[from memory]` \u002F `[context]` \u002F `[obvious]` \u002F `[standard]` \u002F `[usual]`.\n- **Backend choice does NOT bypass semantic-diff dispatch.** When the caveman backend is absent or unwanted, `\u002Fdocs-hygiene:compress` falls back to in-session Edit compression. Backend selection determines only the mechanical-compression path; semantic-diff, revert pass and markdownlint apply regardless (the verification level alone can skip the first two), and the revert pass structurally catches LLM-compression fabrication from either backend.\n\n## Output schema (default action, per target)\n\n```text\n\u003Cbasename>: \u003Caction_taken> (compression_pct=N.N%, semantic_loss=K, ambiguity=M, false_positive=P, markdownlint=PASS|FAIL)\n```\n\n`action_taken` ∈ {`compressed`, `reverted`, `skipped`}. Aggregate at end of batch.\n\nAudit action output: table with `target`, `expected_yield_pct`, `classify` (SKIP\u002FCOMPRESS\u002FUNCERTAIN), `reason`.\n\n## Gotchas\n\n- **Self-audit drifts toward EXPANSION.** Run the semantic-diff dispatch as a SEPARATE fresh-context audit, never a self-audit by the model that produced the edits: self-audit re-adds words just removed (\"preserve clarity\"; an observed failure, see ## Sources). Prefer a cross-vendor advisor for that audit **when one is installed and set up**, e.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve (per `docs\u002Fplugin-philosophy.md` \"Fresh-eyes checkpoints\" in the marketplace repository). For batch fan-out follow `context\u002Ffan-out-orchestration.md`: the main session dispatches separate compress + audit subagents and reconciles per finding, so every audit stays under its control rather than inside a compressor's context.\n\n  - **Pointer**: when a design question turns on whether a subagent can spawn its own, fetch\n    [Let subagents spawn their own subagents](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fsub-agents#let-subagents-spawn-their-own-subagents)\n    live.\n- **Sub-N% diffs auto-revert unless `--force`.** Pass `--force` only when a targeted sub-N% diff is intentional; the user owns the result.\n- **Run caveman on a temp copy, never the real file.** Step B's `mktemp -d` wrapper keeps caveman's edit on the copy, so the real file changes only when caveman succeeds. Where caveman keeps its backup: the Step B pointer.\n\n## When NOT to use\n\n- Code files (`.cs`, `.py`, `.ts`, `.sh`, etc.). The methodology is markdown-specific; code-comment compression is out of scope\n- Binary files\n- Author-time-disciplined instruction files (`.claude\u002Frules\u002F**`, `AGENTS.md`, `CLAUDE.md`, `**\u002FSKILL.md`). `audit` will SKIP-recommend; sub-N% revert default applies (Gotchas \"Sub-N% diffs auto-revert unless `--force`\")\n- Conversation summarization or session compaction. That's the built-in `\u002Fcompact`, different semantic\n- **Subagent context invoking `\u002Fdocs-hygiene:compress` for batch fan-out**. See Gotchas \"Self-audit drifts toward EXPANSION\"; follow `context\u002Ffan-out-orchestration.md`\n\n## What this skill is NOT\n\n- **Not an orchestrator surface.** `\u002Fdocs-hygiene:compress` prints a human-readable summary; no structured\u002F`--json` output\n- **Not a lint front-end.** `markdownlint-cli2` is the post-edit verifier, not the purpose\n- **Not a code-comment compressor.** Out of scope\n- **Not a `\u002Fcode-review` \u002F `\u002Fsimplify` shadow.** The bundled `\u002Fcode-review` and `\u002Fsimplify` skills review code changes; `\u002Fdocs-hygiene:compress` rewrites markdown prose\n- **Not `\u002Fdocs-hygiene:audit-noise`.** `\u002Fdocs-hygiene:compress` owns FLAVOR (filler, hedging, redundant restatement, and articles under `compress_articles: cut` only). `\u002Fdocs-hygiene:audit-noise` owns NOISE classification (historical citations, ghost refs, \"Why this file exists\" preambles, hard-coupled enumerated consumer lists) per its own taxonomy. Both may apply to the same target iteratively\n- **Not a content-relocation \u002F cite-don't-recap tool.** Condensing an inline passage that recaps a cited single source of truth (another doc or rule) is content RELOCATION, not flavor removal: the mandatory semantic-diff net sees the words gone from THIS file and reverts them as SEMANTIC LOSS, blind to the SSOT. Apply \"reference, don't duplicate\" as a MANUAL editorial pass (verify the cited SSOT actually holds the detail first; an unread pointer is an unverified claim); route the duplicated cluster to `\u002Fdocs-hygiene:extract-ssot` at any multiplicity (it rosters rule-of-one \u002F -two \u002F -three buckets; only extraction into a NEW artifact waits for 3+ files)\n\n## Sources\n\n- Always-loaded instruction-file yield bound (2-3%): authoring-repo baseline, 3\u002F3 compression attempts reverted, all flavor-only, 0 semantic loss\n- Self-audit expansion drift: authoring-repo batch compression wave, 2026-05-23. 4\u002F4 reverse-direction edits from self-audit (`context\u002Ffan-out-orchestration.md` ## History)\n\n## Reference index. Load on demand\n\n| File | Load when |\n|---|---|\n| `context\u002Fsemantic-diff-prompt.md` | Dispatching the semantic-diff subagent; it is the prompt body and the return contract. |\n| `context\u002Fcompare-prompt.md` | Dispatching the `compare` labeler; it is the prompt body and the return contract. |\n| `context\u002Fflavor-vs-content-matrix.md` | Judging whether a specific span is FLAVOR or CONTENT, and during the revert pass. |\n| `context\u002Ftarget-types.md` | Resolving what an argument points at, or classifying SKIP \u002F COMPRESS \u002F UNCERTAIN in `audit`. |\n| `context\u002Ffan-out-orchestration.md` | Compressing N files across parallel subagents, so the semantic diff stays in a separate context. |\n| `context\u002Fintegration.md` | Another skill, lint job, or gate wants to call this one, and you need the invocation form it may use. |\n","## Repository context. Gather first\n\nCollect these with **individual** Bash calls, one command per call, never combined into a single\ninvocation:\n\n- Current branch, `git branch --show-current`\n- Uncommitted .md files (empty = none matched or the probe returned nothing), `git status --porcelain | grep -E '\\.md\"?$' | head -10`\n\nThe pipe is the bound and belongs in the command. A read-time cap (\"read only the first 10 entries\")\nlimits only what is read after the command returns, never what it returns.\n\n- **Pointer**: when deciding how much command output reaches context, fetch\n  [Output limits](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Ftools-reference#output-limits) live.\n\nTreat a failure (not a repository, git unavailable) as an unknown value and carry on. Keep these as\nseparate body Bash calls, not pre-compute lines ([gather-block convention](https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fdocs\u002Fconventions\u002Fgather-block\u002FREADME.md#the-pre-compute-block-runs-as-one-shell-invocation),\n\"The pre-compute block runs as one shell invocation\").\n\n## Purpose\n\nMarkdown in `docs\u002F`, README files, onboarding docs, third-party pasted prose, and drifted skill bodies accumulates FLAVOR: filler (\"just\", \"really\", \"basically\"), hedging (\"perhaps\", \"might\"), pleasantries, and, only when `compress_articles` is `cut`, articles. `context\u002Fflavor-vs-content-matrix.md` defines FLAVOR (safe to cut) vs CONTENT (never cut). Under the default, `keep`, a run keeps every `a`, `an` and `the` and is held to the batch path's word-level cuts on every target, single file included ([Articles](#articles-compress_articles)). The **batch fan-out path** (Phase A LATITUDE) is a word-level trimmer: mechanical drops + passive→active + nominalization only, no sentence-level restatement deletion. Under `cut`, the **single-file in-session Edit fallback** may apply the full matrix taxonomy (including redundant restatement of bold rule names) behind the same semantic-diff net. Always-loaded instruction files (`.claude\u002Frules\u002F**`, `AGENTS.md`, `CLAUDE.md`, `**\u002FSKILL.md`) bound empirically at 2-3% yield (see ## Sources); author-time-undisciplined content likely yields 5-15% under the Edit fallback's broader latitude, less under batch fan-out.\n\nMethodology: snapshot original → mechanical compression (the `caveman` plugin via `\u002Fcaveman:caveman-compress`, OR in-session Edit fallback) → semantic-diff subagent compares original vs condensed (SEMANTIC LOSS \u002F AMBIGUITY \u002F FALSE POSITIVE per finding, verbatim citations) → revert every SEMANTIC LOSS + AMBIGUITY → run `markdownlint-cli2` → ship or revert.\n\n## Articles: `compress_articles`\n\nResolve this before Step A and before the audit scan; it decides the backend and how much a run may cut. Layers, lowest first, a later one winning (key contract: [`${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fconfig.md`](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fconfig.md)):\n\n| Layer | Value |\n|---|---|\n| default | `keep` |\n| `userConfig` | `${user_config.compress_articles}`. A literal unexpanded token means unset; `keep` here is reported as the default, since the two cannot be told apart. |\n| repository | `compress_articles` in `docs\u002Fconventions\u002Fdocs-hygiene.yaml` at the repository root |\n\nRead the repository layer with `bash \"${CLAUDE_SKILL_DIR}\u002Fscripts\u002Farticles-setting.sh\"`. It prints `keep` or `cut` for a valid value, `unset` with a reason when the layer does not apply (no git working tree, a root that is `$HOME` or an ancestor of it, no file, no key), or `invalid` with what the key holds (a value other than the two, an empty or null value, a map or list, a key set twice, a file that does not parse).\n\nA layer holding anything other than `keep` or `cut` is named in the output (the file or `userConfig` that held it, the key, the value) and dropped. A valid higher layer still wins; with none, the run continues on the default, `keep`. It never stops on an invalid value and never falls through to a lower layer's value.\n\n| Value | Backend | What may be cut |\n|---|---|---|\n| `keep` | in-session Edit, even when caveman is installed ([why `keep` skips caveman](${CLAUDE_PLUGIN_ROOT}\u002Freference\u002Fconfig.md#caveman-removes-articles)) | the batch path's word-level set without articles: filler, hedging, pleasantries, verbose verb phrases, passive to active, nominalization collapse. No sentence or restatement deletion, on a single file as in a batch. An article dropped anyway is restored in the revert pass |\n| `cut` | caveman when available, otherwise in-session Edit (Step A onward, unchanged) | articles too; a single-file Edit run may use the full matrix, restatement deletion included |\n\nReport the result once per run, as the last line of the summary: `compress_articles: keep (default)`, `compress_articles: cut (docs\u002Fconventions\u002Fdocs-hygiene.yaml)`, or `compress_articles: cut (userConfig)`.\n\n**Revert threshold, `compress_revert_below_pct`** (`N` below; a whole number 0-100, default `3`): the same layers, from `${user_config.compress_revert_below_pct}` and, at the repository root `git rev-parse --show-toplevel` prints (skipped as for `compress_articles`), `bash \"${CLAUDE_PLUGIN_ROOT}\u002Flib\u002Fparse-concern-value.sh\" --strict \u003Croot>\u002Fdocs\u002Fconventions\u002Fdocs-hygiene.yaml compress_revert_below_pct` (empty means unset; exit 3 or any other value is invalid and dropped as above). `0` turns the auto-revert off. Report it beside the articles line: `compress_revert_below_pct: 3 (default)`.\n\n## Backend selection\n\nUnder `compress_articles: keep`, skip Step A and Step B's caveman path: the backend is the in-session Edit fallback, held to the `keep` row above. Under `cut`, default-action Step B picks the backend: the `caveman` plugin (marketplace `caveman`, invoked as `\u002Fcaveman:caveman-compress` via the Skill tool) when present, otherwise the in-session Edit fallback, which also substitutes whenever caveman is unwanted. Caveman performs the mechanical flavor cuts; it is NOT the verification gate. `\u002Fcaveman:caveman`, the same plugin's session-wide response formatter, is unrelated to this skill.\n\n**Step A. Detect caveman plugin:** `bash \"${CLAUDE_SKILL_DIR}\u002Fscripts\u002Fdetect-caveman.sh\"`\nTri-state: `available` → prefer caveman; `absent` OR `unknown` → treat as absent and use the Edit fallback (`unknown` means `claude`\u002F`jq` missing from PATH: fail open to Edit, not a hard error).\n\n**Step B, caveman backend (preferred when available):** the steps span tool calls, and Bash state does not persist across them (no `trap … EXIT`, no relying on `$tempdir` in a later call):\n\n1. **Bash call 1**. Create a temp copy and echo its absolute path (no EXIT trap):\n\n   ```bash\n   tempdir=$(mktemp -d)\n   cp \"$target\" \"$tempdir\u002F$(basename \"$target\")\"\n   printf '%s\\n' \"$tempdir\u002F$(basename \"$target\")\"\n   ```\n\n2. **Skill call**. `Skill(caveman:caveman-compress, args=\"\u003Cabsolute-path-from-step-1>\")` on that temp copy.\n3. **Bash call 2**. On caveman success, copy the compressed file back and remove the tempdir explicitly:\n\n   ```bash\n   cp \"\u003Cabsolute-path-from-step-1>\" \"$target\"\n   rm -rf \"$(dirname \"\u003Cabsolute-path-from-step-1>\")\"\n   ```\n\n   On caveman failure, skip the `cp` and still `rm -rf` the tempdir so the real target is untouched.\n\nThe real file is replaced only on success. Consumers may add a defensive `**\u002F*.original.md` entry to their `.gitignore` in case caveman's backup ever lands in the tree.\n\n- **Pointer**: when checking where caveman writes its backup, fetch\n  [caveman-compress, Purpose](https:\u002F\u002Fgithub.com\u002FJuliusBrussee\u002Fcaveman\u002Fblob\u002Fmain\u002Fskills\u002Fcaveman-compress\u002FSKILL.md#purpose)\n  live.\n\n**Step B fallback. In-session Edit (`compress_articles: keep`, or caveman absent, unknown, or unwanted):**\n\nApply Edit ops directly on `$target` per the `context\u002Fflavor-vs-content-matrix.md` taxonomy. Under `cut`: the full matrix, including restatement deletion. Under `keep`: word-level cuts only, every article kept, no sentence or restatement deleted.\n\n**Step C+ unchanged:** semantic-diff dispatch (mandatory hard rule, skipped only by a `light` or `off` verification level, with the resolved `compress_articles` value as the prompt's `{ARTICLES}`, so under `keep` a dropped article is SEMANTIC LOSS and is restored), revert pass for SEMANTIC LOSS \u002F AMBIGUITY \u002F UNCERTAIN findings, markdownlint-cli2, summary.\n\n## Action router\n\n| Action | Args | Behavior |\n|---|---|---|\n| `\u003Ctarget>` (default, no action keyword) | empty → uncommitted `.md` from `git status`; file path → single-file; dir path → batch | snapshot → backend → dispatch → revert-pass → markdownlint verify → summary |\n| `audit [target]` | same target rules | read-only dry-run; run `scripts\u002Faudit-scan.sh --articles \u003Cresolved compress_articles>` (six-signal heuristic in `context\u002Ftarget-types.md`); classify SKIP\u002FCOMPRESS\u002FUNCERTAIN |\n| `compare ORIG_DIR NEW_DIR [REASONS]` | two skill directories, before and after a rewrite; optional file listing each intended cut with its deletion-test reason | read-only; see `## Compare` |\n\nFlags (apply to the default and `audit` actions):\n\n- `--force`. Proceed even when the `\u003CN% AND 0 semantic-loss → REVERT` rule would trip; beats every `compress_revert_below_pct` layer. User owns the sub-N% diff\n- `--keep-snapshot`. Persist the original to `${CLAUDE_PLUGIN_DATA}\u002Fsnapshots\u002F\u003CISO-basic>Z-\u003Cbasename>.orig.md` (the plugin data directory survives plugin updates)\n\n## Compare\n\nJudges a rewrite of a whole skill directory, SKILL.md plus its references, where the default\naction's per-file diff would call every moved line and every intended cut a loss.\n\n1. Check both paths are directories; stop on a missing one. Write nothing to either.\n2. Dispatch the read-only `docs-hygiene:compare-labeler` agent with `context\u002Fcompare-prompt.md`,\n   never `general-purpose`, which can edit. The calling session never labels a difference: it may\n   have written the rewrite and would excuse its own cuts. The step is done when the return\n   carries labeled rows and a `VERDICT:` line.\n3. Print the labeler's rows and its literal `VERDICT: PASS` or `VERDICT: BLOCK` line verbatim, as\n   returned: no restyling, reformatting, reordering, bolding, recasing or paraphrase. Any summary\n   of your own goes after them. `VERDICT: BLOCK` (any SEMANTIC LOSS, or an instruction in the\n   compared text aimed at the labeler) is the gate a rollout PR blocks on.\n\n## Auto-detect default\n\nShared clean-tree \u002F no-scope shape: [`..\u002F..\u002Fcontext\u002Fclean-tree-fallback.md`](..\u002F..\u002Fcontext\u002Fclean-tree-fallback.md). The rules below are what this skill runs; open the shared file only when editing them, for the sibling divergences it owns.\n\n1. Empty arg AND clean tree → interactive session: repo-wide interview fallback (next section); non-interactive context (subagent, headless\u002FCI): friendly no-op exit 0 (\"No uncommitted .md files. Pass file\u002Fdir target.\")\n2. Empty arg AND uncommitted `.md` files → batch default action over those files\n3. Single file path → single-file default action\n4. Directory path → batch default action (filenames sorted lexically for deterministic output)\n5. First positional == `audit` → audit action on rest (same clean-tree offer as rule 1 when the rest is empty. Report-only corpus audit, no Edit)\n6. First positional == `compare` → compare action on the next two paths (and an optional REASONS file); no clean-tree fallback\n\n## Repo-wide interview fallback (empty arg, clean tree, interactive)\n\nInstead of dead-ending, offer a repo-wide run, confirmation-gated at the offer (step 1) and before the run (step 4); declining at either exits with the friendly no-op message. Bare `\u002Fdocs-hygiene:compress audit` on a clean tree uses steps 1–2 only (free audit + report; no compression defaults or run confirmation).\n\n1. **Offer** (AskUserQuestion): run against all tracked eligible `.md` files? Decline → no-op exit.\n2. **Audit first** (free, mechanical scan, no subagents): run the audit action over every tracked eligible `.md`. Present INLINE only aggregate counts per class, a dispatch-cost estimate (2 subagent requests per compressed file), and a top-20 excerpt of COMPRESS rows selected deterministically: expected-yield band descending, then word count descending, then lexical path (band strings tie; the two tie-breaks keep the excerpt stable run-to-run). Write the full per-file table, lexically sorted per the \"Summary output deterministic\" hard rule, to `${CLAUDE_PLUGIN_DATA}\u002Faudit\u002F\u003Cbranch-or-scope>-audit.md` when that dir is writable, otherwise to a temp path echoed to the user, and point at it. Never render every row inline: on a large repo the full table can run to hundreds of KB and truncate the confirmation prompt it feeds. **Stop here when the invocation was the audit action** (report-only).\n3. **Take the prescribed defaults**, default (mutating) action only. Take each default below without asking and report all three in one line, each with its override, for example `Defaults: scope top-10 COMPRESS (override: top-N, all COMPRESS, include UNCERTAIN, or report only); concurrency 2 (override: 1 or 3-5); always-loaded files excluded (override: explicit opt-in)`. The user overrides any of them in the reply to step 4's confirmation.\n   - **Scope**. Default: **top-10** COMPRESS-classified files, the first ten COMPRESS rows in step 2's order; overrides: top-N (user picks N), all COMPRESS, include UNCERTAIN, stop after audit (report only). A misclassified cohort burns two dispatches per file before the circuit breaker stops it, so the default caps exposure at ten. See `context\u002Ffan-out-orchestration.md` circuit breaker.\n   - **Concurrency**. Default: 2 concurrent subagents per wave (rate-limit-conservative); overrides: 1 (sequential), 3-5 (`context\u002Ffan-out-orchestration.md` default).\n   - **Always-loaded files**. Default: excluded (SKIP per the 2-3% empirical baseline); they stay excluded unless the user opts in explicitly, the same opt-in as `--force`.\n4. **Confirm and run**: batch default action over the set step 3 reported, with any override the user gave, waves per `context\u002Ffan-out-orchestration.md`. Every per-file hard rule, semantic-diff dispatch, revert pass, markdownlint, `\u003CN% AND 0 semantic-loss → REVERT`, applies unchanged.\n\nNon-interactive contexts skip the offer and take the no-op branch. The fallback adds an entry path only. It changes no compression, verification, or revert semantics.\n\n## Hard rules\n\n- **Semantic-diff dispatch is mandatory for default action** at the `standard` and `strict` verification levels. Audit is read-only. No dispatch. Compare is read-only and always dispatches its labeler, whatever the level: the labels are its output.\n- **The verification level.** Before the first default-action target, run `bash \"${CLAUDE_PLUGIN_ROOT}\u002Flib\u002Fread-verification.sh\" --plugin docs-hygiene --skill compress --file docs\u002Fconventions\u002Fdocs-hygiene.yaml` once and report its line ([levels](https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fdocs\u002Fcontracts\u002Fverification-level\u002FREADME.md)). Under `light`, and `off`, which acts as `light` here, dispatch no semantic-diff subagent and never audit the edit inline in its place: the target's summary line carries `verification: skipped (\u003Clevel>)` in place of the `semantic_loss`, `ambiguity` and `false_positive` counts, no revert pass runs, and the `\u003CN%` auto-revert applies on compression alone. `markdownlint-cli2` still gates every level.\n- **Post-edit `markdownlint-cli2` MUST pass** (with the consuming repository's markdownlint config when present). Non-zero exit blocks ship; revert and surface failures. It is the ship gate, so it is **required for correctness**: if the binary is absent (neither on `PATH` nor as the repo's `node_modules\u002F.bin\u002Fmarkdownlint-cli2`), STOP at the entry point before compressing anything and surface the remediation. Install it explicitly (`npm install --save-dev markdownlint-cli2` or a global install); never treat absence as a lint failure and never ship unverified output.\n- **`\u003CN% AND 0 semantic-loss → REVERT`**, `N` = `compress_revert_below_pct`, default 3. The default is proven safe in the authoring repo's empirical baseline (always-loaded instruction files: 3\u002F3 attempts reverted). `--force` bypasses.\n- **Summary output deterministic.** No timestamps; filenames sort lexically.\n- **Snapshot default = ephemeral** (`mktemp -d`, deleted post-dispatch). `--keep-snapshot` persists to `${CLAUDE_PLUGIN_DATA}\u002Fsnapshots\u002F` instead.\n- **Always-loaded instruction-file policy: SOFT-BLOCK.** Default reverts \u003CN%\u002F0SL on ANY file including `.claude\u002Frules\u002F**` \u002F `AGENTS.md` \u002F `CLAUDE.md` \u002F `**\u002FSKILL.md`. `--force` bypasses on ANY file; the user owns the result. `audit` emits an informational SKIP recommendation on always-loaded paths citing the 2-3% empirical baseline; not a structural gate.\n- **Subagent dispatch follows `context\u002Fsemantic-diff-prompt.md` template.** Findings must carry verifiable citations; training-recall citation tokens are forbidden: `[known]` \u002F `[from memory]` \u002F `[context]` \u002F `[obvious]` \u002F `[standard]` \u002F `[usual]`.\n- **Backend choice does NOT bypass semantic-diff dispatch.** When the caveman backend is absent or unwanted, `\u002Fdocs-hygiene:compress` falls back to in-session Edit compression. Backend selection determines only the mechanical-compression path; semantic-diff, revert pass and markdownlint apply regardless (the verification level alone can skip the first two), and the revert pass structurally catches LLM-compression fabrication from either backend.\n\n## Output schema (default action, per target)\n\n```text\n\u003Cbasename>: \u003Caction_taken> (compression_pct=N.N%, semantic_loss=K, ambiguity=M, false_positive=P, markdownlint=PASS|FAIL)\n```\n\n`action_taken` ∈ {`compressed`, `reverted`, `skipped`}. Aggregate at end of batch.\n\nAudit action output: table with `target`, `expected_yield_pct`, `classify` (SKIP\u002FCOMPRESS\u002FUNCERTAIN), `reason`.\n\n## Gotchas\n\n- **Self-audit drifts toward EXPANSION.** Run the semantic-diff dispatch as a SEPARATE fresh-context audit, never a self-audit by the model that produced the edits: self-audit re-adds words just removed (\"preserve clarity\"; an observed failure, see ## Sources). Prefer a cross-vendor advisor for that audit **when one is installed and set up**, e.g. the OpenAI Codex plugin, when its documented surface can take this artifact, invoked per its own docs, with the fresh-context same-vendor subagent as the stated fallback, never a route to a command that may not resolve (per `docs\u002Fplugin-philosophy.md` \"Fresh-eyes checkpoints\" in the marketplace repository). For batch fan-out follow `context\u002Ffan-out-orchestration.md`: the main session dispatches separate compress + audit subagents and reconciles per finding, so every audit stays under its control rather than inside a compressor's context.\n\n  - **Pointer**: when a design question turns on whether a subagent can spawn its own, fetch\n    [Let subagents spawn their own subagents](https:\u002F\u002Fcode.claude.com\u002Fdocs\u002Fen\u002Fsub-agents#let-subagents-spawn-their-own-subagents)\n    live.\n- **Sub-N% diffs auto-revert unless `--force`.** Pass `--force` only when a targeted sub-N% diff is intentional; the user owns the result.\n- **Run caveman on a temp copy, never the real file.** Step B's `mktemp -d` wrapper keeps caveman's edit on the copy, so the real file changes only when caveman succeeds. Where caveman keeps its backup: the Step B pointer.\n\n## When NOT to use\n\n- Code files (`.cs`, `.py`, `.ts`, `.sh`, etc.). The methodology is markdown-specific; code-comment compression is out of scope\n- Binary files\n- Author-time-disciplined instruction files (`.claude\u002Frules\u002F**`, `AGENTS.md`, `CLAUDE.md`, `**\u002FSKILL.md`). `audit` will SKIP-recommend; sub-N% revert default applies (Gotchas \"Sub-N% diffs auto-revert unless `--force`\")\n- Conversation summarization or session compaction. That's the built-in `\u002Fcompact`, different semantic\n- **Subagent context invoking `\u002Fdocs-hygiene:compress` for batch fan-out**. See Gotchas \"Self-audit drifts toward EXPANSION\"; follow `context\u002Ffan-out-orchestration.md`\n\n## What this skill is NOT\n\n- **Not an orchestrator surface.** `\u002Fdocs-hygiene:compress` prints a human-readable summary; no structured\u002F`--json` output\n- **Not a lint front-end.** `markdownlint-cli2` is the post-edit verifier, not the purpose\n- **Not a code-comment compressor.** Out of scope\n- **Not a `\u002Fcode-review` \u002F `\u002Fsimplify` shadow.** The bundled `\u002Fcode-review` and `\u002Fsimplify` skills review code changes; `\u002Fdocs-hygiene:compress` rewrites markdown prose\n- **Not `\u002Fdocs-hygiene:audit-noise`.** `\u002Fdocs-hygiene:compress` owns FLAVOR (filler, hedging, redundant restatement, and articles under `compress_articles: cut` only). `\u002Fdocs-hygiene:audit-noise` owns NOISE classification (historical citations, ghost refs, \"Why this file exists\" preambles, hard-coupled enumerated consumer lists) per its own taxonomy. Both may apply to the same target iteratively\n- **Not a content-relocation \u002F cite-don't-recap tool.** Condensing an inline passage that recaps a cited single source of truth (another doc or rule) is content RELOCATION, not flavor removal: the mandatory semantic-diff net sees the words gone from THIS file and reverts them as SEMANTIC LOSS, blind to the SSOT. Apply \"reference, don't duplicate\" as a MANUAL editorial pass (verify the cited SSOT actually holds the detail first; an unread pointer is an unverified claim); route the duplicated cluster to `\u002Fdocs-hygiene:extract-ssot` at any multiplicity (it rosters rule-of-one \u002F -two \u002F -three buckets; only extraction into a NEW artifact waits for 3+ files)\n\n## Sources\n\n- Always-loaded instruction-file yield bound (2-3%): authoring-repo baseline, 3\u002F3 compression attempts reverted, all flavor-only, 0 semantic loss\n- Self-audit expansion drift: authoring-repo batch compression wave, 2026-05-23. 4\u002F4 reverse-direction edits from self-audit (`context\u002Ffan-out-orchestration.md` ## History)\n\n## Reference index. Load on demand\n\n| File | Load when |\n|---|---|\n| `context\u002Fsemantic-diff-prompt.md` | Dispatching the semantic-diff subagent; it is the prompt body and the return contract. |\n| `context\u002Fcompare-prompt.md` | Dispatching the `compare` labeler; it is the prompt body and the return contract. |\n| `context\u002Fflavor-vs-content-matrix.md` | Judging whether a specific span is FLAVOR or CONTENT, and during the revert pass. |\n| `context\u002Ftarget-types.md` | Resolving what an argument points at, or classifying SKIP \u002F COMPRESS \u002F UNCERTAIN in `audit`. |\n| `context\u002Ffan-out-orchestration.md` | Compressing N files across parallel subagents, so the semantic diff stays in a separate context. |\n| `context\u002Fintegration.md` | Another skill, lint job, or gate wants to call this one, and you need the invocation form it may use. |\n",{"metadata":24,"description":7,"argument-hint":27,"user-invocable":28,"disable-model-invocation":20},{"summary":25,"workflow-stage":26},"Tighten markdown by dropping flavor while preserving every directive","anytime","[audit [target]|compare \u003CORIG_DIR> \u003CNEW_DIR> [REASONS]|target] [--force] [--keep-snapshot]",true,"main","d0e68c3f36b92a1d6381f0ba0060d7a0b8b886c5","plugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress",7,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins","https:\u002F\u002Fgithub.com\u002Fmelodic-software","https:\u002F\u002Fmelodicsoftware.com","Independent software studio building developer tools, automation, and application services, with roots in music.","2026-11-15 05:15:06",{"source":8,"skillName":5,"commands":39,"prompt":49,"zipAvailable":28},[40,43,46],{"tool":41,"command":42},"npx","npx skills add melodic-software\u002Fclaude-code-plugins --skill compress",{"tool":44,"command":45},"bunx","bunx skills add melodic-software\u002Fclaude-code-plugins --skill compress",{"tool":47,"command":48},"pnpm","pnpm dlx skills add melodic-software\u002Fclaude-code-plugins --skill compress","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002FSKILL.md",[51,57,61,65,69,73,77,81,85,89,93,97,101,105,109,113,119,123,127,131,135],{"path":52,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":55,"sourceHtmlUrl":56},"context\u002Fcompare-prompt.md","REFERENCE","参考文档",3221,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fcontext\u002Fcompare-prompt.md",{"path":58,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":59,"sourceHtmlUrl":60},"context\u002Ffan-out-orchestration.md",6636,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fcontext\u002Ffan-out-orchestration.md",{"path":62,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":63,"sourceHtmlUrl":64},"context\u002Fflavor-vs-content-matrix.md",5523,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fcontext\u002Fflavor-vs-content-matrix.md",{"path":66,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":67,"sourceHtmlUrl":68},"context\u002Fintegration.md",4969,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fcontext\u002Fintegration.md",{"path":70,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":71,"sourceHtmlUrl":72},"context\u002Fsemantic-diff-prompt.md",5301,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fcontext\u002Fsemantic-diff-prompt.md",{"path":74,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":75,"sourceHtmlUrl":76},"context\u002Ftarget-types.md",8498,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fcontext\u002Ftarget-types.md",{"path":78,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":79,"sourceHtmlUrl":80},"evals\u002Fevals.json",18429,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fevals\u002Fevals.json",{"path":82,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":83,"sourceHtmlUrl":84},"evals\u002Ffixtures\u002Faudit-fixture-dir\u002Flean.md",528,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fevals\u002Ffixtures\u002Faudit-fixture-dir\u002Flean.md",{"path":86,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":87,"sourceHtmlUrl":88},"evals\u002Ffixtures\u002Faudit-fixture-dir\u002Fmixed.md",713,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fevals\u002Ffixtures\u002Faudit-fixture-dir\u002Fmixed.md",{"path":90,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":91,"sourceHtmlUrl":92},"evals\u002Ffixtures\u002Faudit-fixture-dir\u002Fverbose.md",1837,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fevals\u002Ffixtures\u002Faudit-fixture-dir\u002Fverbose.md",{"path":94,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":95,"sourceHtmlUrl":96},"evals\u002Ffixtures\u002Fdocs-hygiene-articles-invalid.yaml",113,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fevals\u002Ffixtures\u002Fdocs-hygiene-articles-invalid.yaml",{"path":98,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":99,"sourceHtmlUrl":100},"evals\u002Ffixtures\u002Fdocs-hygiene-articles-keep.yaml",116,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fevals\u002Ffixtures\u002Fdocs-hygiene-articles-keep.yaml",{"path":102,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":103,"sourceHtmlUrl":104},"evals\u002Ffixtures\u002Frestated-rule-name.md",350,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fevals\u002Ffixtures\u002Frestated-rule-name.md",{"path":106,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":107,"sourceHtmlUrl":108},"evals\u002Ffixtures\u002Fterse-agent.md",346,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fevals\u002Ffixtures\u002Fterse-agent.md",{"path":110,"resourceType":53,"resourceTypeDesc":54,"sizeBytes":111,"sourceHtmlUrl":112},"evals\u002Ffixtures\u002Fverbose-onboarding-snippet.md",599,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fevals\u002Ffixtures\u002Fverbose-onboarding-snippet.md",{"path":114,"resourceType":115,"resourceTypeDesc":116,"sizeBytes":117,"sourceHtmlUrl":118},"scripts\u002Farticles-setting.sh","SCRIPT","脚本",2502,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fscripts\u002Farticles-setting.sh",{"path":120,"resourceType":115,"resourceTypeDesc":116,"sizeBytes":121,"sourceHtmlUrl":122},"scripts\u002Farticles-setting.test.sh",5271,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fscripts\u002Farticles-setting.test.sh",{"path":124,"resourceType":115,"resourceTypeDesc":116,"sizeBytes":125,"sourceHtmlUrl":126},"scripts\u002Faudit-scan.sh",5046,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fscripts\u002Faudit-scan.sh",{"path":128,"resourceType":115,"resourceTypeDesc":116,"sizeBytes":129,"sourceHtmlUrl":130},"scripts\u002Faudit-scan.test.sh",4540,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fscripts\u002Faudit-scan.test.sh",{"path":132,"resourceType":115,"resourceTypeDesc":116,"sizeBytes":133,"sourceHtmlUrl":134},"scripts\u002Fdetect-caveman.sh",1598,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fscripts\u002Fdetect-caveman.sh",{"path":136,"resourceType":115,"resourceTypeDesc":116,"sizeBytes":137,"sourceHtmlUrl":138},"scripts\u002Fdetect-caveman.test.sh",3613,"https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdocs-hygiene\u002Fskills\u002Fcompress\u002Fscripts\u002Fdetect-caveman.test.sh",[140,147,154,161,166,173],{"skillNo":141,"name":142,"nameZh":6,"description":143,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":144,"categories":145,"keywords":146,"publishedAt":19},"01M7DYYDG31B9YX7N9MB9QW2GW","track","Backlog reads through the bound tracker: search open and closed items, view one item with its comments and state history. Use when another skill searches or reads tracker items.","https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fsession-flow\u002Fevals\u002Frecall-still-reports-reopened-bug\u002Fwork-items-stub\u002Fskills\u002Ftrack\u002FSKILL.md",[],[],{"skillNo":148,"name":149,"nameZh":6,"description":150,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":151,"categories":152,"keywords":153,"publishedAt":19},"01M7DYXVBAVG3NV30PA7GKW9Q6","reviewer-media","Reviewer media for one pull request: decides whether it needs a narrated walkthrough, builds the storyboard from \u002Freview:explain-change's digest, has \u002Fexplainer-video:produce render it and hands the manifest to \u002Fsource-control:pull-request media. Use when asked for 'reviewer media', 'a walkthrough video for this PR', 'a produced video of this change', or when pull-request ready or monitor hands a PR over.","https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Freview\u002Fskills\u002Freviewer-media\u002FSKILL.md",[],[],{"skillNo":155,"name":156,"nameZh":6,"description":157,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":158,"categories":159,"keywords":160,"publishedAt":19},"01M7DYRZ5YD44AMYH26YR25GZ8","route","Model and effort per agent role (orchestrator, worker, verifier, retrieval) for a multi-agent run, resolved through the bundled defaults and the user, team and personal override config layers into fenced JSON with single-agent and fan-out variants and the layer behind each value. Use when asked 'which model for the subagents', 'route the roles' or 'model routing', or before a skill passes a role's model on a spawn.","https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdiscovery\u002Fevals\u002Fex-model-pin-without-override\u002Fmulti-agent-stub\u002Fskills\u002Froute\u002FSKILL.md",[],[],{"skillNo":162,"name":156,"nameZh":6,"description":157,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":163,"categories":164,"keywords":165,"publishedAt":19},"01M7DYRTVT4FWTGDJY0HCCFJMZ","https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Fdiscovery\u002Fevals\u002Fex-model-override-from-route\u002Fmulti-agent-stub\u002Fskills\u002Froute\u002FSKILL.md",[],[],{"skillNo":167,"name":168,"nameZh":6,"description":169,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":170,"categories":171,"keywords":172,"publishedAt":19},"01M7DYNZC8PNW3T27V2ADKECKJ","principles","Module-design vocabulary for architecture findings, and the checks built on it. Use when: 'what is a deep module', 'what is a seam', 'deep vs shallow module', 'what is the deletion test', 'leverage and locality', 'module design vocabulary', 'which word do we use for X in architecture findings'. Scanning a codebase for friction is \u002Farchitecture:improve.","https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Farchitecture\u002Fskills\u002Fprinciples\u002FSKILL.md",[],[],{"skillNo":174,"name":175,"nameZh":6,"description":176,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":177,"categories":178,"keywords":179,"publishedAt":19},"01M7DYNMCZNEWBFHV9KTSS6H60","write","Structured five-field bug report (title, steps to reproduce, expected vs actual, justified severity, suggested fix location) from an informal description, read-only. Use when the user names a defect they observed, or asks for one written up ('report a bug', 'file a bug', 'write this up as a bug').","https:\u002F\u002Fgithub.com\u002Fmelodic-software\u002Fclaude-code-plugins\u002Fblob\u002Fmain\u002Fplugins\u002Farchitecture\u002Fevals\u002Fdeepening-defect-goes-to-bugs-write\u002Fbugs-stub\u002Fskills\u002Fwrite\u002FSKILL.md",[],[]]