doc-audit

name	doc-audit
description	Audit a single Harness Developer Hub documentation page for accuracy, completeness, and editorial quality. Produces a scored report (pass/fail) and optionally rewrites the page. Triggers: "audit [file-path]", "audit [url]", "doc audit", "check this doc", "score this page", "audit the oldest page in [module]", or any request to evaluate a single documentation page against the Harness quality rubric. Also triggers when the user provides a developer.harness.io URL and asks for feedback or a JIRA ticket. For a full audit that also crawls every sibling page in the section, use doc-section-audit instead.
argument-hint	<file-path | url | module-abbreviation> [--rewrite] [--verify pre | --verify post]
user-invocable	true

Audit a single Harness Developer Hub documentation page for accuracy, completion, and editorial quality. Produces a scored report and optionally rewrites the page automatically.

For a full audit that also crawls and assesses every sibling page in the section, use doc-section-audit instead.

Usage

/doc-audit [file-path | url | module-abbreviation] [--rewrite] [--verify pre | --verify post]

Examples:

• /doc-audit docs/infra-as-code-management/workspaces/cli-integration.md — audit only, generate report
• /doc-audit docs/infra-as-code-management/workspaces/cli-integration.md --rewrite — audit then automatically rewrite if score < 80
• /doc-audit docs/infra-as-code-management/workspaces/cli-integration.md --rewrite --verify post — audit, rewrite, then verify on qa.harness.io
• /doc-audit docs/infra-as-code-management/workspaces/cli-integration.md --verify — rewrite then walk through (defaults to post)
• /doc-audit docs/infra-as-code-management/workspaces/cli-integration.md --verify pre — walk through as-is, self-correct if < 80
• /doc-audit iacm — score the oldest IACM page, no rewrite or walkthrough
• /doc-audit https://developer.harness.io/docs/infrastructure-as-code-management/workspaces/cli-integration --rewrite

Arguments

Parse arguments from the user's message.

Parse three things from the arguments:

Target (required — one of):

