# Docs Reorganization Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** Reorganize `docs/` into stable long-lived sections, remove obsolete files, normalize document headers, and repair repository references.

**Architecture:** Keep `docs/plans/` as historical implementation records, move active operating material into `docs/guides/`, move review and governance material into `docs/audits/`, keep `docs/postman/` for collection assets, and add `docs/README.md` as the top-level navigation entrypoint.

**Tech Stack:** Markdown, shell file operations, ripgrep

---

### Task 1: Create the target docs structure

**Files:**
- Create: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/README.md`
- Create: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/guides/`
- Create: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/audits/`

**Step 1: Write the failing test**

Manual expectation: `docs/README.md`, `docs/guides/`, and `docs/audits/` do not yet exist.

**Step 2: Run test to verify it fails**

Run: `find docs -maxdepth 1 -type d -o -type f | sort`
Expected: FAIL to show the new structure.

**Step 3: Write minimal implementation**

Create the new directories and the docs index file.

**Step 4: Run test to verify it passes**

Run: `find docs -maxdepth 2 | sort`
Expected: PASS with `docs/README.md`, `docs/guides`, and `docs/audits`.

### Task 2: Move active docs into semantic directories

**Files:**
- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/guides/release-checklist.md`
- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/guides/setup-config-api.md`
- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/audits/auth-session-acceptance.md`
- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/audits/setup-config-code-audit.md`
- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/audits/storage-persistence-audit.md`
- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/audits/storage-persistence-governance.md`
- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/audits/enterprise-ui-acceptance-checklist.md`

**Step 1: Write the failing test**

Manual expectation: the documents still live in mixed root paths.

**Step 2: Run test to verify it fails**

Run: `find docs -maxdepth 2 -type f | sort`
Expected: FAIL to show the desired grouping.

**Step 3: Write minimal implementation**

Move each document into `guides/` or `audits/`.

**Step 4: Run test to verify it passes**

Run: `find docs -maxdepth 2 -type f | sort`
Expected: PASS with the regrouped files.

### Task 3: Remove obsolete docs and local artifacts

**Files:**
- Delete: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/workbench-ui-optimization.md`
- Delete: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/plans/2026-03-05-rd-monitor-design.md`
- Delete: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/plans/2026-03-05-rd-monitor-implementation.md`

**Step 1: Write the failing test**

Manual expectation: the obsolete files still appear in `git status`.

**Step 2: Run test to verify it fails**

Run: `git status --short docs`
Expected: FAIL because the obsolete docs are still present in tracked history.

**Step 3: Write minimal implementation**

Remove the obsolete files from the working tree and index.

**Step 4: Run test to verify it passes**

Run: `find docs -maxdepth 2 -type f | sort`
Expected: PASS without the removed files.

### Task 4: Normalize titles, metadata, and references

**Files:**
- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/docs/README.md`
- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/README.md`
- Modify: `/Users/zcc/MyCTMS/ctms-dev/.worktrees/main/.gitignore`
- Modify: moved docs under `docs/guides/` and `docs/audits/`

**Step 1: Write the failing test**

Manual expectation: old paths are still referenced and several docs use inconsistent headings.

**Step 2: Run test to verify it fails**

Run: `rg -n "docs/(release-checklist|setup-config-api|storage-persistence|auth-session-acceptance|ui/enterprise-ui-acceptance-checklist)" README.md docs backend frontend .github`
Expected: FAIL with old path references.

**Step 3: Write minimal implementation**

Update headings, add concise metadata blocks where useful, write `docs/README.md`, and fix references to the new paths.

**Step 4: Run test to verify it passes**

Run: `rg -n "docs/(release-checklist|setup-config-api|storage-persistence|auth-session-acceptance|ui/enterprise-ui-acceptance-checklist)" README.md docs backend frontend .github`
Expected: PASS with only the new organized paths.