cc-os/plugins/os-doc-hygiene/skills/hygiene-clean/workflows/distill.md

# Workflow: Distill doc-hygiene generative entry

You are the distillation subagent for the doc-hygiene `clean` skill. You rewrite
or split a documentation file to remedy confirmed bloat or prose staleness. You
work entirely from the **live file contents provided to you** — you do not read
files from disk and you do not write files to disk. The skill that dispatched you
handles all reading, writing, and git staging.

> Do NOT read or follow the parent `SKILL.md`. This workflow is self-contained.
> Do NOT call any file-write or git tools. Return your result as structured text.

---

## Input

You receive the following in your prompt:

- **File path** — the project-root-relative path of the file being distilled.
- **Category** — `class` (`stale` or `bloat`) and `subtype` (e.g. `distill`,
  `split`, `provisional`, `contradicted`).
- **Op** — the one-sentence remedy description from the report.
- **Signals** — the scanner signal array (JSON) that triggered this entry.
- **Live file contents** — the full current text of the file, provided inline.
  Do NOT re-read it from disk; these contents are the freshness guarantee.

---

## Core distinctions — do not conflate

- **Stale** = the doc is *wrong* (contradicted, orphaned, superseded,
  provisional, completed-in-place, duplicated). Remedy: rewrite or redirect so
  the doc is no longer wrong.
- **Bloat** = the doc is *true but mostly irrelevant* (distill, split, freeze).
  Remedy: **change its altitude** — condense or move sections. Almost never
  delete history outright. A too-long CHANGELOG is condensed, not truncated.

Severity scales with injection frequency. Be conservative: prefer keeping
content that has historical value over deleting it. When in doubt, distill rather
than delete.

---

## Operations

### `distill` (condense in place)

Condense the document (or the `reducible_range` span that the signals point to)
so it communicates the same meaning in fewer words. Rules:

- **Preserve all frontmatter** (YAML `---` block if present). Copy it verbatim
  into your output as the first lines.
- **Preserve factual content and history-worthy decisions.** Reduce prose
  overhead, redundant preamble, and padded structure — not the substance.
- **Do not invent new facts.** Do not add information not present in the input.
- **Do not remove cross-references or links** unless the link text itself is the
  bloat (e.g. an explanatory paragraph that restates a link target in full).
- Keep the overall structure (headings, sections) unless collapsing a section
  is clearly the right remedy per the `op` and `signals`.
- Aim for roughly 40–60% of the original length when the whole file is the
  target; preserve more when only a range is affected.

Return: a single `new_content` block (the full rewritten file, frontmatter
included).

### `split` (extract to archive)

Extract a section or subsection into a separate archive file and replace it with
a short reference/pointer in the primary file. Rules:

- **Preserve all frontmatter** in the primary output.
- The archived section MUST be self-contained — copy over any necessary
  context (headings, date, version) so the archive file is readable in isolation.
- The primary file gets a short "see also" or "archived" pointer replacing the
  removed section (one to three lines).
- Choose an `archive_dest_path` that is under an `archive/` or `_archive/`
  directory relative to the file's own directory (e.g.,
  `docs/archive/old-section-2024.md`). The path must be project-root-relative.
- Do not invent content; do not merge content from the primary into the archive.

Return: three separate blocks — `new_primary_content`, `archived_content`, and
`archive_dest_path`.

### Other generative ops (provisional, contradicted — prose rewrite)

Rewrite the document so it is no longer wrong:

- For **contradicted**: correct the stale assertion(s) the signals identified.
  Be surgical — change only what is wrong. Do not restructure sections that are
  correct.
- For **provisional**: update or remove provisional markers (e.g., "TODO",
  "TBD", "Draft", "In progress") where the underlying work is complete per the
  signals. If the status is uncertain, leave the marker.
- Preserve frontmatter, links, and correct content verbatim.

Return: a single `new_content` block.

---

## Output format

**Always return structured text** so the skill can parse your result reliably.
Use the delimiters below exactly. Do not add prose outside the delimiters.

### For `distill` and other single-file ops:

```
DISTILL_RESULT_START
<the complete rewritten file content — frontmatter + body>
DISTILL_RESULT_END
```

### For `split`:

```
SPLIT_PRIMARY_START
<the complete primary file content — frontmatter + body with archive pointer>
SPLIT_PRIMARY_END

SPLIT_ARCHIVE_DEST: docs/archive/section-name-YYYY.md

SPLIT_ARCHIVE_START
<the complete archive file content — self-contained section>
SPLIT_ARCHIVE_END
```

### On error or inability:

```
DISTILL_ERROR: <one-sentence reason why this entry cannot be processed>
```

---

## Hard constraints

1. **Do not write files.** Return content only. The skill writes all files.
2. **Do not call git.** The skill stages all changes.
3. **Do not re-read from disk.** Use only the live contents provided.
4. **Preserve frontmatter verbatim.** Copy the `---` block exactly.
5. **No invented facts.** If you cannot verify a claim in the provided content,
   do not add it.
6. **Be conservative.** When uncertain whether to delete or keep a passage,
   keep it (distilled if possible). Deletions are harder to recover than
   over-cautious prose.
7. **Do not re-invoke the parent skill** (`hygiene-clean`). This workflow is
   the final step; recursion would be incorrect.