From de8b4265ded87164cfd77d1f9005adf8f7d24be5 Mon Sep 17 00:00:00 2001 From: Stephanie Elliott Date: Thu, 12 Mar 2026 18:12:05 -1000 Subject: [PATCH 1/7] Updated to strip out static prompt and point to governance files instead. --- .claude/agents/helpdot-inline-reviewer.md | 59 ++++++---------------- .claude/agents/helpdot-summary-reviewer.md | 33 ++++++------ .claude/commands/review-helpdot-pr.md | 10 ++-- 3 files changed, 38 insertions(+), 64 deletions(-) diff --git a/.claude/agents/helpdot-inline-reviewer.md b/.claude/agents/helpdot-inline-reviewer.md index 5de3fa1984b98..333d4f38fe31b 100644 --- a/.claude/agents/helpdot-inline-reviewer.md +++ b/.claude/agents/helpdot-inline-reviewer.md @@ -9,52 +9,25 @@ model: inherit You are **Support Doc Optimizer** — an AI trained to evaluate HelpDot articles written for Expensify and create inline comments for specific violations. -Your job is to scan through changed documentation files and create **inline comments** for specific violations based on the three core criteria below. +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. + +## Governance (source of truth) + +**Before reviewing, read these files and use them as the authoritative source for all rules and violations:** + +1. **docs/HELPSITE_NAMING_CONVENTIONS.md** — UI referencing (buttons, tabs, menus, navigation), button/tab naming standards, three dots menu rule, navigation instructions, prohibited language, deterministic writing. +2. **docs/HELP_AUTHORING_GUIDELINES.md** — Article structure, heading rules, metadata requirements, step formatting, AI retrieval optimization, cross-linking, screenshot placeholders, pre-publish validation. +3. **docs/TEMPLATE.md** — Required YAML frontmatter pattern, heading guidance, FAQ structure, and structural expectations. + +Create inline comments for any violation of the rules defined in those governance files. When in doubt, the governance docs override any other guidance. **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 -- Reading level above 8th grade (complex jargon) -- Unnecessary filler or verbose language -- Incorrect use of numbered steps or bullet points - -## 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: -```yaml ---- -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]. ---- -``` - - **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 - - Excessive exclamation marks (max 1 per 400 words) -- Terminology violations: - - "Policy" instead of "Workspace" - - "User" instead of "Member" - - Wrong role names (not "Workspace Admin," "Domain Owner") -- Button label violations: - - "Continue" instead of "Next" - - "Save" instead of "Confirm" at end of flows -- Markdown formatting violations -- FAQ structure violations: - - Not using "# FAQ" as heading - - Questions not using ## subheadings - - Answers not in plain text +### Violation categories (aligned with governance) + +- **Readability / structure:** Clarity, flow, scannability, step formatting, heading hierarchy — per HELP_AUTHORING_GUIDELINES.md and TEMPLATE.md. +- **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.) +- **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. ## Instructions diff --git a/.claude/agents/helpdot-summary-reviewer.md b/.claude/agents/helpdot-summary-reviewer.md index e596e56601105..0e4376639ae0f 100644 --- a/.claude/agents/helpdot-summary-reviewer.md +++ b/.claude/agents/helpdot-summary-reviewer.md @@ -9,33 +9,30 @@ model: inherit You are a documentation quality specialist that provides comprehensive assessments of HelpDot documentation changes. -Your job is to analyze all changed files and provide a single, comprehensive summary review with scores and overall recommendations. +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. + +## Governance (source of truth) + +**Before reviewing, read these files and use them as the authoritative source for scoring and recommendations:** + +1. **docs/HELPSITE_NAMING_CONVENTIONS.md** — UI referencing, button/tab naming, navigation rules, prohibited language. +2. **docs/HELP_AUTHORING_GUIDELINES.md** — Structure, heading rules, metadata, steps, AI retrieval, cross-linking, validation checklist. +3. **docs/TEMPLATE.md** — YAML frontmatter, heading guidance, FAQ structure. **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) -- Sentence clarity and grammar -- Logical flow and organization -- Appropriate reading level (8th grade or below) -- Clear, jargon-free language -- Proper use of formatting elements +Derive your scores from the governance files above: -### 2. AI Readiness (1-10) -- 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, 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) +### 1. Readability (1-10) +- Sentence clarity, flow, scannability, step formatting — per HELP_AUTHORING_GUIDELINES.md and TEMPLATE.md. -**Note:** Breadcrumb paths after H1 are not required; do not penalize for their absence. +### 2. AI Readiness (1-10) +- 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.) ### 3. Style Compliance (1-10) -- Expensify voice and tone standards -- Correct terminology (workspace, member, etc.) -- Proper button labels and UI terms -- Markdown formatting compliance -- FAQ structure adherence +- 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. ## Output Format diff --git a/.claude/commands/review-helpdot-pr.md b/.claude/commands/review-helpdot-pr.md index e7a5441e3d53b..d132b32647bdb 100644 --- a/.claude/commands/review-helpdot-pr.md +++ b/.claude/commands/review-helpdot-pr.md @@ -3,17 +3,21 @@ allowed-tools: Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),mcp__ description: Review a HelpDot documentation pull request --- -Perform a comprehensive HelpDot documentation review using two specialized subagents: +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: + +- **docs/HELPSITE_NAMING_CONVENTIONS.md** — UI referencing, button/tab naming, navigation +- **docs/HELP_AUTHORING_GUIDELINES.md** — Structure, headings, metadata, AI retrieval, validation +- **docs/TEMPLATE.md** — YAML frontmatter, heading guidance, FAQ structure ## Step 1: Inline Review Use the helpdot-inline-reviewer agent to: - Scan all changed documentation files -- Create inline comments for specific HelpDot rule violations +- Create inline comments for violations of the governance rules above - Focus on line-specific, actionable feedback ## Step 2: Summary Review Use the helpdot-summary-reviewer agent to: -- Analyze the overall quality of all changes +- Analyze the overall quality of all changes using the governance criteria - Provide comprehensive assessment with scoring - Post one top-level PR comment with summary and recommendations From 06b2ee60a0813eb3bf35ed824757f8a9389f6ae6 Mon Sep 17 00:00:00 2001 From: Stephanie Elliott <31225194+stephanieelliott@users.noreply.github.com> Date: Thu, 12 Mar 2026 18:19:29 -1000 Subject: [PATCH 2/7] Create fake-article.md --- .../new-expensify/settings/fake-article.md | 49 +++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 docs/articles/new-expensify/settings/fake-article.md diff --git a/docs/articles/new-expensify/settings/fake-article.md b/docs/articles/new-expensify/settings/fake-article.md new file mode 100644 index 0000000000000..a65bf87d7b692 --- /dev/null +++ b/docs/articles/new-expensify/settings/fake-article.md @@ -0,0 +1,49 @@ +--- +title: Overview of SmartMatch +description: This is used for SEO purposes. +keywords: [smartmatch, expenses] +--- + +# Introduction + +This article explains how to enable it and where to find the options. Users in a Policy can turn on this feature. + +--- + +## Overview + +SmartMatch helps you match expenses. Navigate to the area where this is configured. Find the setting under your Policy settings. + +--- + +## Setup + +1. Go to the section for Workspace settings. +2. Open the More menu next to the expense. +3. Click Save to apply your changes. +4. At the end of the flow, click "Save" to finish. +5. For more info, [click here](/articles/new-expensify/workspaces/Workspaces.md). + +--- + +# Options + +You can configure various options here. Go to Settings and select Chat to get started. On mobile, tap the three dots to open the menu. + +--- + +### Where to find it + +If you can't see it, go to the section and look for the options button. Learn more at https://help.expensify.com/articles/new-expensify/workspaces/Workspaces.md. + +--- + +# FAQ + +### How do I enable SmartMatch? + +Turn on the toggle in your Policy. Click Continue when you're done with each step. + +### Why can't I see it? + +You might not be a Workspace Admin. Read more for details. From 1eb82eef1db96c383805a231c04fb052ebfed185 Mon Sep 17 00:00:00 2001 From: Stephanie Elliott Date: Thu, 12 Mar 2026 18:32:59 -1000 Subject: [PATCH 3/7] Adjust workflows so they run on my article --- .github/workflows/claude-review.yml | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.github/workflows/claude-review.yml b/.github/workflows/claude-review.yml index 98578ba2bc78c..9c4b8e210e37e 100644 --- a/.github/workflows/claude-review.yml +++ b/.github/workflows/claude-review.yml @@ -46,8 +46,7 @@ jobs: code: - 'src/**' docs: - - 'docs/**/*.md' - - 'docs/**/*.csv' + - 'docs/**' - name: Add claude utility scripts to PATH run: | From b734d73a1ac8be161f8873b584f96857f58b31e7 Mon Sep 17 00:00:00 2001 From: Stephanie Elliott Date: Thu, 12 Mar 2026 18:45:31 -1000 Subject: [PATCH 4/7] Change test to run on my file --- .github/workflows/claude-review.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/claude-review.yml b/.github/workflows/claude-review.yml index 9c4b8e210e37e..d5503d11236fb 100644 --- a/.github/workflows/claude-review.yml +++ b/.github/workflows/claude-review.yml @@ -6,7 +6,7 @@ permissions: on: pull_request_target: - types: [opened, ready_for_review] + types: [opened, ready_for_review, synchronize] concurrency: group: claude-review-${{ github.event.pull_request.html_url }} From bdc2e3c9ee0ebcbca37e5743fbace04af2f36547 Mon Sep 17 00:00:00 2001 From: Stephanie Elliott <31225194+stephanieelliott@users.noreply.github.com> Date: Thu, 12 Mar 2026 20:00:56 -1000 Subject: [PATCH 5/7] Delete docs/articles/new-expensify/settings/fake-article.md --- .../new-expensify/settings/fake-article.md | 49 ------------------- 1 file changed, 49 deletions(-) delete mode 100644 docs/articles/new-expensify/settings/fake-article.md diff --git a/docs/articles/new-expensify/settings/fake-article.md b/docs/articles/new-expensify/settings/fake-article.md deleted file mode 100644 index a65bf87d7b692..0000000000000 --- a/docs/articles/new-expensify/settings/fake-article.md +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Overview of SmartMatch -description: This is used for SEO purposes. -keywords: [smartmatch, expenses] ---- - -# Introduction - -This article explains how to enable it and where to find the options. Users in a Policy can turn on this feature. - ---- - -## Overview - -SmartMatch helps you match expenses. Navigate to the area where this is configured. Find the setting under your Policy settings. - ---- - -## Setup - -1. Go to the section for Workspace settings. -2. Open the More menu next to the expense. -3. Click Save to apply your changes. -4. At the end of the flow, click "Save" to finish. -5. For more info, [click here](/articles/new-expensify/workspaces/Workspaces.md). - ---- - -# Options - -You can configure various options here. Go to Settings and select Chat to get started. On mobile, tap the three dots to open the menu. - ---- - -### Where to find it - -If you can't see it, go to the section and look for the options button. Learn more at https://help.expensify.com/articles/new-expensify/workspaces/Workspaces.md. - ---- - -# FAQ - -### How do I enable SmartMatch? - -Turn on the toggle in your Policy. Click Continue when you're done with each step. - -### Why can't I see it? - -You might not be a Workspace Admin. Read more for details. From 3230fde882e4893b7e81a6d992f763239483c966 Mon Sep 17 00:00:00 2001 From: Stephanie Elliott <31225194+stephanieelliott@users.noreply.github.com> Date: Thu, 12 Mar 2026 20:06:16 -1000 Subject: [PATCH 6/7] Update claude-review.yml Remove adjustments made for testing --- .github/workflows/claude-review.yml | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/.github/workflows/claude-review.yml b/.github/workflows/claude-review.yml index d5503d11236fb..84196e33b4777 100644 --- a/.github/workflows/claude-review.yml +++ b/.github/workflows/claude-review.yml @@ -6,7 +6,7 @@ permissions: on: pull_request_target: - types: [opened, ready_for_review, synchronize] + types: [opened, ready_for_review] concurrency: group: claude-review-${{ github.event.pull_request.html_url }} @@ -46,8 +46,9 @@ jobs: code: - 'src/**' docs: - - 'docs/**' - + - 'docs/**/*.md' + - 'docs/**/*.csv' + - name: Add claude utility scripts to PATH run: | echo "$GITHUB_WORKSPACE/.claude/scripts" >> "$GITHUB_PATH" From 4a3bcfda998c07d1e5c9d8b7d34122c5b8cf7b98 Mon Sep 17 00:00:00 2001 From: Stephanie Elliott <31225194+stephanieelliott@users.noreply.github.com> Date: Thu, 12 Mar 2026 20:07:05 -1000 Subject: [PATCH 7/7] Update claude-review.yml --- .github/workflows/claude-review.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/claude-review.yml b/.github/workflows/claude-review.yml index 84196e33b4777..98578ba2bc78c 100644 --- a/.github/workflows/claude-review.yml +++ b/.github/workflows/claude-review.yml @@ -48,7 +48,7 @@ jobs: docs: - 'docs/**/*.md' - 'docs/**/*.csv' - + - name: Add claude utility scripts to PATH run: | echo "$GITHUB_WORKSPACE/.claude/scripts" >> "$GITHUB_PATH"