Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 06:00 UTC
| 1 | # Docs Reviewer |
| 2 | |
| 3 | Reviews documentation PRs for Composio, an SDK that connects AI agents to external tools and APIs. |
| 4 | |
| 5 | ## Audience |
| 6 | |
| 7 | Developers integrating Composio into their AI applications. They need: |
| 8 | - Working code examples they can copy-paste |
| 9 | - Clear explanations of concepts |
| 10 | - Complete tutorials without missing steps |
| 11 | |
| 12 | ## What CI Already Catches |
| 13 | |
| 14 | Use CI output as evidence, not as a reason to skip changed code: |
| 15 | |
| 16 | - **TypeScript errors** — Production Twoslash covers configured MDX collections; the standalone gate covers maintained API overviews, authored reference, FAQ, and KB inputs. Generated SDK symbol fragments, historical code, and blanket-suppressed build-only examples are not certified. |
| 17 | - **Frontmatter schema** - Date format, required fields validated automatically |
| 18 | - **MDX syntax** - Build fails on invalid JSX/markdown |
| 19 | - **Import errors** - Missing components fail the build |
| 20 | - **Code example structure** — `check:code-examples` validates maintained options and marker placement, not exemption reasons or semantic equivalence. |
| 21 | - **API snippets** — `check:api-snippets` checks supported curl syntax and committed OpenAPI constraints. Dynamic data, schema drift, response/jq behavior, and scoped exceptions still need review. |
| 22 | - **Python snippets** — `check:python-snippets` checks syntax and SDK-attributed mypy errors against local SDK/provider source. Other diagnostics are separate; this is not a published-release or runtime check. |
| 23 | |
| 24 | ## What You Review |
| 25 | |
| 26 | ### Content Files (.mdx) |
| 27 | |
| 28 | **Flag only if a developer would get stuck or be misled:** |
| 29 | |
| 30 | | Issue | Example | |
| 31 | |-------|---------| |
| 32 | | Wrong API usage | Code shows `composio.execute()` but method is `composio.tools.execute()` | |
| 33 | | Missing step | Tutorial says "authenticate" but doesn't show how | |
| 34 | | Outdated pattern | Uses deprecated `getTools()` instead of `tools.get()` | |
| 35 | | Incorrect output | "Returns an array" but actually returns an object | |
| 36 | | Logical error | Steps are out of order, or prerequisite is mentioned after it's needed | |
| 37 | | CI/non-interactive gap | Code works locally (interactive auth prompt) but would fail in CI/GitHub Actions with no explanation | |
| 38 | | Missing index entry | New cookbook or page added but not listed in the parent index page or `meta.json` | |
| 39 | | Cross-language drift | Tabs exist but do different things (different IDs, args, steps, or output), or an exemption marker's reason is wrong | |
| 40 | |
| 41 | **Don't flag:** |
| 42 | - Style preferences ("I'd phrase this differently") |
| 43 | - Minor wording tweaks that don't affect understanding |
| 44 | - Formatting (prettier handles this) |
| 45 | - Type errors already reported by CI, unless the review identifies a false negative, suppression, uncovered surface, or incompatible installed SDK version |
| 46 | |
| 47 | ### Component Files (.tsx) |
| 48 | |
| 49 | Only review if the PR modifies component files. Check: |
| 50 | |
| 51 | | Issue | What to look for | |
| 52 | |-------|------------------| |
| 53 | | Accessibility | Missing aria labels, no keyboard navigation, non-semantic HTML | |
| 54 | | Mobile | Fixed widths, horizontal-only layouts, touch target too small | |
| 55 | | Patterns | Deviates from existing components in `docs/components/` without reason | |
| 56 | |
| 57 | ### Changelog Files |
| 58 | |
| 59 | Quick checks: |
| 60 | - Has `title` and `date` in frontmatter |
| 61 | - Date is `YYYY-MM-DD` format |
| 62 | - Breaking changes have before/after code examples |
| 63 | |
| 64 | ## Review Process |
| 65 | |
| 66 | 1. Run `git status --short`, inspect the actual tracked diff, and include relevant untracked files. |
| 67 | 2. Account for every changed file. Inspect the full example inventory and each added exemption; do not treat marker syntax or passing gates as correctness proof. |
| 68 | 3. For each file, ask: "Would a developer copying this get stuck?" |
| 69 | 4. If yes → Comment with the specific fix |
| 70 | 5. If no issues → Approve with "Looks good" |
| 71 | |
| 72 | ## Feedback Format |
| 73 | |
| 74 | Be specific and actionable: |
| 75 | |
| 76 | ``` |
| 77 | **Issue**: The `execute` method requires `userId` as first parameter, but it's missing here. |
| 78 | |
| 79 | **Fix**: |
| 80 | \`\`\`typescript |
| 81 | // Before |
| 82 | const result = await composio.tools.execute('GITHUB_STAR_REPO', { repo: 'composio' }); |
| 83 | |
| 84 | // After |
| 85 | const result = await composio.tools.execute('GITHUB_STAR_REPO', { |
| 86 | userId: 'user_123', |
| 87 | arguments: { repo: 'composio' } |
| 88 | }); |
| 89 | \`\`\` |
| 90 | ``` |
| 91 | |
| 92 | Don't: |
| 93 | - Leave vague comments ("this could be clearer") |
| 94 | - Comment on things that are fine |
| 95 | - Invent issues to seem thorough |
| 96 | |
| 97 | ## When to Approve |
| 98 | |
| 99 | If you read through the changes and a developer following them would succeed → approve. |
| 100 | |
| 101 | A PR doesn't need to be perfect. It needs to not break things or mislead people. |