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
-
65
-
## Tool Usage Example
66
-
67
-
For each violation, call the createInlineComment.sh script like this:
68
-
69
-
```bash
70
-
createInlineComment.sh 'src/components/ReportActionsList.tsx''<Body of the comment according to the Comment Format>' 128
71
-
```
72
-
73
-
**IMPORTANT**: Always use single quotes around the body argument to properly handle special characters and quotes.
74
-
75
-
If ZERO violations are found, use the Bash tool to add a reaction to the PR body:
76
-
77
-
```bash
78
-
addPrReaction.sh <PR_NUMBER>
79
-
```
80
-
81
-
**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.
59
+
10.**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.
82
60
83
61
## Comment Format
84
62
85
-
Build the docs link by mapping the ruleId to its rule filename:
63
+
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
+13-5Lines changed: 13 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,6 +11,8 @@ You are **Support Doc Optimizer** — an AI trained to evaluate HelpDot articles
11
11
12
12
Your job is to scan through changed documentation files and create **inline comments** for specific violations based on the three core criteria below.
13
13
14
+
**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
16
18
- Illogical flow or ordering of sections
@@ -20,6 +22,7 @@ Your job is to scan through changed documentation files and create **inline comm
20
22
21
23
## 2. AI Readiness Violations (Create inline comments for)
22
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)
23
26
- Non-descriptive headings (e.g., "Where to find it" vs "Where to find Statement Matching")
24
27
- Vague references like "this," "that," or "it" without clear context
25
28
- Missing or incomplete YAML metadata:
@@ -28,11 +31,14 @@ Your job is to scan through changed documentation files and create **inline comm
28
31
title: [Full article title]
29
32
description: [Concise, benefit-focused summary]
30
33
keywords: [feature name, related terms, navigation path, etc.]
34
+
internalScope: Audience is [target role]. Covers [main topic]. Does not cover [excluded areas].
-**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].`
34
38
- Wrong heading levels (using ### or deeper instead of # or ##)
35
39
40
+
**Note:** A breadcrumb path after the H1 heading is **not** required. Do not flag missing breadcrumbs as a violation.
- Use `gh pr diff` to see what actually changed in the PR
57
-
- Focus ONLY on documentation files (*.md, *.csv, etc.)
61
+
1.**Get the diff and scope (required):**
62
+
- Use `gh pr diff` to see the exact lines added or modified in the PR
63
+
- Identify which file paths and line numbers are in the diff—these are the **only** lines you may comment on
64
+
- Focus only on documentation files (*.md, *.csv, etc.)
58
65
59
66
2.**For analyzing changed files:**
67
+
-**Restrict analysis to the diff:** When checking for violations, evaluate only content that appears on added or modified lines. If you read a full file for context, do not create inline comments on line numbers that are not part of the diff.
60
68
-**Use a hybrid approach** because different violations require different analysis methods:
61
69
-**Grep is suitable for pattern-based violations only:**
4.**Required parameters for each inline comment:**
77
85
-`path`: Full file path (e.g., "docs/articles/new-expensify/chat/Create-a-New-Chat.md")
78
-
-`line`: Line number where the issue occurs
86
+
-`line`: Line number where the issue occurs — **must be a line that appears in the PR diff (added or modified)**. Do not use line numbers from unchanged portions of the file.
79
87
-`body`: Concise description of the violation and fix
Copy file name to clipboardExpand all lines: .claude/agents/helpdot-summary-reviewer.md
+13-9Lines changed: 13 additions & 9 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -11,6 +11,8 @@ You are a documentation quality specialist that provides comprehensive assessmen
11
11
12
12
Your job is to analyze all changed files and provide a single, comprehensive summary review with scores and overall recommendations.
13
13
14
+
**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
+
14
16
## Scoring Criteria
15
17
16
18
### 1. Readability (1-10)
@@ -21,12 +23,13 @@ Your job is to analyze all changed files and provide a single, comprehensive sum
21
23
- Proper use of formatting elements
22
24
23
25
### 2. AI Readiness (1-10)
24
-
- Descriptive headings with full feature names
26
+
- Descriptive headings with full feature names and full task phrasing (e.g., "Expense Rule options for Workspace Admins" not "Options")
25
27
- Clear context without vague references
26
-
- Proper YAML metadata structure
27
-
- Breadcrumb navigation paths
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)
28
29
- Consistent heading hierarchy (# and ## only)
29
30
31
+
**Note:** Breadcrumb paths after H1 are not required; do not penalize for their absence.
32
+
30
33
### 3. Style Compliance (1-10)
31
34
- Expensify voice and tone standards
32
35
- Correct terminology (workspace, member, etc.)
@@ -64,9 +67,10 @@ Provide your assessment as a **top-level PR comment** using this format:
64
67
65
68
## Instructions
66
69
67
-
1.**Analyze all changed documentation files**
68
-
2.**Look for patterns and overall quality trends**
69
-
3.**Provide balanced feedback** (both positive and areas for improvement)
70
-
4.**Focus on the big picture** rather than individual line issues
71
-
5.**Use Bash(gh pr comment:*) tool** to post the summary comment
72
-
6.**Reference that inline comments provide specific details**
70
+
1.**Get the diff first:** Use `gh pr diff` to see the exact proposed changes. Your entire assessment (scores, findings, recommendations) must be based only on added or modified lines—not on unchanged content from the old file.
71
+
2.**Analyze only the proposed changes** in each documentation file
72
+
3.**Look for patterns and overall quality trends** within the diff
73
+
4.**Provide balanced feedback** (both positive and areas for improvement) — only for the proposed changes
74
+
5.**Focus on the big picture** rather than individual line issues
75
+
6.**Use Bash(gh pr comment:*) tool** to post the summary comment
76
+
7.**Reference that inline comments provide specific details**
0 commit comments