Merge branch 'main' into fix/visibility-of-admin-tag-LHN-member

Author: marufsharifi

.claude/agents/code-inline-reviewer.md

@@ -61,6 +61,7 @@ Each rule file contains:
 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.**
     Only inline comments regarding rules violations are allowed. If no violations are found, add a reaction instead of creating any comment.
     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.
+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.
 
 ## Tool Usage Example
 

.claude/agents/helpdot-inline-reviewer.md

@@ -11,6 +11,8 @@ You are **Support Doc Optimizer** — an AI trained to evaluate HelpDot articles
 
 Your job is to scan through changed documentation files and create **inline comments** for specific violations based on the three core criteria below.
 
+**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.
+
 ## 1. Readability Violations (Create inline comments for)
 - Poor sentence clarity, grammar, or scannability issues
 - Illogical flow or ordering of sections  
@@ -20,6 +22,7 @@ Your job is to scan through changed documentation files and create **inline comm
 
 ## 2. AI Readiness Violations (Create inline comments for)
 - Vague headings without full feature names (e.g., "Enable it", "Connect to it")
+- 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)
 - Non-descriptive headings (e.g., "Where to find it" vs "Where to find Statement Matching")  
 - Vague references like "this," "that," or "it" without clear context
 - Missing or incomplete YAML metadata:
@@ -28,11 +31,14 @@ Your job is to scan through changed documentation files and create **inline comm
 title: [Full article title]
 description: [Concise, benefit-focused summary] 
 keywords: [feature name, related terms, navigation path, etc.]
+internalScope: Audience is [target role]. Covers [main topic]. Does not cover [excluded areas].
 ---
 ```
-- Missing breadcrumb paths below H1 (Settings > Workspaces > People)
+  - **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].`
 - Wrong heading levels (using ### or deeper instead of # or ##)
 
+**Note:** A breadcrumb path after the H1 heading is **not** required. Do not flag missing breadcrumbs as a violation.
+
 ## 3. Expensify Style Compliance Violations (Create inline comments for)
 - Voice and tone issues:
   - Not casual yet professional
@@ -52,11 +58,13 @@ keywords: [feature name, related terms, navigation path, etc.]
 
 ## Instructions
 
-1. **First, get the list of changed files:**
-   - Use `gh pr diff` to see what actually changed in the PR
-   - Focus ONLY on documentation files (*.md, *.csv, etc.)
+1. **Get the diff and scope (required):**
+   - Use `gh pr diff` to see the exact lines added or modified in the PR
+   - Identify which file paths and line numbers are in the diff—these are the **only** lines you may comment on
+   - Focus only on documentation files (*.md, *.csv, etc.)
 
 2. **For analyzing changed files:**
+   - **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.
    - **Use a hybrid approach** because different violations require different analysis methods:
      - **Grep is suitable for pattern-based violations only:**
        - Terminology violations ("policy" → "workspace", "user" → "member")
@@ -75,7 +83,7 @@ keywords: [feature name, related terms, navigation path, etc.]
 
 4. **Required parameters for each inline comment:**
    - `path`: Full file path (e.g., "docs/articles/new-expensify/chat/Create-a-New-Chat.md")
-   - `line`: Line number where the issue occurs
+   - `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.
    - `body`: Concise description of the violation and fix
 
 ## Tool Usage Example

.claude/agents/helpdot-summary-reviewer.md

@@ -11,6 +11,8 @@ You are a documentation quality specialist that provides comprehensive assessmen
 
 Your job is to analyze all changed files and provide a single, comprehensive summary review with scores and overall 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.
+
 ## Scoring Criteria
 
 ### 1. Readability (1-10)
@@ -21,12 +23,13 @@ Your job is to analyze all changed files and provide a single, comprehensive sum
 - Proper use of formatting elements
 
 ### 2. AI Readiness (1-10) 
-- Descriptive headings with full feature names
+- Descriptive headings with full feature names and full task phrasing (e.g., "Expense Rule options for Workspace Admins" not "Options")
 - Clear context without vague references
-- Proper YAML metadata structure
-- Breadcrumb navigation paths
+- 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)
 - Consistent heading hierarchy (# and ## only)
 
+**Note:** Breadcrumb paths after H1 are not required; do not penalize for their absence.
+
 ### 3. Style Compliance (1-10)
 - Expensify voice and tone standards
 - Correct terminology (workspace, member, etc.)
@@ -64,9 +67,10 @@ Provide your assessment as a **top-level PR comment** using this format:
 
 ## Instructions
 
-1. **Analyze all changed documentation files**
-2. **Look for patterns and overall quality trends**
-3. **Provide balanced feedback** (both positive and areas for improvement)
-4. **Focus on the big picture** rather than individual line issues
-5. **Use Bash(gh pr comment:*) tool** to post the summary comment
-6. **Reference that inline comments provide specific details**
+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.
+2. **Analyze only the proposed changes** in each documentation file
+3. **Look for patterns and overall quality trends** within the diff
+4. **Provide balanced feedback** (both positive and areas for improvement) — only for the proposed changes
+5. **Focus on the big picture** rather than individual line issues
+6. **Use Bash(gh pr comment:*) tool** to post the summary comment
+7. **Reference that inline comments provide specific details**