Skip to main content

Documentation Navigation Fix Checklist

Documentation Navigation Fix Checklist

Purpose: Actionable checklist to fix documentation navigation gaps Based on: NAVIGATION-ANALYSIS-REPORT.md (December 7, 2025) Goal: Reduce orphan rate from 57.3% to <30%, improve cross-linking to 50%

Week 1: Create Missing Category READMEs​

Priority 1: Critical Missing READMEs​

  • Create 02-user-guides/README.md

    • Link all 8 user guides (COMPONENT-ACTIVATION-GUIDE, USER-BEST-PRACTICES, USER-TROUBLESHOOTING, etc.)
    • Organize by: Getting Started, Daily Operations, Advanced Workflows, Troubleshooting
    • Add "Quick Links" section for frequently accessed guides
    • Include "When to Read" guidance for each document
    • Cross-reference to 01-getting-started/ for onboarding

  • Create 05-deployment/README.md

    • Link LOCAL-DEVELOPMENT-DOCKER.md
    • Link CI-CD-DEPLOYMENT-GUIDE.md
    • Link AGENT-SELECTION-CI-CD-DEPLOYMENT.md
    • Organize by: Local Development, CI/CD Automation, Production Deployment
    • Add prerequisites section
    • Include troubleshooting links

  • Populate 03-technical-specifications/README.md

    • Link PHASE-2C-IMPLEMENTATION-SUMMARY.md
    • Link SLASH-COMMAND-PIPELINE.md
    • Link AGENT-LLM-BINDINGS-GUIDE.md
    • Organize by: API Specs, Implementation Details, Integration Contracts
    • Add quick reference section

  • Populate 05-implementation-guides/README.md

    • Link all 19 implementation guides
    • Organize subdirectories: hooks/, privacy/, processes/, safety/, standards/
    • Add cross-references to 02-architecture/ docs
    • Include "Getting Started with Implementation" section

  • Populate multi-agent-reference/README.md

    • Link AGENT-INDEX.md (all agents)
    • Link COMPONENT-REFERENCE.md (all components)
    • Link COMPLETE-INVENTORY.md
    • Link slash-commands/SLASH-COMMANDS-REFERENCE.md
    • Link SKILLS-REFERENCE.md
    • Create "Quick Start: Finding the Right Agent/Command" section

  • Populate 08-training-certification/README.md

    • Link USER-TRAINING-PATHWAYS.md
    • Link templates/WELCOME-EMAIL-NEW-CUSTOMERS.md
    • Organize by: Learning Pathways, Certification Programs, Templates
    • Add skill level guidance (Beginner/Intermediate/Advanced)

  • Populate 09-special-topics/README.md

    • Link deduplication/DEDUPLICATION-SYSTEM-MASTER.md
    • Link memory-context/MEMORY-CONTEXT-COMPLETE.md
    • Link memory-context/MEMORY-CONTEXT-GUIDE.md
    • Link submodule-management/ docs (3 guides)
    • Link legacy/README-EDUCATIONAL-FRAMEWORK.md
    • Organize by topic with clear descriptions

  • Populate 07-research-analysis/market-research/README.md

    • Link GENAI-CONTEXT-MEMORY-MARKET-RESEARCH.md
    • Link any other market research documents
    • Organize by: Industry Research, Competitive Analysis, Market Sizing

Week 2: Create Subdirectory CLAUDE.md Files​

