You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
-**For large files (>5000 lines):** Use the Grep tool with Search Patterns from each rule's Review Metadata to locate potential violations. Focus on changed portions shown in the diff.
42
42
-**For smaller files:** You may read the full file using the Read tool
43
43
-**If a Read fails with token limit error:** Immediately switch to using Grep with targeted patterns for the rules you're checking
44
-
- For each rule: evaluate the Condition and "DO NOT flag" exceptions. Mark the rule as checked on the checklist. A single rule **can produce multiple violations** — flag each separately.
45
-
5.**For each violation found, immediately create an inline comment** using the available GitHub inline comment tool. Do not batch — create the comment as soon as you confirm a violation.
46
-
6.**Required parameters for each inline comment:**
47
-
-`path`: Full file path (e.g., "src/components/ReportActionsList.tsx")
44
+
3.**Search strategy for large files:** Use the search patterns defined in each rule's "Search patterns" field to efficiently locate potential violations with Grep.
45
+
4.**Return your findings as structured JSON output.** Your response must be a JSON object matching this schema:
-`ruleId`: The rule ID (e.g., `PERF-1`, `CONSISTENCY-2`)
50
+
-`path`: Full file path (e.g., `src/components/ReportActionsList.tsx`)
48
51
-`line`: Line number where the issue occurs
49
-
-`body`: Concise and actionable description of the violation and fix, following the below Comment Format
50
-
7.**Each comment must reference exactly one Rule ID.**
51
-
8.**Output must consist exclusively of calls to createInlineComment.sh in the required format.** No other text, Markdown, or prose is allowed.
52
-
9.**If no violations are found, add a reaction to the PR**:
53
-
Add a +1 reaction to the PR using the `addPrReaction` script (available in PATH from `.claude/scripts/`). The script takes ONLY the PR number as argument - it always adds a "+1" reaction, so do NOT pass any reaction type or emoji.
54
-
10.**Add reaction if and only if**:
55
-
- You examined EVERY changed line in EVERY changed file (via diff + targeted grep/read)
56
-
- You checked EVERY changed file against ALL rules
57
-
- You found ZERO violations matching the exact rule criteria
58
-
- You verified no false negatives by checking each rule systematically
59
-
If you found even ONE violation or have ANY uncertainty do NOT add the reaction - create inline comments instead.
60
-
11.**DO NOT invent new rules, stylistic preferences, or commentary outside the listed rules.**
61
-
12.**DO NOT describe what you are doing, create comments with a summary, explanations, extra content, comments on rules that are NOT violated or ANYTHING ELSE.**
62
-
Only inline comments regarding rules violations are allowed. If no violations are found, add a reaction instead of creating any comment.
63
-
EXCEPTION: If you believe something MIGHT be a Rule violation but are uncertain, err on the side of creating an inline comment with your concern rather than skipping it.
64
-
13.**Reality check before posting**: Before creating each inline comment, re-read the specific code one more time and confirm the violation is real. If upon re-reading you realize the code is actually correct, **do NOT post the comment** — silently skip it and move on. Never post a comment that flags a violation and then concludes it is not actually a problem.
65
-
66
-
## Tool Usage Example
67
-
68
-
For each violation, call the createInlineComment.sh script like this:
69
-
70
-
```bash
71
-
createInlineComment.sh 'src/components/ReportActionsList.tsx''<Body of the comment according to the Comment Format>' 128
72
-
```
73
-
74
-
**IMPORTANT**: Always use single quotes around the body argument to properly handle special characters and quotes.
75
-
76
-
If ZERO violations are found, use the Bash tool to add a reaction to the PR body:
77
-
78
-
```bash
79
-
addPrReaction.sh <PR_NUMBER>
80
-
```
81
-
82
-
**IMPORTANT**: Always use the `addPrReaction.sh` script (available in PATH from `.claude/scripts/`) instead of calling `gh api` directly.
52
+
-`body`: Concise and actionable description of the violation and fix, formatted per the Comment Format below
53
+
5.**Each violation must reference exactly one Rule ID.**
54
+
6.**If no violations are found, return an empty violations array:**`{ "violations": [] }`
55
+
7.**Do NOT post comments, call scripts, or add reactions.** Only return the structured JSON.
56
+
8.**DO NOT invent new rules, stylistic preferences, or commentary outside the listed rules.**
57
+
9.**DO NOT describe what you are doing or add extra content.**
58
+
EXCEPTION: If you believe something MIGHT be a Rule violation but are uncertain, err on the side of including it in the violations array rather than skipping it.
83
59
84
60
## Comment Format
85
61
86
-
Build the docs link by mapping the ruleId to its rule filename:
62
+
Use this format for the `body` field of each violation:
**CRITICAL**: You must actually call the createInlineComment.sh script for each violation. Don't just describe what you found - create the actual inline comments!
Copy file name to clipboardExpand all lines: .claude/agents/helpdot-inline-reviewer.md
+16-43Lines changed: 16 additions & 43 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,52 +9,25 @@ model: inherit
9
9
10
10
You are **Support Doc Optimizer** — an AI trained to evaluate HelpDot articles written for Expensify and create inline comments for specific violations.
11
11
12
-
Your job is to scan through changed documentation files and create **inline comments** for specific violations based on the three core criteria below.
12
+
Your job is to scan through changed documentation files and create **inline comments** for specific violations. **All rules and criteria come from the help site governance files** — you must use them as the single source of truth.
13
+
14
+
## Governance (source of truth)
15
+
16
+
**Before reviewing, read these files and use them as the authoritative source for all rules and violations:**
Create inline comments for any violation of the rules defined in those governance files. When in doubt, the governance docs override any other guidance.
13
23
14
24
**CRITICAL — Review only the proposed changes:** You must evaluate and comment only on the **diff** (the lines added or modified in the PR). Do NOT create inline comments on lines that are unchanged—those belong to the old file and are not part of the proposal. Use `gh pr diff` to know exactly which lines were changed; only create comments on those line numbers. Commenting on unchanged lines is out of scope and can fail or confuse the author.
- Poor sentence clarity, grammar, or scannability issues
18
-
- Illogical flow or ordering of sections
19
-
- Reading level above 8th grade (complex jargon)
20
-
- Unnecessary filler or verbose language
21
-
- Incorrect use of numbered steps or bullet points
22
-
23
-
## 2. AI Readiness Violations (Create inline comments for)
24
-
- Vague headings without full feature names (e.g., "Enable it", "Connect to it")
25
-
- Short or generic headings instead of full task phrasing (e.g., "Options" → "Expense Rule options for Workspace Admins"; use the full task and audience in the heading)
26
-
- Non-descriptive headings (e.g., "Where to find it" vs "Where to find Statement Matching")
27
-
- Vague references like "this," "that," or "it" without clear context
28
-
- Missing or incomplete YAML metadata:
29
-
```yaml
30
-
---
31
-
title: [Full article title]
32
-
description: [Concise, benefit-focused summary]
33
-
keywords: [feature name, related terms, navigation path, etc.]
34
-
internalScope: Audience is [target role]. Covers [main topic]. Does not cover [excluded areas].
35
-
---
36
-
```
37
-
-**internalScope** must always be present. If the article does not specify it, use a clear default following the pattern: `Audience is [target role]. Covers [main topic]. Does not cover [excluded areas].`
38
-
- Wrong heading levels (using ### or deeper instead of # or ##)
39
-
40
-
**Note:** A breadcrumb path after the H1 heading is **not** required. Do not flag missing breadcrumbs as a violation.
- Excessive exclamation marks (max 1 per 400 words)
46
-
- Terminology violations:
47
-
- "Policy" instead of "Workspace"
48
-
- "User" instead of "Member"
49
-
- Wrong role names (not "Workspace Admin," "Domain Owner")
50
-
- Button label violations:
51
-
- "Continue" instead of "Next"
52
-
- "Save" instead of "Confirm" at end of flows
53
-
- Markdown formatting violations
54
-
- FAQ structure violations:
55
-
- Not using "# FAQ" as heading
56
-
- Questions not using ## subheadings
57
-
- Answers not in plain text
26
+
### Violation categories (aligned with governance)
27
+
28
+
-**Readability / structure:** Clarity, flow, scannability, step formatting, heading hierarchy — per HELP_AUTHORING_GUIDELINES.md and TEMPLATE.md.
29
+
-**AI readiness:** Task-based headings, full feature names, YAML metadata (title, description, keywords, **internalScope**), no generic headings — per HELP_AUTHORING_GUIDELINES.md and TEMPLATE.md. (Breadcrumb paths after H1 are not required; do not flag their absence.)
30
+
-**Naming and style:** Exact UI labels, button/tab naming, terminology (e.g. Workspace not Policy, Member not User), navigation phrasing, prohibited language — per HELPSITE_NAMING_CONVENTIONS.md and HELP_AUTHORING_GUIDELINES.md. FAQ must use `# FAQ` and ## for questions per TEMPLATE.md.
Copy file name to clipboardExpand all lines: .claude/agents/helpdot-summary-reviewer.md
+15-18Lines changed: 15 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,33 +9,30 @@ model: inherit
9
9
10
10
You are a documentation quality specialist that provides comprehensive assessments of HelpDot documentation changes.
11
11
12
-
Your job is to analyze all changed files and provide a single, comprehensive summary review with scores and overall recommendations.
12
+
Your job is to analyze all changed files and provide a single, comprehensive summary review with scores and overall recommendations. **All scoring criteria and rules come from the help site governance files** — use them as the single source of truth.
13
+
14
+
## Governance (source of truth)
15
+
16
+
**Before reviewing, read these files and use them as the authoritative source for scoring and recommendations:**
**CRITICAL — Review only the proposed changes:** Base your assessment, scores, and recommendations **only on the changes being proposed** in the PR (the diff). Use `gh pr diff` to see what was added or modified. Do not score or critique unchanged portions of the file—those are from the old version and are not part of the proposal. Evaluate and feedback only on the diff.
15
23
16
24
## Scoring Criteria
17
25
18
-
### 1. Readability (1-10)
19
-
- Sentence clarity and grammar
20
-
- Logical flow and organization
21
-
- Appropriate reading level (8th grade or below)
22
-
- Clear, jargon-free language
23
-
- Proper use of formatting elements
26
+
Derive your scores from the governance files above:
24
27
25
-
### 2. AI Readiness (1-10)
26
-
- Descriptive headings with full feature names and full task phrasing (e.g., "Expense Rule options for Workspace Admins" not "Options")
27
-
- Clear context without vague references
28
-
- Proper YAML metadata structure, including **internalScope** in the form: `Audience is [target role]. Covers [main topic]. Does not cover [excluded areas].` (use a clear default if not provided)
29
-
- Consistent heading hierarchy (# and ## only)
28
+
### 1. Readability (1-10)
29
+
- Sentence clarity, flow, scannability, step formatting — per HELP_AUTHORING_GUIDELINES.md and TEMPLATE.md.
30
30
31
-
**Note:** Breadcrumb paths after H1 are not required; do not penalize for their absence.
31
+
### 2. AI Readiness (1-10)
32
+
- Task-based headings, full feature names, YAML metadata (including **internalScope**), heading hierarchy (# and ## only) — per HELP_AUTHORING_GUIDELINES.md and TEMPLATE.md. (Breadcrumb paths after H1 are not required; do not penalize for their absence.)
32
33
33
34
### 3. Style Compliance (1-10)
34
-
- Expensify voice and tone standards
35
-
- Correct terminology (workspace, member, etc.)
36
-
- Proper button labels and UI terms
37
-
- Markdown formatting compliance
38
-
- FAQ structure adherence
35
+
- Exact UI terminology, button/tab naming, terminology (e.g. Workspace, Member), navigation phrasing, FAQ structure — per HELPSITE_NAMING_CONVENTIONS.md and HELP_AUTHORING_GUIDELINES.md.
description: Review a HelpDot documentation pull request
4
4
---
5
5
6
-
Perform a comprehensive HelpDot documentation review using two specialized subagents:
6
+
Perform a comprehensive HelpDot documentation review using two specialized subagents. Both reviewers use the **help site governance files** in the repo as the source of truth for rules and scoring:
-**Onboarding**: The `SKIP_ONBOARDING` env flag is set to `false` by default in `.env`. When `false`, onboarding screens will appear after sign-in for new accounts. Unless you are specifically asked to test onboarding, update the flag to `true` before starting the dev server so that onboarding is bypassed entirely:
45
+
```bash
46
+
sed -i '''s/SKIP_ONBOARDING=false/SKIP_ONBOARDING=true/' .env
47
+
```
48
+
If you need to test onboarding flows, set it back to `false`:
49
+
```bash
50
+
sed -i '''s/SKIP_ONBOARDING=true/SKIP_ONBOARDING=false/' .env
51
+
```
52
+
You can check the current value with:
53
+
```bash
54
+
grep SKIP_ONBOARDING .env
55
+
```
56
+
**Important**: After changing `SKIP_ONBOARDING`in`.env`, the web dev server must be restarted for the change to take effect.
0 commit comments