• A repo-relative file path (docs/.../*.md) → audit that file directly (primary approach; works for new and unpublished docs)
• A https://developer.harness.io/docs/... URL → derive the local file path, then audit locally; use the URL for optional browser rendering
• A module abbreviation (e.g. iacm, ccm) → find and audit the oldest page in that module
• Nothing → ask the user before proceeding

Rewrite flag (optional):

• --rewrite → after audit, if score < 80, automatically invoke the doc-rewrite skill to apply all fixes
• Omitted → generate audit report and rewrite prompt only, do not automatically rewrite

Verify flag (optional):

• --verify pre → after scoring (before any rewrite), run the live qa.harness.io walkthrough on the original file; self-correct if score < 80
• --verify post → rewrite the file to match the doc-structure-template first, then walk through and self-correct if score < 80
• --verify (no mode) → default to post
• Omitted → no live walkthrough

Flag combinations:

• --rewrite alone: audit → rewrite if fails → done
• --verify alone: audit → verify (no automatic rewrite)
• --rewrite --verify: audit → rewrite if fails → verify
• Neither flag: audit only → report
• Neither flag: audit only → report

--rewrite and --verify are only valid when the target is a file path or URL. If the target is a module abbreviation, reject the combination and ask the user to specify a file path or URL instead.

If --verify is present, warn the user before starting:

"The --verify flag runs a live walkthrough on qa.harness.io. It may pause and ask you to log in — stay at your desk during this step."

Then read .claude/scripts/verify-step.md before executing the verification phase and follow its instructions exactly.

---

Module map

The authoritative module list lives in .claude/scripts/modules.json. Read it when resolving a module abbreviation:

python .claude/scripts/find-oldest-docs.py --list-modules

Excluded — never audit: ff (feature-flags), srm (service-reliability-management), cet (continuous-error-tracking), release-notes.

---

Step 1 — Resolve the target page

A — Local file path (docs/.../*.md) — primary approach: Read the file directly from the repo. Derive the live URL from the module map if the doc is published (strip docs/<REPO-FOLDER>/ and .md, prepend the Base URL). If the doc is new and has no live URL yet, note "New/unpublished — no live URL" in the report and skip browser steps.

Get the last git commit date:

python .claude/scripts/find-oldest-docs.py --git-date <file-path>

Tell the user: "Auditing [FILE-PATH] — last updated [GIT-DATE]. Starting audit…"

B — Direct URL (https://developer.harness.io/docs/...): Derive the local file path by reversing the module map:

• Match the URL prefix to a Base URL entry → get the Repo folder
• Strip the Base URL prefix from the URL path, append .md, prepend docs/<REPO-FOLDER>/
• Example: https://developer.harness.io/docs/infrastructure-as-code-management/workspaces/cli-integration → docs/infra-as-code-management/workspaces/cli-integration.md

Read the local file. Also use the URL for browser rendering where helpful.

Tell the user: "Auditing [FILE-PATH] (from URL). Starting audit…"

C — Module abbreviation:

python .claude/scripts/find-oldest-docs.py docs/<MODULE-FOLDER> --top 1

Take the single result file path. Derive the live URL (strip docs/<REPO-FOLDER>/ and .md, prepend the Base URL). Treat as Case A going forward.

Tell the user: "Oldest page in [MODULE]: [FILE-PATH] — last updated [DATE]. Starting audit…"

---

Step 2 — Determine page type and fetch appropriate template

Read the page file first to assess its type. Check for FAQ first — it is the most specific type.

Page type assessment (check in this order):

• FAQ page if ANY of:

  • sidebar_label: FAQ in frontmatter, OR title contains "FAQ" or "Frequently asked questions" (case-insensitive)
  • Filename is faq.md, ends with -faq.md, or ends with -faqs.md
  • More than 60% of H2 sections contain only <details>/<summary> blocks with no step-by-step prose (legacy detection)

• Best-practices page if ANY of (check this before Instructional/Overview — it is a specific type):

  • title is "Best Practices" or matches "X best practices" (case-insensitive), OR sidebar_label is "Best Practices"
  • best-practices (or best_practices) appears in the frontmatter tags
  • Filename is best-practices.md or ends with -best-practices.md
  • The dominant content is recommendation-oriented: most sections give an imperative recommendation paired with a rationale and a consequence ("if you do not do X, then Y happens"), rather than explaining concepts or walking through a procedure
  • Misclassification check: if a page carries a best-practices title or tag but reads like a feature or overview tour (bare imperatives with no consequence, concept dumps, framework/version matrices), it is mislabeled. Score it against the best-practices rubric and flag in the report that it should either be rewritten to the recommendation + rationale + consequence model or reclassified as Overview. Conversely, a page full of recommendation + consequence advice but labelled Overview or Feature should be flagged for reclassification to Best-practices.

• Instructional/Action page if the dominant content is procedural:

  • Title is action-oriented ("Create", "Configure", "Set up", "Install") AND
  • Contains step-by-step UI navigation ("Select X, then click Y") OR
  • Has sequential procedures users follow verbatim OR
  • Contains API curl examples with specific endpoints and parameters
  • Before you begin may include account access and RBAC permissions

• Informative/Overview page if the dominant content is conceptual:

  • Title is a noun phrase ("OPA Policies", "Workspace Architecture", "Delegate Types") AND
  • Explains concepts, architecture, or "how it works" AND
  • Code examples are illustrative/reference, not step-by-step AND
  • No UI walkthrough or sequential procedures
  • Content is "what/why/how" rather than "do this, then that"

• Hybrid page if BOTH:

  • Contains substantial conceptual sections (architecture, "how it works", reference tables) AND
  • Contains substantial procedural sections (step-by-step UI navigation, API examples, configuration instructions)
  • Common patterns: feature pages that explain what something is, then show how to configure it; reference pages with procedural setup sections

For hybrid pages, score against both templates and use the scoring approach that best fits the dominant content:

• If ≥60% of the page is procedural (UI steps, API calls, configuration walkthroughs) → score as Instructional
• If ≥60% of the page is conceptual (architecture explanations, reference tables, "how it works") → score as Overview
• If roughly equal (40-60% each) → score against both templates, use whichever yields the higher overall score, and note both scores in the report

Once you determine the page type, fetch the appropriate template(s):

For FAQ pages:

cat .cursor/rules/faq-template.mdc

For instructional pages (or hybrid leaning instructional):

cat .cursor/rules/doc-structure-template.mdc

For overview pages (or hybrid leaning overview):

cat .cursor/rules/doc-structure-overview-template.mdc

For best-practices pages:

cat .cursor/rules/doc-structure-best-practices-template.mdc

For balanced hybrid pages, fetch both:

cat .cursor/rules/doc-structure-template.mdc
cat .cursor/rules/doc-structure-overview-template.mdc

Use the selected template(s) as the structural benchmark for the Editorial score.

Report the page type to the user:

• For clear types: "Page type: [FAQ/Best-practices/Instructional/Overview] — using [template name] for scoring."
• For hybrid pages: "Page type: Hybrid ([dominant type] leaning) — [explanation of why]. Using [template name] for scoring."
• For balanced hybrid: "Page type: Hybrid (balanced) — scored against both templates. Using [chosen template] (score: X/100) over [other template] (score: Y/100)."

---

Step 3 — Read and score the page

Read the local file directly:

cat <file-path>

If a live URL exists, optionally use Claude in Chrome to view the rendered page for context — but base all scoring and edits on the local file, not the rendered version.

Score across three dimensions (each starts at 100). Adjust criteria based on page type:

Scoring for FAQ pages

Accuracy (40%): –20 answer contradicts current product behaviour, –15 broken or incorrect code in answer, –10 stale version info in answer, –5 broken links in answers

Completion (30%): –15 <details> body is empty or contains only a link with no context sentence, –10 a category heading has no <details> entries, –10 <FAQ> component used on a page with 10 or more questions, –5 answer is a verbatim copy of an existing doc section that Ask AI would already surface (should be shortened + linked)

Editorial (30%): –15 page does not follow faq-template skeleton (H2 categories + <details>/<summary>), –10 missing/incorrect frontmatter (must include sidebar_label: FAQ, title: FAQ — X, faq tag, description, sidebar_position as multiple of 10), –10 non-site-relative links, –10 missing redirect_from on a moved page, –10 em dashes / bare link text (S-1, S-3), –5 <summary> text does not end with ?, –5 ### or deeper heading found in page body, –5 ## Before you begin, ## Next steps, or ## Troubleshooting section present, –5 link phrasing — see [link], refer to, to learn more (S-2), –5 contractions (S-7), –5 "please" in body (S-5), –5 spelling/grammar

Key differences for FAQ pages:

• No Before you begin, Next steps, or "What will you learn?" sections required — their absence is not penalised
• No Troubleshoot component expected — <details> is the correct pattern
• C-1 (landmark sections) does not apply
• H-2 (gerund headings) does not apply — FAQ categories are noun phrases by design
• The <FAQ> component is allowed only when fewer than 10 questions appear on the page

---

Scoring for Best-practices pages

Best-practices pages are scored against .cursor/rules/doc-structure-best-practices-template.mdc, not the overview or instructional rubric. The defining test is whether every recommendation carries a consequence.

Accuracy (40%): –20 a recommendation contradicts current product behaviour, –15 a stated consequence is wrong or overstated, –10 recommends a deprecated or unsupported approach, –10 stale version or feature info, –5 broken links

Completion (30%): –20 recommendations lack a consequence (the "if you do not do X, then Y" framing is the defining trait — apply this when most entries are bare imperatives), –10 missing key practices a production reader needs, –10 concept, hierarchy, or setup content that belongs on another page and is not routed out, –5 trade-offs presented as benefits only, –5 no Next steps or no links out to the platform controls (RBAC, secrets) the page deliberately omits. Do NOT penalize missing "What you will learn" or missing Troubleshooting — both must be absent.

Editorial (30%): –15 wrong structure (includes a "What you will learn" section, a <Troubleshoot> block, a standalone Troubleshooting or "Limitations and gotchas" section, or a concept dump), –10 feature-tour introduction instead of an advice frame, –10 missing/incorrect frontmatter, –10 non-site-relative links, –10 missing redirect_from, –10 em dashes / bare link text (S-1, S-3), –10 walls of text, –5 link phrasing (S-2), –5 gerund headings (use imperative practice names), –5 "please" (S-5), –5 contractions (S-7), –5 inconsistent bolding, –5 spelling/grammar, –5 slug /docs/docs/ bug

Key differences for best-practices pages:

• Every recommendation states a consequence. Bare imperatives with no rationale or consequence are the primary Completion failure.
• "What you will learn" must be absent — penalize its presence, not its absence.
• Troubleshooting and "Limitations and gotchas" sections must be absent — fold instructive failure modes into a recommendation as its consequence, or route them to the feature page.
• Headings are imperative practice names ("Store state in a remote backend"), so imperative headings are correct here, unlike on overview pages.
• Concept, hierarchy, and platform-level material (RBAC, secret management) is linked out, not reproduced, and surfaced under Next steps.
• Best-practices pages are rare — generally one per module. When auditing one, note whether the module already has another; consolidation or reclassification may be needed (CD and Platform may carry a few scoped exceptions).

---

Scoring for Instructional pages

Accuracy (40%): –20 contradicts UI/behaviour, –15 steps would error, –15 outdated screenshots, –15 broken code, –10 wrong API, –10 stale versions, –10 wrong prerequisites, –5 broken links

Completion (30%): –15 undocumented capabilities, –10 missing prerequisites (account/RBAC), –10 missing troubleshooting, –10 missing config options, –10 no code examples, –10 missing cross-module refs (esp. Platform), –10 no RBAC guidance, –10 missing limitations, –10 incomplete API params, –5 no Next Steps

Editorial (30%): –15 wrong structure (vs template), –10 missing/incorrect frontmatter (must include title, sidebar_label, description, keywords, tags, sidebar_position as multiple of 10), –10 wrong heading case (must be sentence case + imperative; gerund headings such as “Configuring X” are wrong; allow proper nouns: CamelCase words like BigQuery/CloudSQL, words with numbers like Jinja2/OAuth2, acronyms like API/REST/JSON, product names like Kubernetes/Terraform), –10 non-site-relative links, –10 missing redirect_from, –10 em dashes / bare link text — here, click here (S-1, S-3), –5 link phrasing — see [link], refer to, to learn more (S-2), –10 walls of text, –5 inconsistent UI bolding, –5 no intro before lists (S-6), –5 “please” in body (S-5), –5 contractions — don’t, won’t, can’t etc. (S-7), –5 missing Troubleshoot component (T-1) / ## Introduction heading in body (T-2), –5 spelling/grammar, –5 missing callouts, –5 slug /docs/docs/ bug

Scoring for Overview pages

Accuracy (40%): –20 contradicts behavior/concepts, –15 incorrect examples, –15 broken code, –10 wrong API/schema, –10 stale versions, –10 incorrect conceptual explanations, –5 broken links

Completion (30%): –15 missing "What you will learn", –10 incomplete concept explanations, –10 missing reference material (attributes/params), –10 no code examples, –10 missing cross-module refs (esp. Platform), –10 missing architectural context, –10 missing limitations/caveats, –5 no Related concepts/Next steps, –5 light/no prerequisites for knowledge context

Editorial (30%): –15 wrong structure (vs overview template), –10 missing/incorrect frontmatter (must include title, sidebar_label, description, keywords, tags, sidebar_position as multiple of 10), –10 wrong heading case (must be sentence case + descriptive/noun phrases, NOT imperative; allow proper nouns: CamelCase words like BigQuery/CloudSQL, words with numbers like Jinja2/OAuth2, acronyms like API/REST/JSON, product names like Kubernetes/Terraform), –10 non-site-relative links, –10 missing redirect_from, –10 em dashes / bare link text — here, click here (S-1, S-3), –5 link phrasing — see [link], refer to, to learn more (S-2), –10 walls of text, –5 inconsistent bolding, –5 no intro before lists (S-6), –5 “please” in body (S-5), –5 contractions — don’t, won’t, can’t etc. (S-7), –5 missing Troubleshoot component (T-1) / ## Introduction heading in body (T-2), –5 spelling/grammar, –5 missing callouts, –5 slug /docs/docs/ bug

Key differences for overview pages:

• Before you begin is optional/lightweight (knowledge context only, NOT account/RBAC)
• "What you will learn" section is required
• Headings should be descriptive/noun phrases, NOT imperative verbs
• Troubleshooting/FAQs are optional
• End section is "Related concepts" or "Learn more" (not necessarily "Next steps")

---

Scoring for Hybrid pages

When a page is classified as Hybrid, apply adjusted scoring rules that account for cross-template characteristics:

Hybrid pages (Instructional leaning — ≥60% procedural):

• Score using Instructional template rules above
• Do NOT penalize for having "What you will learn" section (common in hybrids)
• Do NOT penalize for having conceptual "How it works" sections with noun phrase headings alongside imperative procedural headings
• Reduce penalty for missing detailed RBAC prerequisites if the page is primarily configuration-focused (–5 instead of –10)
• Heading case: Allow mixed heading styles — imperative for procedural sections ("Configure X"), descriptive for conceptual sections ("Configuration levels", "How X works")

Hybrid pages (Overview leaning — ≥60% conceptual):

• Score using Overview template rules above
• Do NOT penalize for having procedural sections with step-by-step instructions (common in hybrids)
• Do NOT penalize for having imperative headings in procedural subsections alongside descriptive headings in conceptual sections
• Reduce penalty for missing "What you will learn" if the page has a strong introductory explanation (–5 instead of –15)
• Heading case: Allow mixed heading styles — descriptive for conceptual sections, imperative for procedural sections

Hybrid pages (Balanced — 40-60% each):

• Score against both templates
• Report both scores in the audit
• Use whichever score is higher as the official score
• In the report, note: "Hybrid (balanced) — Instructional scoring: X/100, Overview scoring: Y/100. Using higher score."
• In the "Page type assessment" section, explain why both templates apply and which characteristics lean which direction

General hybrid scoring adjustments:

• Editorial heading case: For all hybrid pages, allow mixed heading styles without penalty as long as each heading matches its section type (imperative for steps, descriptive for concepts)
• Completion RBAC: Reduce RBAC prerequisite penalty to –5 if the page focuses more on architecture/concepts than account setup
• Structure flexibility: Do not penalize for having both "What you will learn" (overview pattern) and detailed "Before you begin" (instructional pattern) in the same document

Weighted score: (Accuracy × 0.4) + (Completion × 0.3) + (Editorial × 0.3) Pass: ≥ 80. Fail: < 80.

---

Step 4 — Information architecture review

This step is advisory only — findings go into a separate IA section in the report and do not affect the Accuracy/Completion/Editorial score. Some suggestions may intentionally flex the standard template depending on doc type (tutorial vs. feature reference vs. conceptual). Flag opportunities; do not auto-apply them.

4a — Page length

Count the approximate word count or line count of the file.

• If the page exceeds ~800 lines or feels like it requires multiple reads to understand end-to-end, flag it as a candidate for splitting or restructuring.
• Consider whether a long instructional page could be broken into a parent overview + child pages surfaced via the DynamicMarkdownSelector (DMS) — see 4c below.
• Reference: the ECS deployment tutorial is a known example of a page that is too long for a single read; use it as a benchmark for "this needs restructuring".

4b — Platform doc duplication

Scan the page for content that restates or paraphrases Harness Platform documentation — particularly around RBAC, delegates, variables, expressions, secrets, pipelines, connectors, or service accounts.

• If a section largely duplicates a platform doc, flag it: suggest replacing the section with 1–2 sentences of context + a "Go to [platform doc] to [do Y]" link.
• If an entire page duplicates a platform topic (e.g. re-explaining RBAC from scratch), flag it as a candidate for removal with a redirect.

4c — Consolidation: DMS vs tabs vs synced tabs

Assess whether the page, or its siblings (if visible from the section map), could benefit from consolidation using one of the following Docusaurus components:

DynamicMarkdownSelector (DMS)

• Use when multiple full-content child pages exist and a parent "hub" page would improve discoverability and reduce navigation steps.
• Not limited to 4–5 options — uses grid tiles, suited to full context pieces.
• Reference pattern: docs/artifact-registry/get-started/quickstart.md pulls all child get-started pages into one parent via DMS.
• Only recommend DMS when the child pages are genuinely self-contained full guides, not when they are short parallel sections.

Synced tabs

• Use when the same concept or procedure applies across multiple environments, platforms, or providers and the user would likely only need one at a time.
• Example: configuring a connector for AWS / GCP / Azure — the same steps but platform-specific values. Syncing tabs means selecting "AWS" on one page auto-selects it elsewhere.
• Reference: https://docusaurus.io/docs/markdown-features/tabs#syncing-tab-choices

Unsynced tabs

• Use when several related but independent concepts can be shown side-by-side on the same page to reduce vertical scroll and improve scannability.
• Best for shorter sections (2–5 options). If options are longer or more than ~5, prefer DMS.
• Tabs increase engagement by encouraging interaction — a useful secondary benefit but not a primary goal.

If none of the above apply, note "No consolidation opportunity identified."

4d — Tab TOC duplication

Check for duplicate major sections across tabs that create TOC confusion.

If the page uses <Tabs> / <TabItem> components, scan all tab contents for duplicate ## headings — especially:

• ## Before you begin
• ## Troubleshooting
• ## Next steps
• Step headings (e.g., ## Step 1, ## Step 2)

Problem: Docusaurus right-hand TOC shows headings from ALL tabs simultaneously, not just the active tab. When multiple tabs contain the same major sections, the TOC displays duplicates (e.g., Before you begin ×2, Troubleshooting ×2), making it impossible to tell which tab each heading belongs to.

When to flag:

• Two or more tabs each contain ## Before you begin, ## Troubleshooting, or ## Next steps
• Multiple tabs use the same step heading structure (e.g., both have ## Step 1: X, ## Step 2: Y)

Recommended fix — DMS restructuring:

When tabs represent different approaches to the same task (e.g., Terraform vs API provisioning), restructure using DMS:

Parent page (with DMS component):

• Introduction (shared — what the task accomplishes and why)
• DMS component with tiles for each approach
• Troubleshooting (shared — common issues apply to all approaches)
• Next steps (shared — what to do after provisioning)

Child pages (in content/ subdirectory, flat structure):

• File naming: content/<parent-name>-<approach>.md (e.g., content/provision-terraform.md, content/provision-api.md)
• Keep content folder flat — do NOT nest as content/<parent-name>/<approach>.md
• Before you begin (approach-specific — Terraform needs Terraform CLI, API needs curl)
• Step-by-step instructions (unique to each approach)
• No Troubleshooting/Next steps sections (those live on parent only)
• H1 heading allowed (serves as tab section title)

Benefits:

• TOC only shows ONE approach at a time (whichever tile is selected)
• Shared sections aren't duplicated
• Before you begin can still differ by approach
• URL structure: parent-page#terraform and parent-page#api

Example flagging:

**Tab TOC duplication detected:**
- Both "Terraform" and "API" tabs contain `## Before you begin`
- Both tabs contain `## Troubleshooting`
- Both tabs contain `## Next steps`

**Impact:** Right-hand TOC shows 6 major sections (Before you begin ×2, Troubleshooting ×2, Next steps ×2), making navigation confusing.

**Recommendation:** Restructure with DMS — shared sections (Intro, Troubleshooting, Next steps) on parent page, approach-specific content (Before you begin, Steps) in child pages at `content/provision-terraform.md` and `content/provision-api.md`.

If no duplicate sections are found across tabs, or the page doesn't use tabs, note: "No tab TOC duplication detected."

---

Step 5 — User confusion gap analysis

This step identifies where readers might get stuck, confused, or lack context to proceed. This is not about accuracy (Step 3 covers that) — it's about usability and clarity.

Read the page as if you're a user encountering this feature for the first time. Flag gaps in these categories:

5a — Missing "how to access/use" context

For overview pages with reference material (attributes, schemas, API endpoints):

• Are there examples showing how to use the items in the reference list?
• Do code examples include explanatory prose before/after?
• Is the input/output structure explained (e.g., "Access these via input.workspace.* in Rego")?

For instructional pages:

• Is the UI path clear? (e.g., "Go to Project Settings > Policies")
• Are prerequisite steps linked? (e.g., if you need a connector first, does it link to how to create one?)

Examples of gaps:

• Attribute list with no example showing input.workspace.provisioner_version
• "Create a policy set" with no link to where/how to do that
• "Use the Harness API" with no endpoint or authentication guidance

5b — Unexplained behavior or outcomes

What happens when X fails or succeeds?

• Policy fails → What happens? (Pipeline stops? Warning? Error message shown?)
• Deployment completes → Where do I see the results?
• Configuration saved → When does it take effect?

Examples of gaps:

• "Policies are evaluated automatically" — but no mention that pipeline fails if policy denies
• "Terraform state is updated" — but no mention of where to view it or what happens on conflict
• Error messages mentioned but no guidance on how to debug them

5c — Missing prerequisite knowledge or links

Does the page assume knowledge the reader might not have?

• OPA/Rego syntax → Should link to OPA documentation
• Terraform plan JSON structure → Should link to Terraform docs or show example structure
• Harness RBAC → Should link to Platform RBAC docs, not re-explain it

Flag when:

• Technical concepts (OPA, Rego, JSON schema) are used without definition or link
• External tool knowledge is required (Terraform, Kubernetes) without reference links
• Harness Platform concepts (connectors, delegates, secrets) are mentioned without linking to Platform docs

5d — Broken or vague links

Check all links in "Related concepts" or "Next steps":

• Do they actually exist? (Run a quick check for broken paths if possible)
• Are they actionable? Good: "Create your first policy" → Bad: "Policy documentation"
• Do they help the user do something vs. just read more?

Examples of gaps:

• Link to /docs/iacm/pipelines/iacm-pipelines (broken — should be /docs/iacm/pipelines/default-pipelines)
• "Learn more about policies" (vague) → "Create policies and policy sets" (actionable)
• Link to generic Platform overview when a specific how-to guide exists

5e — Jargon or abbreviations without explanation

First use of specialized terms should include:

• Brief inline definition, OR
• Link to glossary/concept doc, OR
• Expansion of abbreviation

Flag when:

• IaCM, OPA, RBAC used in intro without expansion (fine later in doc after first use)
• Domain terms like "policy set", "entity type", "evaluation" used without brief definition
• Product-specific jargon ("workspace", "connector") without context for new users

Scoring impact

This step does NOT affect the Accuracy/Completion/Editorial score. However, gaps identified here should be included in the Completion section of the audit report as context-related issues, and in the Structural rewrite plan section with specific fixes.

Think of this as a "usability layer" on top of the technical correctness audit.

---

Step 6 — Write the audit report

Save to .claude/skills/doc-audit/audits/[slug]-audit-YYYYMMDD.md (e.g. auth-403-errors-audit-20260410.md). Use today's date. The folder already exists.

# Audit: [Page Title]

**URL:** [url]
**Last git commit:** [date or "unknown"]
**Audit date:** [today]
**Overall score:** [score]/100 — PASS / FAIL

## Page type assessment

**Type:** [FAQ | Best-practices | Instructional | Overview]
**Template used:** [.cursor/rules/faq-template.mdc | .cursor/rules/doc-structure-best-practices-template.mdc | .cursor/rules/doc-structure-template.mdc | .cursor/rules/doc-structure-overview-template.mdc]

**Rationale:**
[2-3 sentences explaining why this page is categorized as FAQ, Best-practices, Instructional, or Overview. Reference title pattern, content style, and presence/absence of step-by-step procedures or recommendation + consequence framing. For a Best-practices page, also note whether the module already has another best-practices page (rarity check).]

## Scores
| Dimension | Raw | Weight | Weighted |
|---|---|---|---|
| Accuracy | /100 | 40% | |
| Completion | /100 | 30% | |
| Editorial | /100 | 30% | |
| **Total** | | | **/100** |

## Issues found
### Accuracy
### Completion
### Editorial

## User confusion gaps

> Usability issues where readers might get stuck or lack context to proceed.

### Missing "how to access/use" context
[List gaps where the doc shows WHAT but not HOW to use it]

### Unexplained behavior or outcomes
[List gaps where the doc doesn't explain what happens when X succeeds/fails]

### Missing prerequisite knowledge or links
[List assumed knowledge that should be defined or linked]

### Broken or vague links
[List broken links, vague link text, or missing actionable links]

### Jargon without explanation
[List terms/abbreviations that need inline definition or links]

## Structural rewrite plan

## Redirect changes required

## Information architecture

> These are advisory recommendations only. They do not affect the quality score.
> Apply them only if they genuinely improve the user experience for this doc type.

**Page length:** [short / medium / long — flag if >800 lines or clearly too long for one read]

**Platform doc duplication:**
- [Section or concept that duplicates a platform doc — suggest replace with link, or "None identified"]

**Consolidation opportunities:**
| Opportunity | Component | Rationale |
|---|---|---|
| [description] | DMS / Synced tabs / Unsynced tabs / None | [why] |

**DMS candidate:** [Yes — child pages: X, Y, Z / No]
**Tab candidate:** [Yes — options: X, Y, Z / No]

## JIRA ticket description
**Summary:**
**Description:** [HIGH/MEDIUM/LOW issues]
**Acceptance criteria:** [ ] ...
**Labels:** docs-quality, [module], [stale if applicable]
**Effort:** Low / Medium / High

## Rewrite prompt

Copy this prompt into Claude Code or Cursor to apply the suggested changes:

Rewrite the following Harness Developer Hub documentation page to address quality issues identified in an audit. Before making any changes, read these files in order:

1. [.cursor/rules/doc-structure-template.mdc OR .cursor/rules/doc-structure-overview-template.mdc OR .cursor/rules/doc-structure-best-practices-template.mdc — use the template that matches the page type from the audit]
2. .cursor/rules/doc-linking.mdc — link formatting (site-relative paths only)
3. .cursor/rules/doc-slugs-and-redirects.mdc — slug and redirect_from conventions
4. .cursor/rules/doc-move.mdc — redirect requirements if restructuring
5. CLAUDE.md — project-wide conventions (headings, components, frontmatter)

Page to rewrite: [repo-relative file path] Live URL: [full URL] Audit report: .claude/skills/doc-audit/audits/[slug]-audit-YYYYMMDD.md

Page type: [FAQ | Best-practices | Instructional | Overview] — see audit report for rationale

---

ACCURACY FIXES [paste Accuracy issues from audit]

COMPLETION GAPS TO ADDRESS [paste Completion issues from audit]

EDITORIAL FIXES [paste Editorial issues from audit]

USER CONFUSION GAPS TO ADDRESS [paste User confusion gaps from audit — focus on adding missing context, explaining behavior, linking prerequisites, fixing vague links, and defining jargon]

STRUCTURAL REWRITE PLAN [paste Structural rewrite plan from audit]

REDIRECTS REQUIRED [paste Redirect changes required from audit]

---

The rewritten page must satisfy all of the following before you consider it done:

For FAQ pages:

• Follows faq-template.mdc skeleton exactly (frontmatter → 1–2 sentence intro → --- + ## categories → <details>/<summary> Q&A)
• sidebar_label: FAQ, title FAQ — [Feature Name], faq tag present in frontmatter, sidebar_position (multiple of 10)
• Every <summary> ends with ?
• Every <details> body contains at least one full sentence (not just a link)
• No ## Before you begin, ## Next steps, ## Troubleshooting, or ### headings anywhere on the page
• <FAQ> component only used if page has fewer than 10 questions total
• No <Troubleshoot> component

For Best-practices pages:

• Follows doc-structure-best-practices-template.mdc skeleton (frontmatter → advice-frame intro → practice sections with imperative headings → Next steps)
• Every recommendation states a recommendation + rationale + consequence ("if you do not do X, then Y happens")
• No "What you will learn" section, no <Troubleshoot> block, no standalone Troubleshooting or "Limitations and gotchas" section
• No concept dumps (hierarchies, framework/version matrices, "how RBAC works") — linked out instead
• Trade-offs state the real downside, not benefits only
• Platform-level material (RBAC, secrets) routed to Next steps, not explained in the body

For Instructional pages:

• Follows doc-structure-template.mdc skeleton exactly (frontmatter → intro → prerequisites → step-by-step instructions → Troubleshoot component → Next steps)
• Before you begin include account access, RBAC permissions with specific permission names and links
• All ## and ### headings use sentence case with imperative form ("Create X", "Configure Y")
• component with at least 3 entries for common task errors

For Overview pages:

• Follows doc-structure-overview-template.mdc skeleton exactly (frontmatter → intro → What you will learn → optional lightweight prerequisites → concept sections → optional FAQs → Related concepts)
• "What you will learn" section with 3-5 learning outcomes
• Before you begin is optional/lightweight (knowledge context only, NOT account/RBAC)
• All ## and ### headings use sentence case with descriptive noun phrases ("Policy entity types", "How X works")
• Optional component for conceptual questions

For both page types:

• Frontmatter is complete: title, sidebar_label (Title Case), description, keywords, tags, sidebar_position (multiple of 10); slug does not include a /docs/ prefix
• All internal links use site-relative paths (/docs/...), never full production URLs
• redirect_from added to frontmatter for any URL being superseded
• UI element names are consistently bolded
• No intro is missing before the first list (S-6)
• No em dashes in body (S-1)
• Links use "Go to X to Y" phrasing — no "see [link]", "refer to", "to learn more" (S-2, S-3)
• No "please" anywhere in the body (S-5)
• No contractions — use full forms (do not, cannot, it is, etc.) (S-7)
• Troubleshooting entries use the <Troubleshoot> component, not static ### heading pairs (T-1)
• No ## Introduction heading — intro is plain prose only (T-2)
• Page scores ≥ 80 on a re-audit across Accuracy, Completion, and Editorial dimensions

---

Step 7 — Automatic rewrite (if --rewrite flag present)

Only execute this step if the user provided the --rewrite flag AND the audit score < 80 AND --verify post is NOT also present.

If --rewrite --verify post is provided, skip this step — --verify post handles the rewrite as part of the walkthrough.

If --rewrite was NOT provided:

• Skip this step entirely
• Proceed to Step 8

---

Step 8 — Report back

1. Score + PASS/FAIL
2. Top 3 most impactful issues
3. If the file was rewritten (via --rewrite flag in Step 7), remind the user to review the diff before committing:

   git diff docs/path/to/file.md
   

4. Link: computer://[full path to audit file]
5. JIRA ticket description pasted inline, ready to copy (only if score < 80)

Do not write to any Google Sheet.