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:

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:

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

Create directory structure (including archive):

mkdir -p docs/{00-context,01-product,02-features,03-logs,04-process,archive}

Move ARCHIVE files first:

mv docs/old-file.md docs/archive/

Move KEEP files to appropriate tiers
For CONSOLIDATE: read both files, merge content into new file, move originals to archive
Remove empty old directories

Step 3: Create Structure

3.1 Create Directories

mkdir -p docs/{00-context,01-product,02-features,03-logs,04-process,archive}

3.2 Required Files

Create these files (see references/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-<name>/ subdirectories as needed
Or flat files for simpler projects

03-logs/ (5 files):

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 CLAUDE.md exists: Add or update documentation pointer:

## 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

# 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:

# [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: references/templates.md

docs-builder