Docs

---
name: docs
description: Consolidate a project's legacy docs snapshots (docs/requirement, docs/use-cases, docs/testplan) into the living docs under docs/specs, one context per run. Use when kf doctor lists "Legacy docs not consolidated" or the user asks to migrate or consolidate the docs.
---

# Docs — consolidate legacy snapshots into living specs

Plugin root: `${CLAUDE_PLUGIN_ROOT}` — resolve it to the path this skill was loaded from.

`docs/specs/` is the current description of the system. The legacy snapshots are history awaiting consolidation. This skill moves their content into specs, one context at a time, and leaves the merge to the human.

## Procedure

1. Run `kf doctor --json` and read `legacyDocs`: the legacy feature names still to consolidate, per context. Pick one context per run; when several remain, name them and ask which comes first.
2. Check the branch with `git branch --show-current`. Never work on the default branch. Ask the user before creating the branch for this run, name it, and wait for the yes.
3. List the context's legacy files (`docs/requirement/<context>/`, `docs/use-cases/<context>/`, `docs/testplan/<context>/`), read them and the existing `docs/specs/` files. Build a table: each legacy file, the spec file it folds into (new or existing), and what is dropped as obsolete.
4. Present the table and wait for the user to approve it. Write nothing until the table is approved; an edit to the table is approved again.
5. Write each capability as `docs/specs/<context>/<capability>.md` from the template `kf instruct living-doc` prints; it must carry the five headings `## Purpose`, `## Current behaviour`, `## Use cases`, `## Surfaces` and `## History`. Link every capability from the context index `docs/specs/<context>/README.md` (`## Capabilities`; template from `kf instruct living-doc-index`) and link nothing that does not exist. Remove a legacy file only when its content is fully folded in; keep a feature's legacy files together, never half-removing one feature. Name each removed legacy feature as `<context>/<feature>` on a line of a `## History` section of the capability that absorbed it, or of the index `## Retired` section when it is dropped.
6. Run `kf validate --all --strict --base origin/<default branch>` before the PR — the same command CI runs — and fix every finding in its `(project)` block. Run `kf doctor` to confirm the context no longer appears.
7. Commit on the branch and open the PR. Never merge it: the human merges.

## Never

- Never merge, never push to or commit on the default branch.
- Never write before the table is approved.
- Never consolidate more than one context in a run.