Documentation Fix Checklist

Documentation Fix Checklist

CODITECT Core - Action Items from Quality Report

Generated: December 22, 2025 Target Completion: January 15, 2026 Current Health Score: 37/100 → Target: 90/100

---

Week 1: Critical Fixes (Dec 23-29, 2025)

Priority 1.1: Fix Customer Documentation Links (docs/)

Effort: 4-6 hours | Owner: Documentation Librarian

• Update docs/guides/CIRCULAR-FIX-DETECTION-GUIDE.md

  • Fix link: RECOVERY-MANAGER-GUIDE.md → create or remove
  • Fix link: ORCHESTRATOR-GUIDE.md → create or remove
  • Fix link: ../../internal/testing/TESTING-GUIDE.md → update path

• Update docs/guides/COMPONENT-ACTIVATION-GUIDE.md

  • Fix link: MULTI-SESSION-INTEGRATION-GUIDE.md → create or remove
  • Fix link: ../00-ai-agent-guides/COMPONENT-DISCOVERY.md → update path

• Update docs/guides/THINKING-BUDGET-SYSTEM.md

  • Fix link: COST-OPTIMIZATION.md → create or remove
  • Fix link: AGENT-DEVELOPMENT-GUIDE.md → create or remove
  • Remove false positives (code snippets parsed as links)

• Update docs/reference/AGENT-FRONTMATTER-THINKING-CONFIG.md

  • Fix link: ../guides/COST-OPTIMIZATION.md → create or remove
  • Fix link: ../guides/AGENT-DEVELOPMENT-GUIDE.md → create or remove

• Update docs/workflows/HEALTHCARE-INDUSTRY-WORKFLOWS.md

  • Fix link: ../guides/WORKFLOW-VALUE-GUIDE.md → create or remove

Total Files to Update: 5 Total Broken Links to Fix: ~67

Priority 1.2: Create Missing Major READMEs

Effort: 6-8 hours | Owner: Documentation Librarian

• internal/deployment/README.md

  • Overview section
  • List LOCAL-DEVELOPMENT-DOCKER.md
  • List AGENT-SELECTION-CI-CD-DEPLOYMENT.md
  • Quick links section

• internal/testing/README.md

  • Overview of test documentation
  • List test guides
  • Link to test suite documentation

• internal/architecture/system-design/README.md

  • Overview of system design docs (15 files)
  • Categorize by topic
  • Quick reference links

• internal/architecture/database/README.md

  • Overview of database architecture (6 files)
  • List schema documents
  • Link to ADRs

• internal/architecture/multi-tenant/README.md

  • Overview of multi-tenant architecture (5 files)
  • List integration guides
  • Link to relevant ADRs

• internal/research/README.md

  • Overview of research directory
  • Categorize research by topic
  • List major research findings

• internal/project/v2/README.md

  • Overview of epic-based roadmap
  • Link to V2-MASTER-project-plan.md
  • Quick navigation to epics

• docs/reference/README.md (verify completeness)

  • Check all reference docs are linked
  • Add descriptions if missing
  • Verify categorization

• docs/workflows/README.md (verify completeness)

  • Verify WORKFLOW-LIBRARY-INDEX.md is comprehensive
  • Check all workflow docs are linked

Total READMEs to Create/Update: 9

Priority 1.3: Fix ADR Cross-References

Effort: 3-4 hours | Owner: Documentation Librarian

• ADR-001-async-task-executor-refactoring.md

  • Fix: ../../PROJECT-PLAN-EXECUTOR-REFACTORING.md → archive or update
  • Fix: ../../docs/ASYNC-EXECUTOR-STRATEGIC-PLAN.md → update path
  • Fix: ../../docs/ASYNC-EXECUTOR-INTEGRATION-SECTION.md → update path
  • Fix: ../../docs/05-project-planning/project-plan.md → update path
  • Fix: ../../docs/MULTI-AGENT-ARCHITECTURE-BEST-PRACTICES.md → update path

• ADR-003-license-validation-strategy.md

  • Fix: adrs/ADR-002-hybrid-deployment-architecture.md → remove duplicate adrs/
  • Fix: CLOUD-INFRASTRUCTURE-INTEGRATION-ANALYSIS.md → update path
  • Fix: ../../../../../submodules/cloud/... → fix submodule path

• ADR-005-work-item-hierarchy.md

  • Fix: ../../commands/cxq.md → update path to ../../../commands/cxq.md
  • Fix: ../../CODITECT-CORE-STANDARDS/TEMPLATES/... → update paths
  • Remove false positives (code snippets)

• ADR-012-llm-council-pattern.md

  • Fix: ../../../docs/09-research-analysis/llm-council-pattern/ → update to research/

• ADR-013-agent-skills-framework-adoption.md

  • Fix: ../../../docs/09-research-analysis/... → update to research/

• ADR-015-coditect-master-index-system.md

  • Fix submodule paths
  • Fix research directory references

