Cheng Zhou
116 lines
4.4 KiB
Markdown
116 lines
4.4 KiB
Markdown
# 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/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.
|