--- name: docs-builder description: Create or reorganize project documentation with structured /docs hierarchy usage: /docs-builder auto_trigger: false --- # Documentation Architecture Skill Create or reorganize `/docs` following a 5-tier hierarchy: ``` /docs ├── 00-context/ # WHY and WHAT EXISTS RIGHT NOW ├── 01-product/ # WHAT the product must do ├── 02-features/ # HOW features are designed & built ├── 03-logs/ # MEMORY (what changed over time) ├── 04-process/ # HOW to work with this system ├── archive/ # Old/unclear docs preserved here └── README.md # Navigation guide ``` --- ## Step 1: Detect Mode Check if `/docs` exists and has content: ```bash find docs -name "*.md" 2>/dev/null | wc -l ``` - **0 files** → **Fresh Mode** (skip to Step 3) - **1+ files** → **Existing Mode** (continue to Step 2) --- ## Step 2: Existing Mode - Analyze First ### 2.1 Inventory List all markdown files: ```bash find docs -name "*.md" -exec wc -l {} \; | sort -n ``` ### 2.2 Read and Categorize **For each file**, read first 50-100 lines and categorize: | Category | Criteria | Action | |----------|----------|--------| | **KEEP** | Evergreen guides, references, architecture, troubleshooting | Move to appropriate tier | | **CONSOLIDATE** | Duplicate/overlapping content | Merge into one, originals to archive | | **ARCHIVE** | Work logs, status reports, old phase docs, unclear purpose | Move to `/docs/archive/` | ### 2.3 Categorization Heuristics **Likely KEEP/MOVE:** - Filename contains: GUIDE, REFERENCE, HOWTO, ARCHITECTURE, COMMANDS, TROUBLESHOOTING, QUICKSTART - Content: Has TOC, structured sections, explains "how to" or "what is" - Purpose: Teaches something reusable **Likely ARCHIVE:** - Filename contains: REPORT, STATUS, SUMMARY, FIX_, PHASE_, SPRINT_, _LOG, DRAFT, WIP, OLD, TEMP - Filename has dates: 2024-01-15-meeting.md - Located in: archive/, old/, reports/, fixes/, phases/ - Content: Dated entries, task IDs, one-time status updates - Under ~20 lines and looks like placeholder **When uncertain → ARCHIVE** (can always recover later) ### 2.4 Present Plan to User Before making changes, show categorization: ``` KEEP → Move to new structure (X files): - guides/COMMANDS.md → 02-features/cli/COMMANDS.md - reference/CONFIG.md → 04-process/reference/CONFIG.md ... CONSOLIDATE (X groups): - architecture.md + ARCHITECTURE.md → 00-context/system-state.md ... ARCHIVE (X files): - PHASE1_STATUS.md - FIX_SUMMARY_2024.md - reports/old-metrics.md ... ``` **Wait for user approval before proceeding.** ### 2.5 Execute Reorganization 1. Create directory structure (including archive): ```bash mkdir -p docs/{00-context,01-product,02-features,03-logs,04-process,archive} ``` 2. Move ARCHIVE files first: ```bash mv docs/old-file.md docs/archive/ ``` 3. Move KEEP files to appropriate tiers 4. For CONSOLIDATE: read both files, merge content into new file, move originals to archive 5. Remove empty old directories --- ## Step 3: Create Structure ### 3.1 Create Directories ```bash mkdir -p docs/{00-context,01-product,02-features,03-logs,04-process,archive} ``` ### 3.2 Required Files Create these files (see `docs-builder/templates.md` for content): **00-context/** (4 files): - [ ] `blueprint.md` - Overarching project artifact (see below) - [ ] `vision.md` - Product purpose & boundaries - [ ] `assumptions.md` - Constraints, risks, unknowns - [ ] `system-state.md` - What's currently built **01-product/** (1 file): - [ ] `prd.md` - Product requirements **02-features/** (per feature): - [ ] `feature-/` subdirectories as needed - [ ] Or flat files for simpler projects **03-logs/** (5 files): - [ ] `implementation-log.md` - [ ] `decisions-log.md` - [ ] `bug-log.md` - [ ] `validation-log.md` - [ ] `insights.md` **04-process/** (3+ files): - [ ] `dev-workflow.md` - [ ] `definition-of-done.md` - [ ] `llm-prompts.md` **Root:** - [ ] `README.md` - Navigation guide --- ## Step 4: Populate Files ### Content Sources Pull content from: - Project README.md - Package files (package.json, pyproject.toml) - Existing code comments/docstrings - Existing docs being reorganized ### For Existing Mode When moving files: - Update any internal links to match new locations - Merge duplicate content thoughtfully - Preserve useful information, don't just copy-paste --- ## Step 5: Integration **If AGENTS.md exists:** Add or update documentation pointer: ```markdown ## Documentation See `docs/README.md` for full documentation structure. ``` **If KNOWLEDGE_BASE.md exists:** Update to reference new structure with quick links. --- ## Step 6: Validate ```bash # Check structure exists ls -la docs/{00-context,01-product,02-features,03-logs,04-process,archive} # Verify minimum files test -f docs/00-context/blueprint.md && echo "✓ blueprint.md" test -f docs/00-context/vision.md && echo "✓ vision.md" test -f docs/00-context/system-state.md && echo "✓ system-state.md" test -f docs/01-product/prd.md && echo "✓ prd.md" test -f docs/README.md && echo "✓ README.md" # Count files per tier find docs/00-context -name "*.md" | wc -l # >= 4 find docs/03-logs -name "*.md" | wc -l # >= 5 find docs/04-process -name "*.md" | wc -l # >= 3 ``` --- ## Blueprint: The Overarching Project Artifact `docs/00-context/blueprint.md` is the **one and only** high-level project document. It answers: what is this project, what's built, what's planned, where is it headed. **When to create:** Always. blueprint.md is the first file created in 00-context/. It is required for both Fresh and Existing modes. **Content sources:** - Root `README.md` — project identity, purpose, stats - `package.json` / `pyproject.toml` — tech stack, dependencies - Existing docs — features implemented vs planned - Code structure — what modules/packages exist **Structure:** ```markdown # [Project Name] Blueprint ## Identity [What this project IS in 2-3 sentences. Sourced from README.] ## Status | Area | Status | Notes | |------|--------|-------| | [feature/module] | implemented / in-progress / planned | [brief] | ## Architecture [High-level structure: packages, modules, entry points. No ASCII trees — use tables or flat lists.] ## Implemented [What works today. Group by feature area. Be specific.] ## Planned [What's next. Ordered by priority. Include design docs if they exist.] ## Future Direction [Where does this project want to be? North star. 3-5 bullets max.] ## Key Decisions [Major architectural choices already made. Link to decisions-log if it exists.] ``` **Rules for blueprint.md:** - Keep it under 150 lines — it's an overview, not a manual - Update it when features ship or plans change - It is the FIRST document a new contributor or LLM should read - No duplication with vision.md (vision = WHY, blueprint = WHAT + WHERE) --- ## Rules **DO:** - Read files before categorizing (don't guess from filename alone) - Present plan to user before bulk changes - Archive instead of delete - Complete one section before moving to next - Populate files with real content (not empty templates) - Preserve original files in archive when consolidating **DON'T:** - Delete any files (archive instead) - Move files without reading them first - Make bulk changes without user approval - Create empty placeholder files - Skip the analysis phase for existing docs --- ## Success Criteria ✅ Mode correctly detected (fresh vs existing) ✅ For existing: categorization presented and approved ✅ All 5 tier directories created (+ archive) ✅ Minimum files in each tier ✅ Files populated with project-specific content ✅ Archive contains old/unclear docs (not deleted) ✅ docs/README.md with navigation ✅ Validation checks pass --- ## Quick Reference ### Tier Mapping | Old Location | New Location | |--------------|--------------| | guides/, howto/ | 02-features/ or 04-process/ | | reference/, api/ | 04-process/reference/ | | architecture/ | 00-context/ | | commands/ | 02-features/cli/ | | development/ | 04-process/development/ | | troubleshooting/ | 04-process/troubleshooting/ | | reports/, status/, phases/ | archive/ | ### File Templates See: `docs-builder/templates.md`