docs-vs-code-review

name	docs-vs-code-review
description	Reviews Confluence docs against source code to find inaccuracies and suggest fixes. Use when the user provides a Confluence URL and asks to review, audit, or check if docs are accurate or up to date (GitHub repo not required — inferred from the Confluence space).

Docs vs. Code Review

Your job is to find where the documentation is wrong or incomplete, then produce a concise list of specific edits to make. Only report things that need to change — skip anything that's already accurate. The output should read like a focused edit list, not a code audit.

What you need from the user

You only need:

1. Confluence page URL — the root documentation page to review

GitHub repos are inferred automatically from the Confluence space — do not ask the user for them.

Confluence space	Repos to clone and check
connectpublic or connect	https://github.com/dimagi/commcare-connect (web/backend) AND https://github.com/dimagi/commcare-android (mobile)
commcare or CC	https://github.com/dimagi/commcare-hq

If the space doesn't match any of the above, then ask the user for the repo URL before proceeding.

---

Step 1: Fetch the root page AND every child page

Get the Atlassian cloud ID using getAccessibleAtlassianResources.

Extract the page ID from the URL (the number in the path, e.g. 3215458305).

Then fetch everything under the root:

• getConfluencePage(pageId, contentFormat="markdown") — root page
• getConfluencePageDescendants(pageId, limit=50) — find all child pages
• getConfluencePage for each child page — read them all

This is important: the user wants every page under the root reviewed, not just the root page itself. Make a list of all pages you've fetched before moving to the code, so you can systematically check each one.

As you read, note the specific claims each page makes — exact error messages, column names, icon descriptions, navigation steps, character limits, permission rules, and what happens when an action is taken.

---

Step 2: Clone and read the relevant code

Using the repos inferred from the Confluence space (see table above), clone shallowly:

git clone --depth=1 https://github.com/ORG/REPO.git /tmp/REPO

Find files that implement the documented features. The most useful files to check:

File	What to look for
models.py	Field names, max_length, status choices, defaults
views.py	Navigation after actions, permission decorators, side effects
forms.py	Validation logic, exact error message strings
tasks.py	SMS/push notification content
tables.py	Column labels, icon CSS classes (especially color), tooltip text
Import files (visit_import.py etc.)	Exact required CSV column names — often wrong in docs
utils/flags.py	Flag string identifiers

Use grep to find specific behavior across all cloned repos:

grep -rn "term" /tmp/REPO --include="*.py" | grep -v migration | grep -v test
# For mobile (commcare-android), also check .kt and .java files:
grep -rn "term" /tmp/commcare-android --include="*.kt" --include="*.java"

Common gotchas worth checking on every review:

• CSV import column names: check the actual constant values, not display labels (e.g., AMOUNT_COL = "payment amount", not "Amount")
• Icon colors: search for CSS class (e.g., is it text-orange-600 or text-red-600?)
• SMS/notification content: find the actual template string
• Status values: check the TextChoices class for real string values
• Rate limits: search timedelta near the relevant view
• Revoke/undo actions: what fields are actually cleared vs. retained?
• "Not found" re-check logic: does the code retry before giving up, vs. what the docs imply?

---

Step 3: Produce the edit list

For each page you reviewed, report only the things that need to change. Skip anything correct.

Structure the output as two sections:

Section A — Inaccurate or Misleading Content

Things where the docs say something wrong or incomplete compared to the code. Order by severity — break things first, then confusing things, then minor wording issues.

Use this format for each item:

---

[High/Medium/Low] Page: [Page name] — [Short title of issue]

[Quote the exact text that's wrong]

Change to: [Exact replacement text, or clear description of what to add/remove]

(Code: file.py — one-line explanation of what the code actually does)

---

Keep it tight. The code reference is just enough to justify the change — a filename and one sentence, not a walkthrough. Don't explain what you checked and found to be correct.

Section B — Documentation Quality Gaps

For pages missing required sections per the Connect Documentation Process. Be brief — one line per gap.

Required sections each page should have: Feature Summary, Usage Overview, Screenshots with accompanying text (the support bot can't read images), Behavior Details/Edge Cases, Version & Last Updated Date.

Best practices to flag if missing:

• No info panel at top explaining purpose and user personas
• Screenshots without text descriptions (support bot can't interpret images)
• No step-by-step instructions
• No FAQs for complex features

Format: **Page: [Name]** — Missing: [list what's absent]. Recommendation: [one sentence]

---

Scope

Cover every page under the root. If you find more than ~10 items in Section A, prioritize the ones that would cause a user to do something wrong (wrong column names, wrong navigation, wrong constraints) over minor wording issues.