cowork-doc-init - SKILL.md Agent Skill

name: cowork-doc-init description: "One-time bootstrap of an existing project's docs/ and source into the cowork-doc-sync taxonomy structure. After a detailed gap analysis, relocate docs to match the standard. Phase 1 = relocation only (no new creation, includes moving content between docs), Phase 2 = analyze source to create new docs (only after user approval). For ongoing maintenance use /cowork-doc-sync. Triggers: cowork-doc-init, /cowork-doc-init, init doc structure, relocate docs, organize existing docs, doc init, doc bootstrap"

/cowork-doc-init — Bootstrap existing docs/source into the cowork-doc-sync structure (one-time)

For fitting an existing project to the cowork-doc-sync taxonomy for the first time. For ongoing maintenance afterward, use /cowork-doc-sync.

Required read (every call)

../cowork-doc-sync/references/taxonomy.md — target spec (taxonomy/status/migration/tool separation/vault boundary)
Target repo's docs/CONVENTION.md (if present)

Safety principles (MUST)

Phase 1 = relocation only. No new content creation, no rewriting existing content. Content is verbatim move only (summary/polish = Phase 2's domain).
Phase 2 = source→new-doc creation. Only proceed after user approval. (Hallucination risk — code-grounded only, no speculation.)
git is the safety net — but present a plan first before bulk moves. If it feels irreversible, confirm.
Delete only pure clutter (taxonomy §3). If unsure, do not delete — use 99-misc or 04-legacy.

Phase 1 — gap analysis + relocation (no new creation)

1. Inventory: enumerate all docs in docs/ + grasp the structure. (Source = only light cross-reference, to judge LIVING/stale)
2. Classify — each doc, and each major section within a doc:
   → which bucket (00~06/99)?  + which status (LIVING/ACTIVE/FROZEN)?
   Must view at the section level: if one doc mixes LIVING (current), FROZEN (past), and other topics, split it.
   e.g. a "current architecture" section inside a plan doc → move to 01-built (LIVING) / the rest of the plan → keep in 02-planned.
3. Write a gap-analysis report (current → proposed mapping: destination per doc/section + rationale + move/delete/tombstone action).
   → Present to the user. Get a nod before executing bulk/risky moves.
3-b. fold-check (for each legacy candidate): has the current truth been absorbed into as-built (LIVING)?
     ★ **If LIVING cites that plan as the "detail spec"** = only summarized = **not-folded → must not legacy it, keep in place as FROZEN-built.** (taxonomy §3.)
4. Execute relocation (taxonomy §3 rules):
   - Whole doc superseded (fully-folded) → move to 04-legacy + tombstone
   - Section move → cut verbatim and paste into the destination doc. Delete the original location + a 1-line pointer if needed.
   - Pure clutter → delete. Tool-generated artifacts (commit-log/bkit) → do not touch (§4).
   - ★ **Update inbound references (MUST)**: before moving, check blast radius (`grep -rn <basename>.md`). After moving, **fix broken LIVING/ACTIVE/manual → MOVED links** (if the plan was "current," redirect to as-built). intra-legacy/frozen internal links = preserve (history).
5. Establish single LIVING authority: consolidate the current truth into 01-built. Assign status label headers.
6. File the report as 05-reports/YYYYMMDD-cowork-doc-init.md (work record + skill defects found).

Relocation principle: you are moving, not rewriting. Preserve facts = verbatim. "This section is stale, should I fix it?" → in Phase 1 do not fix it; if it is LIVING, move it as-is to 01-built and only flag "needs update" in the report (actual update happens via /cowork-doc-sync or user instruction).

Phase 2 — source analysis → new doc creation (user approval required)

1. Source gap analysis: identify areas the code does that no doc covers
   (e.g. missing as-built architecture, missing manual, missing handover for a core module).
2. Proposal: list which new docs to create (in which bucket) + rationale.
3. ⛔ Create only the items the user has been asked about and approved. (Creation = code-grounded, no speculation.)
4. Artifacts → the appropriate bucket. as-built=01-built (LIVING), manual=03-manual, handover=03-manual.

Output

Phase 1: relocated docs/ + a gap-analysis/relocation report in 05-reports/.
Phase 2 (if approved): code-grounded new docs.
After completion, advise: for ongoing maintenance afterward, use /cowork-doc-sync.