ctms/docs/plans/2026-03-30-docs-reorganization-implementation.md

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.