[docs-audit] Weekly documentation audit — 2026-03-05

[github-actions]

Documentation Audit Report — 2026-03-05

Audited against codebase state as of the current main branch (post-merge of PR #45 on 2026-03-05). 8 documentation files reviewed.

Previous audit: #50 (2026-02-24). Most findings below are recurring from that issue. New items are marked 🆕.

---

Resolved Since Last Audit

• docs/REVERSE_ENGINEERING_ARCHITECTURE.md "Last Updated: December 2025" — date was updated to 2026-02-23 in a commit on 2026-02-23. (Now stale again after 2026-03-05 PR — see Critical section.)

---

Critical (documentation is wrong or references removed code)

• 🆕 CHANGELOG.md: [2.5.0] entry (line 8) is dated 2026-02-23, but PR Pass reverse-engineered business logic into migration/conversion pipeline #45 — which introduced all v2.5.0 features — was merged on 2026-03-05. Per [Keep a Changelog]((keepachangelog.com/redacted), the release date should reflect when the version was released/merged. Fix: Change ## [2.5.0] - 2026-02-23 → ## [2.5.0] - 2026-03-05.

• 🆕 docs/REVERSE_ENGINEERING_ARCHITECTURE.md: After PR Pass reverse-engineered business logic into migration/conversion pipeline #45 (merged 2026-03-05) the file was modified (+45/-7 lines covering business logic persistence, --reuse-re, and dependency mapping), but the header still reads > **Last Updated:** 2026-02-23 and > **Version:** 0.2 (Smart Chunking). The version label is misleading given that v2.5.0 features are now documented here. Fix: Update Last Updated to 2026-03-05 and version to e.g. 0.3 (Business Logic Persistence & Dependency Mapping).

• 🆕 .devcontainer/README.md — Configure AI section lists three wrong environment variable names:

  • AZURE_OPENAI_ENDPOINT → correct name is _MAIN_ENDPOINT
  • AZURE_OPENAI_DEPLOYMENT_NAME → correct names are _CODE_MODEL / _CHAT_MODEL
  • AZURE_OPENAI_API_KEY → correct name is _MAIN_API_KEY

  These names do not match Config/ai-config.local.env or the configuration loading documented in README.md. A developer following the devcontainer README will set the wrong variables and get a silent failure.

• README.md (lines ~164 and ~990): Links to azlogin-auth-guide.md which does not exist anywhere in the repository. Fix: Either create docs/azlogin-auth-guide.md or remove/update the links. (Recurring from #50)

• README.md "Further Reading" section: Two links use paths without the docs/ prefix and will 404:

  • [Smart Chunking Guide](Smart-chuncking-how%20it-works.md) → should be docs/Smart-chuncking-how%20it-works.md
  • [Architecture Documentation](REVERSE_ENGINEERING_ARCHITECTURE.md) → should be docs/REVERSE_ENGINEERING_ARCHITECTURE.md

  (Recurring from #50)

• .devcontainer/README.md: References /workspace/WINDOWS_COMPATIBILITY.md (in the "Additional Resources" section and the Windows Compatibility section) but this file does not exist in the repository. (Recurring from #50)

• .devcontainer/README.md: References .NET 9.0 SDK throughout (What's Included, Build Errors troubleshooting, verification checklist: dotnet --version # Should be 9.0.x), but both CobolToQuarkusMigration.csproj and McpChatWeb/McpChatWeb.csproj target net10.0. (Recurring from #50)

• docs/spec-approach-concept.md: Documents ConversionPlannerAgent, IConversionPlannerAgent, and a Constitution loader — none of which exist in the codebase. The Spec-Driven Migration workflow was explicitly removed in v2.3.0. This file should be deleted or clearly marked as a rejected proposal. (Recurring from #50)

---

Missing (undocumented user-facing features)

• Speed Profile system (TURBO / FAST / BALANCED / THOROUGH, added in v2.4.0): Documented inline in README.md but there is no dedicated deep-dive in docs/ covering env var overrides (CODEX_STAGGER_DELAY_MS, CODEX_MAX_PARALLEL_CONVERSION, CODEX_RATE_LIMIT_SAFETY_FACTOR), the select_speed_profile() function in doctor.sh, or the three-tier complexity scoring system that BALANCED mode relies on. (Recurring from #50)

---

Stale (documentation references that may be outdated)

• docs/smart-chunking-architecture.md (**Last updated**: 2025-02-17): Predates v2.4.0 (2026-02-16) by nearly a year. The MaxParallelConversion setting, the new env var overrides, and the Adaptive Re-Chunking feature added in v2.4.0 are not reflected. (Recurring from #50)

---

Structural (guideline compliance issues)

• docs/Smart-chuncking-how it-works.md: Filename contains a space and a typo ("chuncking" instead of "chunking"). Guidelines require a speaking filename without special characters. Suggestion: rename to docs/smart-chunking-deep-dive.md. (Recurring from #50)

• docs/Smart-chuncking-how it-works.md: Missing required **Last updated**: YYYY-MM-DD header at the top of the file. (Recurring from #50)

• docs/legacy-modernization-flow.md: Missing required **Last updated**: YYYY-MM-DD header. File also has no title or description — it starts directly with a Mermaid diagram. (Recurring from #50)

• docs/spec-approach-concept.md: Missing required **Last updated**: YYYY-MM-DD header. (Recurring from #50)

• docs/REVERSE_ENGINEERING_ARCHITECTURE.md: Date format > **Last Updated:** 2026-02-23 does not follow the required **Last updated**: YYYY-MM-DD convention (wrong capitalisation, colon position, and surrounding > blockquote). (Recurring from #50)

---

Summary

• Total documentation files audited: 8 (README.md, .devcontainer/README.md, CHANGELOG.md, docs/REVERSE_ENGINEERING_ARCHITECTURE.md, docs/Smart-chuncking-how it-works.md, docs/smart-chunking-architecture.md, docs/legacy-modernization-flow.md, docs/spec-approach-concept.md)
• Issues found: 8 critical, 1 missing, 1 stale, 5 structural
• Previously reported issues resolved: 1 (docs/REVERSE_ENGINEERING_ARCHITECTURE.md December 2025 date → 2026-02-23)
• New issues since last audit: 3 (CHANGELOG [2.5.0] date; REVERSE_ENGINEERING_ARCHITECTURE.md stale after PR Pass reverse-engineered business logic into migration/conversion pipeline #45; .devcontainer/README.md wrong env var names)

Generated by Documentation Full Audit

Generated by Documentation Full Audit