Testing the AI doc pipeline

.claude/commands/density-check.md

@@ -0,0 +1,26 @@
+description: Audit a document for low-information, fillable sentences.
+---
+
+Audit the document at $ARGUMENTS for information density. Identify every sentence or paragraph that does not deliver new, actionable information to the reader.
+
+## What counts as low-density content
+
+* Restatements: sentences that repeat what a heading, previous sentence, or adjacent paragraph already says
+* Throat-clearing: opening sentences that announce what is coming instead of delivering it. "This section describes how to..." "In this guide, you will learn..."
+* Transition filler: sentences whose only purpose is connecting two paragraphs. If removing the sentence does not break the reader's understanding, it is filler.
+* Redundant qualifiers: "very important", "absolutely necessary", "completely optional". The qualifier adds no information the noun does not already carry.
+* UI narration: describing what the reader can already see on screen. "The Save button saves your changes."
+* Defensive hedging: "It should be noted that...", "Keep in mind that...", "Please be aware that...". Strip the hedge and keep the content.
+
+## Output format
+
+For each finding, report on its own line:
+Line [N]: [quoted sentence or phrase]
+Problem: [which low-density pattern it matches]
+Action: [delete / merge with adjacent sentence / replace with: "..."]
+
+End with a summary:
+* Total sentences in document
+* Sentences flagged as low-density
+* Percentage that could be cut or compressed
+* Estimated word count reduction

.claude/commands/review-doc.md

@@ -0,0 +1,53 @@
+description: Structured editorial review against the style guide, findings only.
+---
+
+Review the technical document at $ARGUMENTS against our style guide. Do not rewrite or modify the source text. Provide findings only. Do not invent product behavior.
+
+## Review dimensions
+
+Evaluate each dimension independently. Only flag genuine problems.
+
+### Concision
+Flag sentences using more words than necessary. Setup phrases, hedging language, and redundant qualifiers are the common culprits. Test: can the sentence be shortened without losing meaning?
+
+### Information density
+Flag sentences or paragraphs delivering little or no new information: restatements of what a heading already says, throat-clearing introductions, transition sentences describing what the next paragraph will say.
+
+### Scanability
+Flag:
+* Paragraphs longer than 5 sentences that could be lists
+* Sections with no visual break between dense prose blocks
+* Missing or weak lead sentences that do not orient the reader
+
+### Progressive disclosure
+Flag when information appears before the reader needs it. Background and context follow actionable content, not precede it.
+
+### Action clarity
+For procedural sections, flag instructions that are ambiguous, incomplete, or missing an explicit outcome.
+
+### AI-sounding phrasing
+Flag: "delve into", "it's worth noting", "comprehensive", "robust", "leverage", "seamlessly", "empower", "streamline", "unlock", "harness", "moreover", "furthermore", "take advantage of", "this allows you to", "this enables you to."
+
+### Style guide compliance
+* No em dashes
+* No semicolons
+* No bare demonstrative pronouns
+* Sentence case for all headings
+* Consistent list marker style
+
+## Output format
+
+### Summary
+One paragraph: what the doc covers, whether it meets its goals.
+
+### Findings table
+
+| Severity | Location | Issue | Rule violated | Fix |
+|---|---|---|---|---|
+| Critical/Major/Minor | heading or phrase | description | style rule | one-line fix |
+
+### Top 3 changes for biggest impact
+Format: Outcome → Action.
+
+### Open questions
+Clarifying questions about gaps or ambiguous content.

.claude/commands/revise-doc.md