• ADR-020-context-extraction.md

  • Fix: ../../commands/cx.md → update path
  • Fix: ../../scripts/context-db.py → update path
  • Fix: ../../docs/10-special-topics/... → update to guides/

• ADR-021-context-query.md

  • Fix absolute paths to relative paths
  • Remove code snippet false positives

• ADR-024-multi-tenant-platform-architecture.md

  • Fix submodule paths

• ADR-030, 031, 033, 035 (LMS ADRs)

  • Fix: ../../11-training-certification/... → update to docs/training/
  • Remove code snippet false positives

• ADR-040-token-accounting.md

  • Fix command and script paths

• ADR-041-workflow-executor.md

  • Remove code snippet false positives

Total ADRs to Update: ~20 Total Broken Links to Fix: ~89

---

Week 2: Improve Discoverability (Dec 30, 2025 - Jan 5, 2026)

Priority 2.1: Link High-Value Orphans

Effort: 8-10 hours | Owner: Documentation Librarian

Customer Guides (docs/guides/)

• Add to docs/guides/README.md:
  • CIRCULAR-FIX-DETECTION-GUIDE.md (under "QA & Testing")
  • CIRCULAR-FIX-DETECTION-README.md (consolidate with above or remove)
  • QA-SELF-HEALING-LOOP-GUIDE.md (under "QA & Testing")
  • SECURITY-PROFILING-GUIDE.md (under "Security")
  • THINKING-BUDGET-SYSTEM.md (under "Cost Optimization")
  • POST-SESSION-PROCESSING-GUIDE.md (under "Session Management")

Architecture Docs (internal/architecture/)

• Link from internal/architecture/README.md:
  • COMPONENT-CAPABILITY-SCHEMA.md
  • CLOUD-INFRASTRUCTURE-INTEGRATION-ANALYSIS.md
  • HYPER-SCALE-ARCHITECTURE-1M-TENANTS.md

Architecture ADRs (internal/architecture/adrs/)

• Verify adrs/README.md links all 30+ ADRs
  • Check ADR-001 through ADR-015 are linked
  • Check ADR-020 through ADR-024 are linked
  • Check ADR-030 through ADR-038 are linked
  • Check ADR-040, ADR-041 are linked
  • Add ADR-RENUMBERING-PLAN.md

System Design (internal/architecture/system-design/)

• Create system-design/README.md linking:
  • ASYNC-EXECUTOR-architecture.md
  • AUTONOMOUS-AGENT-SYSTEM-DESIGN.md
  • C4-ARCHITECTURE-METHODOLOGY.md
  • CODITECT-CORE-SDD.md
  • MULTI-AGENT-ARCHITECTURE-BEST-PRACTICES.md

Database (internal/architecture/database/)

• Create database/README.md linking:
  • CODITECT-COMPLETE-database-schema.md
  • DATABASE-ARCHITECTURE-PROJECT-INTELLIGENCE.md
  • DATABASE-ARCHITECTURE-UNIFIED.md
  • LMS-database-schema.md

Research (internal/research/)

• Create research/README.md with categories:
  • Anthropic Research (link anthropic-research/)
  • Business Research (link business/)
  • Market Research (link market-research/)
  • LLM Council Pattern (link llm-council-pattern/)
  • Performance Analysis (link performance/)
  • Submodule Management (link submodule-management/)

Total Documents to Link: ~50

Priority 2.2: Create Archive Navigation

Effort: 2-3 hours | Owner: Documentation Librarian

• internal/archive/README.md

  • Explain purpose of archive directory
  • List archived documentation categories
  • Add search tips for historical reference
  • Clarify that archive links are intentionally not maintained

• internal/archive/architecture/README.md

  • Index major archived architecture documents
  • List superseded docs with replacement references

• internal/archive/research/README.md

  • Index major archived research
  • Add timestamps and context

Total Archive READMEs: 3

Priority 2.3: Improve Link Parser

Effort: 4-6 hours | Owner: Developer

