# 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 DISTILL_RESULT_END ``` ### For `split`: ``` SPLIT_PRIMARY_START SPLIT_PRIMARY_END SPLIT_ARCHIVE_DEST: docs/archive/section-name-YYYY.md SPLIT_ARCHIVE_START SPLIT_ARCHIVE_END ``` ### On error or inability: ``` DISTILL_ERROR: ``` --- ## 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.