📚 Documentation Review

📋 Summary

Midshift is unusually heavily documented for a one-developer product: roughly 46,000 words of Markdown across a README, an architecture document, an API reference, a deployment guide, a security policy and a very long working-rules file (CLAUDE.md), plus source code in which about one line in five is a comment. Much of it is candid and useful — the architecture document openly lists what is missing (no error tracker, no tested backups, no review gate before production). However, the documents are written as a running decision log by and for an AI-assisted development workflow, they are dense and hard for a newcomer to navigate, and they have drifted from the code in several places, including facts that matter: how to set up a fresh database, whether a security migration has been applied, and who to contact about a vulnerability. Of 16 specific claims checked against the code, 3 are current, 3 are partly current, 9 have drifted and 1 is an unfilled placeholder. A new team could take the product over, but would need a short, correct onboarding path, an operations runbook and a data-model diagram first.

🎯 Rating

🟡 ●●●○○ 3 / 5 — Adequate (Amber). Coverage is broad and the API reference is near-complete (82 of 83 route files documented), but material drift on onboarding and security facts, contradictions between documents, and the absence of runbooks and incident procedures mean the documentation cannot yet be relied on without verification.

🔍 Findings

1. Inventory

[Observed] Line counts from wc -l; comment counts from the shared cloc facts.

2. Style

• Decision-log narrative. Documents record why things changed, with dates and post-mortems ("Three pushes to main sat red that way on 2026-09-06…", CLAUDE.md:649). This preserves reasoning well but buries current-state facts among history; e.g. the migrations section of CLAUDE.md runs to ~250 lines and lists migrations out of numeric order. [Observed]
• AI-session orientation. CLAUDE.md, AGENTS.md and docs/HANDOVER.md are explicitly instructions to AI coding sessions ("For a session that picks the build up mid-stream", docs/HANDOVER.md:3), including how to publish screenshots to a claude.ai artifact board (docs/HANDOVER.md:62-93). A human team inherits a workflow built around one owner plus AI agents. [Observed]
• Density. Long sentences, private vocabulary ("the door", "the strip", "the board", "the ledger", "planted"), and cross-references by section name. High cost to a newcomer. [Observed]
• Candour. ARCHITECTURE.md §9–10 states plainly: no error tracker, no uptime probe, no SLO, no alerting, backups untested, no review gate between commit and production, no retention for logs. This is a strength for due diligence. [Observed] ARCHITECTURE.md:522-560,505-519

3. Accuracy check (16 claims sampled)

Additional minor drift [Observed]: docs/README.md describes UTM_REFERENCE.md against "today's generateUtm()", which was removed (src/lib/utils.ts:10); .env.example keeps comment headers for retired season/domain variables with no variable beneath; README.md "Provenance" says the repository began 31 August 2026 and SECURITY.md says 2026-09-01, while the audited repository is a single squashed commit of 2026-10-06; ARCHITECTURE.md §11 correctly flags google-auth-library and date-fns as declared but unused (confirmed: no imports in src, scripts, e2e).

Tally (16 claims): current 3 (#2, #3, #16); partly current 3 (#7, #8, #15); drifted 9 (#1, #4, #6, #9, #10, #11, #12, #13, #14); placeholder 1 (#5). Drift clusters in counts and dated status statements, which the documents restate in several places without any check.

4. API documentation completeness

5. Could a new team take over? Gaps in priority order

🧾 Evidence

• wc -l README.md ARCHITECTURE.md CLAUDE.md AGENTS.md SECURITY.md docs/*.md docs/*.txt design/COMPLIANCE.md docs/archive/*.md; wc -w over Markdown docs → 46,219 words.
• Route diff: find src/app/api -name route.ts (83) vs paths extracted from docs/API.md with grep -o '/api/[^]*'andcomm → one undocumented (/cap`), two documented-as-retired.
• grep -rl "canEditArea\|canApprove" src/app/api | wc -l → 23; canEditCampaign → 14.
• cat vercel.json → two crons. cat .github/workflows/ci.yml → !cancelled() on each gate.
• grep -oiE 'create table …' supabase/baseline.sql | sort -u | wc -l → 44; head -25 supabase/baseline.sql (inconsistent 001–090/001–078/058 statements).
• ls e2e/journeys/chain-*.spec.ts | wc -l → 21; ls e2e/journeys/*.spec.ts | wc -l → 25.
• grep -n ratio_w supabase/baseline.sql src -r; src/lib/ad-frame.ts:64-82.
• grep -rln "SpeechRecognition" src → ask-sheet.tsx.
• grep -oE '20[0-9]{2}-[0-9]{2}-[0-9]{2}' CLAUDE.md | wc -l → 61.
• Path existence check over every backticked src/…, scripts/…, docs/… path in the five main docs: all resolve except retired src/lib/plugin-auth.ts (correctly described as gone).

⚠️ Risks

✅ Recommendations