@@ -0,0 +1,19 @@
+description: Rewrite a passage or file to publication-ready style, in place.
+---
+
+Rewrite the following text to publication-ready technical documentation standard. If $ARGUMENTS is a file path, read that file's content as the text to edit; otherwise treat $ARGUMENTS as the text itself.
+
+Rules:
+* Active voice. Subject performs the action.
+* Sentence case for headings.
+* No em dashes, semicolons, or smart quotes.
+* No bare demonstrative pronouns. Follow "This/These/That/Those" with a noun.
+* No filler: remove "it's worth noting", "please note", "keep in mind", "in order to", "due to the fact that".
+* No AI-sounding language: remove "leverage", "utilize", "streamline", "comprehensive", "robust", "seamlessly".
+* Lead each sentence with its information, not a preamble announcing the information.
+* One idea per sentence. Split compounds.
+* Conditions before instructions: "To X, do Y."
+
+Preserve technical accuracy. Do not invent behavior, parameters, or UI labels not present in the original text.
+
+Text to edit: $ARGUMENTS

.claude/commands/terminology-audit.md

@@ -0,0 +1,30 @@
+description: Audit a document for inconsistent naming of the same concept.
+---
+
+Audit the document at $ARGUMENTS for terminology consistency. Identify every instance where the same concept, feature, component, or action is referred to by different names.
+
+## What to check
+
+* Feature names: Is the same feature called different things in different sections?
+* UI element names: Are buttons, fields, pages, and tabs named consistently?
+* Actions: Is the same user action described with different verbs? "Configure" vs "set up" vs "enable"
+* Technical terms: Are API objects, parameters, and values referred to the same way throughout? "API key" vs "api_key" vs "access token"
+* Roles and actors: "User" vs "admin" vs "account owner" vs "you". Is the audience addressed consistently?
+
+## Output format
+
+### Terminology map
+
+For each concept with inconsistent naming:
+
+| Concept | Terms used | Locations | Recommended term |
+|---|---|---|---|
+| [concept] | [all variants found] | [sections/lines] | [one term to standardize on] |
+
+### Undefined terms
+List any technical terms, acronyms, or jargon used without definition on first occurrence.
+
+### Recommendations
+* Which term to standardize on for each inconsistency
+* Whether any terms need a glossary entry
+* Whether any inconsistencies reflect actual product inconsistencies that need to be escalated

.claude/skills/branch/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: branch
+description: Create a correctly named git branch from a ticket ID before starting any documentation work.
+---
+
+# branch
+
+Create a correctly named git branch from a ticket before starting any documentation work.
+
+## When to use this skill
+
+Run this as the first step when starting work on any ticket. It ensures branch names are consistent, traceable to the ticket, and do not require the writer to manually construct the slug.
+
+## Inputs
+
+* Ticket ID: the full ticket identifier, for example `DOC-1234` or `ISSUE-567`
+
+## Steps
+
+### Step 1: Check the current branch
+
+Run `git branch --show-current`.
+
+If the current branch is not the main branch, stop and tell the writer:
+
+> Cannot create branch: you are currently on `[branch-name]`, not `main`. Switch to `main` first.
+
+Do not proceed until the writer is on the main branch.
+
+### Step 2: Fetch the ticket title
+
+Use your issue tracker integration to fetch the ticket and read its title or summary field. The field name varies by tool: `summary` in Jira, `title` in GitHub Issues and Linear.
+
+### Step 3: Derive the branch name slug
+
+Transform the ticket title into a URL-safe slug:
+
+* Replace spaces with hyphens
+* Remove parentheses, commas, and periods
+* Replace any remaining special characters (except letters, digits, and hyphens) with hyphens
+* Collapse consecutive hyphens into one
+* Preserve original casing
+
+Examples:
+
+| Ticket | Title | Branch name |
+|---|---|---|
+| DOC-1234 | Release notes (June 3, 2024) | `DOC-1234-Release-notes-June-3-2024` |
+| DOC-1189 | Add rate limiting to API reference | `DOC-1189-Add-rate-limiting-to-API-reference` |
+
+### Step 4: Create the branch
+
+```bash
+git checkout -b [TICKET-ID]-[TITLE-SLUG]
+```
+
+Confirm the branch was created and report the full branch name to the writer.
+
+## Output
+
+A new local git branch named `[TICKET-ID]-[TITLE-SLUG]`.
+
+## Rules
+
+* Never create a branch from anything other than the main branch.
+* Never modify the ticket title when deriving the slug. Only apply the transformations in Step 3.