AI Agent Context Files (10 critical categories)​

  • Create 01-getting-started/CLAUDE.md

    • Purpose: First-time setup and onboarding for AI agents
    • When to use: Agent helping new user setup, onboarding workflows
    • Key documents: USER-quick-start.md, DEVELOPMENT-SETUP.md, quick-starts/
    • Common workflows: Setup assistance, troubleshooting installation

  • Create 02-architecture/CLAUDE.md

    • Purpose: System design and architectural decision context
    • When to use: Architecture questions, technical trade-offs, ADR creation
    • Key documents: ARCHITECTURE-OVERVIEW.md, ADRs, SOFTWARE-DESIGN-DOCUMENT
    • Common workflows: Creating ADRs, architecture validation, design reviews

  • Create 02-user-guides/CLAUDE.md

    • Purpose: Daily operational workflows and best practices
    • When to use: User asking "how do I...?" questions
    • Key documents: USER-BEST-PRACTICES.md, workflow guides, troubleshooting
    • Common workflows: Component activation, session processing, git sync

  • Create 03-technical-specifications/CLAUDE.md

    • Purpose: Implementation details and API contracts
    • When to use: Developer implementing features, API integration
    • Key documents: API specs, implementation summaries, bindings guide
    • Common workflows: API implementation, integration testing

  • Create 04-project-planning/CLAUDE.md

    • Purpose: Project planning, task tracking, and progress reporting
    • When to use: Project management tasks, status updates, planning
    • Key documents: PROJECT-STATUS.md, ROADMAP-AND-CHANGELOG.md
    • Common workflows: Status reporting, roadmap updates, task tracking

  • Create 05-deployment/CLAUDE.md

    • Purpose: Deployment automation and infrastructure setup
    • When to use: Setting up dev environment, CI/CD, production deployment
    • Key documents: Docker guides, CI/CD guides, deployment strategies
    • Common workflows: Local setup, pipeline creation, production deploys

  • Create 05-implementation-guides/CLAUDE.md

    • Purpose: Implementation standards and patterns
    • When to use: Implementing new features, following standards, code reviews
    • Key documents: Standards docs, hooks guides, safety/privacy patterns
    • Common workflows: Standards compliance, hook implementation, code review

  • Create multi-agent-reference/CLAUDE.md

    • Purpose: Agent, command, and skill discovery
    • When to use: Selecting agents, finding commands, activating components
    • Key documents: AGENT-INDEX.md, COMPONENT-REFERENCE.md, slash commands
    • Common workflows: Agent selection, component activation, capability discovery

  • Create 07-research-analysis/CLAUDE.md

    • Purpose: Research findings, competitive intelligence, analysis reports
    • When to use: Strategic questions, market research, competitive analysis
    • Key documents: Market research, code reviews, completion reports
    • Common workflows: Research synthesis, competitive analysis, audits

  • Create 08-training-certification/CLAUDE.md

    • Purpose: User training and skill development
    • When to use: Onboarding new users, training programs, skill assessment
    • Key documents: Training pathways, templates
    • Common workflows: User onboarding, training plan creation, skill tracking

100% Orphaned Categories (Critical)​

  • Create research/README.md

    • Link GDPVal/00-index.md (and 6 sub-documents)
    • Link az1.ai-coditect-A16Z-response/ (3 documents)
    • Link 05-formatted-transcript-ai-startup-era.md
    • Link 2510.04374v1.md (research paper)
    • Organize by: Academic Research, Strategic Analysis, Market Intelligence
    • Add context for founders/executives

  • Create generative-ui/README.md

    • Link research/original-research/ARTIFACTS/Opus4.5-artifacts-v1/ (11 docs)
    • Link analysis and implementation docs
    • Organize by: Research Findings, Technical Analysis, Implementation Guides
    • Add "Historical Context" note (past research archive)

  • Create examples/README.md

    • Link session-exports/sessions/ (session files)
    • Link session-exports/checkpoints/ (28 checkpoint files)
    • Organize by: Session Examples, Checkpoint Examples
    • Add "Learning from Examples" section for AI agents
    • Include usage guidance (when to reference examples)

High Orphan Categories (Reduce 60%+ to <30%)​

  • Improve 04-project-planning/README.md (currently 14 links, 30 orphaned)

    • Link all master plans (MASTER-FILE-ACTION-PLAN.md, etc.)
    • Link sprint plans from sprints/ subdirectory
    • Link migration plans from migration-plans/ subdirectory
    • Link stakeholder presentations
    • Link strategic/ subdirectory docs
    • Target: 40+ links, <10 orphaned

  • Create 04-project-planning/strategic/README.md

    • Link PRODUCTION-READINESS-ROADMAP.md
    • Link vision and strategy documents
    • Organize for executive/founder audience

  • Improve 07-research-analysis/README.md (currently 5 links, 32 orphaned)

    • Link anthropic-research/ subdirectory docs
    • Link claude-code-automation/ docs
    • Link audits/, code-reviews/, completion-reports/ subdirectories
    • Link gap-analysis/ docs
    • Link session-summaries/
    • Target: 30+ links, <10 orphaned

  • Populate 09-implementation-summaries/README.md (currently 4 links, 8 orphaned)

    • Link all Claude.md rewrite summaries
    • Link README rewrite summaries
    • Link GIT-WORKFLOW-SYSTEM-COMPLETE.md
    • Organize by: Documentation Projects, System Implementations
    • Target: 10+ links, 0-2 orphaned

  • Improve claude-4.5-optimization/README.md (currently 6 links, 12 orphaned)

    • Link all batch summaries (batches/CLAUDE-4.5-UPDATE-BATCH-*.md)
    • Link testing/ subdirectory reports
    • Link templates/
    • Organize batches chronologically
    • Target: 20+ links, <3 orphaned