• Update scripts/analyze-documentation-links.py:

  • Add code block exclusion (...)
  • Add inline code exclusion (...)
  • Add docstring exclusion ("""...""")
  • Improve anchor detection (#...)
  • Add external link validation (optional)
  • Generate cleaner reports

• Test improvements on sample files

• Re-run analysis and compare results

• Update documentation with new capabilities

Expected Result: Reduce false positives from ~350 to <50

---

Week 3: Complete Navigation (Jan 6-12, 2026)

Priority 3.1: Create Missing CLAUDE.md Files

Effort: 6-8 hours | Owner: Documentation Librarian

• docs/reference/CLAUDE.md

  • Overview of reference documentation
  • When to use vs. guides vs. getting-started
  • List key documents with AI agent context
  • Cross-references to architecture and guides

• internal/deployment/CLAUDE.md

  • Overview of deployment documentation
  • When agents should use deployment docs
  • Key documents for CI/CD and Docker
  • Workflow guidance for deployment tasks

• internal/research/CLAUDE.md

  • Overview of research directory
  • When to reference research vs. implementation docs
  • Key research findings for agents
  • How to navigate research categories

• internal/testing/CLAUDE.md

  • Overview of test documentation
  • When to use testing docs
  • Test suite guidance
  • Quality assurance workflows

• internal/architecture/adrs/CLAUDE.md

  • Overview of ADR system
  • When to create new ADRs
  • How to reference ADRs in decisions
  • ADR numbering and categories

• internal/project/v2/CLAUDE.md

  • Overview of epic-based roadmap
  • When to use v2 vs. plans/ vs. tasklists/
  • Epic structure and sprint planning
  • How to track progress

• internal/project/v2/epics/CLAUDE.md

  • Overview of epic structure
  • How to work with epic tasklists
  • Epic-specific best practices
  • Cross-epic dependencies

• docs/workflows/CLAUDE.md (if needed)

  • Overview of workflow library
  • When to use workflows vs. create custom
  • Workflow selection guidance
  • Industry-specific workflows

Total CLAUDE.md Files: 8

Priority 3.2: Fix Remaining Broken Links

Effort: 6-8 hours | Owner: Documentation Librarian

• Archive References (134 links)

  • Review each archive broken link
  • Replace with "Historical reference - archived" notes
  • Or update paths if file was moved not deleted

• Claude 4.5 Optimization Links

  • Fix links in internal/architecture/claude-4.5-optimization/
  • Update batch summary references
  • Point to archive for historical batches

• Submodule Path References

  • Review cross-submodule links
  • Fix incorrect paths (e.g., submodules/submodules/...)
  • Document cross-submodule linking conventions

• Code Snippet False Positives

  • Review remaining "broken links" that are code
  • Verify parser improvements catch these
  • Document any edge cases

Total Links to Fix: ~250

Priority 3.3: Create Documentation Index

Effort: 4-6 hours | Owner: Documentation Librarian

• docs/DOCUMENTATION-INDEX.md

  • Master index of ALL customer documentation
  • Organized by category (getting-started, guides, reference, workflows, training)
  • Quick navigation matrix
  • Search tips and best practices

• internal/DOCUMENTATION-INDEX.md

  • Master index of ALL contributor documentation
  • Organized by category (architecture, deployment, project, research, testing)
  • Quick navigation matrix
  • Contributor guidance

• Link from root CLAUDE.md and README.md

  • Add prominent links to both indexes
  • Update "Essential Reading" sections

Total Index Files: 2

---

Week 4: Automation (Jan 13-19, 2026)

Priority 4.1: Automated Link Validation

Effort: 8-10 hours | Owner: DevOps

• Create .github/workflows/documentation-quality.yml

  • Run analyze-documentation-links.py on push/PR
  • Report broken links in CI output
  • Fail build if broken links > threshold (e.g., 50)
  • Generate documentation quality badge

• Test CI workflow on feature branch

• Set appropriate thresholds for failures

• Document workflow in internal/deployment/

• Optional: Add pre-commit hook

  • Run quick link check before commit
  • Warn about new broken links
  • Allow override for work-in-progress

Deliverable: Automated documentation quality enforcement

Priority 4.2: Orphan Detection Reports

Effort: 2-3 hours | Owner: Developer

• Create weekly automation for orphan detection

  • Schedule: Every Monday 9am
  • Output: Orphan report to internal/project/reports/
  • Email: Notify documentation team

• Set up dashboard for documentation health

  • Track broken links over time
  • Track orphaned documents over time
  • Track missing READMEs/CLAUDE.md
  • Display health score trend

Deliverable: Continuous documentation quality monitoring

---

Success Criteria

Week 1 Target: Health Score 60/100

• <200 broken links (from 1,419)
• 9 major READMEs created
• Customer documentation fully fixed

Week 2 Target: Health Score 75/100

• <100 broken links
• <200 orphaned documents (from 437)
• Archive navigation complete

Week 3 Target: Health Score 85/100

• <50 broken links
• 8 CLAUDE.md files created
• Documentation indexes created

Week 4 Target: Health Score 90/100

• <30 broken links
• <50 orphaned documents
• Automation in place
• CI/CD enforcing quality

---

Metrics Tracking

Metric	Baseline (Dec 22)	Week 1	Week 2	Week 3	Week 4 Target
Broken Links	1,419	200	100	50	<30
Orphaned Docs	437	400	200	100	<50
Missing READMEs	74	65	40	20	<10
Missing CLAUDE.md	36	36	28	20	<18
Health Score	37/100	60/100	75/100	85/100	90/100

---

Notes

Ongoing Maintenance:

• Run link analyzer weekly
• Review orphaned documents monthly
• Update indexes quarterly
• Health score target: >85/100 sustained

Tools:

• scripts/analyze-documentation-links.py - Main analysis tool
• internal/project/reports/DOCUMENTATION-LINK-ANALYSIS.md - Detailed report
• internal/project/reports/DOCUMENTATION-QUALITY-REPORT.md - Executive summary

Owner: Hal Casteel, CTO Contributors: Documentation Librarian (AI), DevOps Team Review Date: January 20, 2026

---

Last Updated: December 22, 2025