.claude/skills/copyedit-reference/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: copyedit-reference
+description: Grammar, style, and consistency copyedit for reference documentation, parameter tables, and API reference material.
+---
+
+# copyedit-reference
+
+Grammar, style, and consistency copyedit for reference documentation: parameter tables, field descriptions, configuration options, and API reference material.
+
+## When to use this skill
+
+Use this on reference docs that describe parameters, fields, configuration options, or API inputs and outputs. It applies a focused set of rules specific to the challenges of reference material: inconsistent formatting, missing required/optional labels, unclear descriptions, and raw URLs.
+
+## Inputs
+
+* File path of the reference document to review
+
+## Steps
+
+### Step 1: Grammar and spelling check
+
+Check for basic grammar errors, spelling mistakes, and punctuation inconsistencies. Flag each issue with its location.
+
+### Step 2: Code formatting
+
+* Variable names, parameter names, and values that appear inline use code formatting (backticks).
+* Uppercase words (like UUID, ID) do not use backticks unless they are specifically a parameter name in this document.
+* Example values are always code-formatted.
+
+### Step 3: Links
+
+* Every raw URL gets descriptive link text.
+* Link text is the destination page title or a clear description. Do not use "click here," "here," or the raw URL.
+* Internal links use relative paths, not absolute URLs.
+
+### Step 4: Sentences and punctuation
+
+* Every sentence ends with a period, including sentences that end with a link.
+* If a sentence ends with a link, the period comes after the closing link markup.
+* Capitalize the first word after a colon when it introduces a complete sentence.
+
+### Step 5: Word choice
+
+* Write out abbreviations: "for example" not "e.g.," "such as" not "i.e.," "and so on" not "etc."
+* Use "ID" not "id" or "Id."
+
+### Step 6: Capitalization
+
+* Use sentence case for parameter titles, field labels, and action titles.
+* Do not capitalize common nouns unless a vendor requires it (for example, a brand name).
+* Product and feature names follow the project's terminology guide.
+
+### Step 7: Required/optional labels
+
+* Label each parameter as **(Required)**, **(Optional)**, or **(Recommended)**.
+* Labels appear in parentheses at the beginning of the description.
+* Do not use all caps (REQUIRED) or other formatting variations.
+
+### Step 8: Parameter description structure
+
+Where possible, descriptions follow this order:
+
+1. What the parameter does
+1. Format, accepted values, and example inputs
+1. Additional behavior notes or conditions
+1. Link to supporting documentation (if applicable)
+
+### Step 9: Report findings and produce revision
+
+List each issue found with:
+* Location (field name, section, or line number)
+* Problem description
+* Recommended fix
+
+Then provide the full revised text.
+
+## Output
+
+Findings list followed by the complete revised document.
+
+## Example: before and after
+
+**Before:**
+```
+API Key (REQUIRED): The API Key for your account e.g. abc123. You can find this
+in Settings > API Keys. Utilize this to authenticate requests.
+```
+
+**After:**
+```
+`api_key` (Required): Your account API key, used to authenticate requests.
+Format: alphanumeric string. Example: `abc123`.
+To find your key, go to **Settings > API Keys**.
+```
+
+What changed:
+* `api_key` is code-formatted because it is a parameter name
+* "(REQUIRED)" → "(Required)": sentence case, not all caps
+* "e.g." → inline example with code formatting
+* "Utilize" → removed. Description rewritten as direct action.
+* Description follows the structure: what it does → format → where to find it
+
+## Rules
+
+* Preserve technical accuracy while simplifying wording.
+* Do not rewrite descriptions that are technically correct. Only fix language and formatting issues.
+* Do not invent accepted values, defaults, or behaviors.
+* If a description is unclear about what a parameter does, mark it as a gap rather than guessing.