Week 4: Enhance Cross-Linking​

  • Add to major user guides (8 documents in 02-user-guides/)

    • COMPONENT-ACTIVATION-GUIDE.md → link to AGENT-INDEX.md, COMPONENT-REFERENCE.md
    • USER-BEST-PRACTICES.md → link to troubleshooting, workflow guides
    • GIT-WORKFLOW-AUTOMATION-GUIDE.md → link to git-workflow/ docs
    • JSONL-SESSION-PROCESSING-GUIDE.md → link to examples/
    • MULTI-SESSION-INTEGRATION-GUIDE.md → link to memory-context guides
    • Add "See Also" section to each guide

  • Add to architecture documents

    • ARCHITECTURE-OVERVIEW.md → link to specific ADRs
    • ADRs → link to related ADRs, implementation guides
    • SOFTWARE-DESIGN-DOCUMENT → link to technical specs

  • Add to project planning documents

    • PROJECT-STATUS.md → link to ROADMAP-AND-CHANGELOG.md, completion reports
    • Batch summaries → link to next/previous batch, testing reports

  • Add to research documents

    • Market research → link to competitive analysis, strategic docs
    • Code reviews → link to architecture docs, standards

Create Topic-Based Cross-Reference Maps​

  • Create docs/TOPIC-INDEX.md (optional)
    • Group documents by topic: Git, Sessions, Components, Architecture, etc.
    • Provide multiple entry points per topic
    • Include "Start here" recommendations per topic

Month 2: Create Specialized Navigation​

Audience-Specific Entry Points​

  • Create docs/EXECUTIVE-SUMMARY.md

    • Link vision and strategy documents
    • Link market research and competitive analysis
    • Link PROJECT-STATUS.md and ROADMAP-AND-CHANGELOG.md
    • Include metrics: 370 docs, all components, production status
    • Highlight competitive advantages and market positioning
    • Add investor-ready documentation package

  • Create docs/DEVELOPER-PORTAL.md

    • Link DEVELOPMENT-SETUP.md
    • Link architecture docs and ADRs
    • Link implementation guides and standards
    • Link technical specifications
    • Include "First Contribution" quickstart
    • Add code review checklist

  • Create docs/USER-PORTAL.md

    • Link USER-quick-start.md
    • Link all user guides
    • Link troubleshooting and FAQ
    • Link training pathways
    • Organize by skill level: Beginner, Intermediate, Advanced
    • Include support information

  • Create scripts/check-orphaned-docs.py

    • Detect orphaned documents
    • Output orphan report with categorization
    • Integration with CI/CD for regression detection

  • Create scripts/check-broken-links.py

    • Validate all relative markdown links
    • Report broken links with source file and target
    • Pre-commit hook integration

  • Create scripts/generate-cross-reference-map.py

    • Extract all links from all documents
    • Build topic-based link graph
    • Output cross-reference visualization

  • Create scripts/update-readme-toc.py

    • Auto-generate README table of contents
    • Maintain consistent TOC format across READMEs
    • Update last-modified dates automatically

CI/CD Integration​

  • Add pre-commit hook for link validation

    • Run check-broken-links.py before commit
    • Reject commits with broken links
    • Add to .git/hooks/pre-commit

  • Add GitHub Action for documentation quality

    • Run orphan check on PR creation
    • Comment on PR with navigation report
    • Block merge if critical navigation gaps introduced

  • Create automated navigation report

    • Generate navigation report weekly
    • Track orphan rate and cross-linking rate over time
    • Alert if metrics degrade

Success Metrics Tracking​

Weekly Check-ins​

  • Week 1 metrics:

    • Orphan rate: ___% (target: <50%)
    • Empty READMEs fixed: ___ / 6
    • Missing READMEs created: ___ / 2

  • Week 2 metrics:

    • Subdirectory CLAUDE.md created: ___ / 10
    • Orphan rate: ___% (target: <45%)

  • Week 3 metrics:

    • 100% orphaned categories fixed: ___ / 3
    • Orphan rate: ___% (target: <35%)

  • Week 4 metrics:

    • Cross-linking rate: ___% (target: >40%)
    • Orphan rate: ___% (target: <30%)

Final Goal (End of Month 1)​

  • Orphan rate <30% (currently 57.3%)
  • Cross-linking rate >50% (currently 26.5%)
  • All category READMEs Grade B+ or better (currently 4 Grade A, 9 Grade D-F)
  • 10+ subdirectory CLAUDE.md files (currently 0)
  • Broken links remain 0 (currently 0)

Usage Instructions​

  1. Copy this checklist to your project tracking system
  2. Assign tasks to documentation-librarian agent or team members
  3. Check off items as completed
  4. Run analyze_navigation.py weekly to track progress
  5. Update metrics in "Success Metrics Tracking" section
  6. Adjust priorities based on user feedback and analytics

Checklist Created: December 7, 2025 Based on: NAVIGATION-ANALYSIS-REPORT.md Total Tasks: 80+ actionable items Estimated Effort: 4 weeks (1 person) or 2 weeks (2 people)

For questions or implementation support:

  • Review NAVIGATION-ANALYSIS-REPORT.md for detailed context
  • Review NAVIGATION-ASSESSMENT-SUMMARY.md for executive overview
  • Run analyze_navigation.py to check current status
  • Contact documentation-librarian agent for generation assistance