| 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:
- 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 pagegetConfluencePageDescendants(pageId, limit=50) — find all child pagesgetConfluencePage 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
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.
