cd-content-audit

# CD Content Audit Role: worker. This skill validates content files and reports findings. It does not modify files. Validate content pages for structural compliance, front matter correctness, tone and voice, cross-references, and terminology consistency. ## Constraints 1. **Read-only.** Do not modify files. Report findings only. 2. **Be concise.** Output the report and summary. No preambles or per-file narration. 3. **Follow the output format.** Use the structured format below for every audit. 4. **Delegate out-of-scope concerns.** Do not check writing quality (`tech-writing-review`) or glossary linking (`glossary-link`). ## Instructions 1. **Accept file paths or globs as arguments.** If no arguments are given, ask which files to audit. 2. **Read `page-templates.md`** in this skill directory for canonical values and page structures. 3. **Detect page type** from the file path (anti-pattern, symptom, or guide). If the file does not match a known page type, report it and skip. 4. **For each file, run all checks** described below. 5. **Report findings** grouped by file, then by check category. Use severity levels: `ERROR` (must fix), `WARNING` (should fix), `INFO` (awareness only). ## Check Categories ### 1. Structure compliance Compare the file's heading structure against the required template for its page type. Required headings use sentence case and must match the forms below exactly. Report a title-case heading (for example `## What This Looks Like`) as a structure violation. **Anti-pattern pages:** - `## What this looks like` exists - `## Why this is a problem` exists with required H3 subsections in order: - `### It reduces quality` - `### It increases rework` - `### It makes delivery timelines unpredictable` - Zero or more optional H3 subsections - `### Impact on continuous delivery` (must be last H3 under this H2) - `## How to fix it` exists with at least one `### Step N:` subsection. Step headings must not include timeline labels (see the rule in `page-templates.md`) - `## Measuring progress` exists and contains a table - `## Related content` exists and contains at least one link - `{{% pageinfo %}}` block exists after front matter **Symptom pages:** - `## What you are seeing` exists (note lowercase) - `## Common causes` exists with 2-5 H3 subsections - Each H3 under "Common causes" ends with `**Read more:**` followed by a link - `## How to narrow it down` exists with a numbered list **Guide pages:** - `{{% pageinfo %}}` block exists with phase indicator - At least 3 H2 sections exist - `### Step N:` headings must not include timeline labels (see the rule in `page-templates.md`) **Severity:** Missing required sections are `ERROR`. Missing optional elements are `WARNING`. A timeline label in a step heading is a `WARNING` structure violation. ### 2. Front matter validation **Anti-pattern pages:** - `title`: required, non-empty - `ERROR` if missing - `linkTitle`: required, non-empty - `ERROR` if missing - `weight`: required, positive integer - `ERROR` if missing - `category`: required, must be one of 7 canonical values - `ERROR` if missing or invalid - `risk_level`: required, must be one of `critical`, `high`, `medium`, `low` - `ERROR` if missing or invalid - `description`: required, under 160 characters - `ERROR` if missing, `WARNING` if over 160 chars - `tags`: required, array, each from allowed vocabulary of 11 tags - `ERROR` if missing, `WARNING` if tag not in vocabulary **Symptom pages:** - `title`: required - `ERROR` if missing - `linkTitle`: required - `ERROR` if missing - `description`: required, under 160 characters - `ERROR` if missing, `WARNING` if over 160 chars - `tags`: required, array, each from allowed vocabulary - `ERROR` if missing, `WARNING` if tag not in vocabulary - Should NOT have `category` or `risk_level` - `WARNING` if present **Guide pages:** - `title`: required - `ERROR` if missing - `linkTitle`: required - `ERROR` if missing - `weight`: required - `ERROR` if missing - `description`: required, under 160 characters - `ERROR` if missing, `WARNING` if over 160 chars - Should NOT have `category`, `risk_level`, or `tags` - `WARNING` if present ### 3. Cross-references - **Relative links** - For each relative link in the body, check that the target file exists. Severity: `ERROR` if target does not exist. - **"Read more" links** (symptom pages) - Verify they point to files under `anti-patterns/`. Severity: `ERROR` if pointing elsewhere. - **"Related content" links** (anti-pattern pages) - Verify they point to guide pages under the phase sections (`assess/`, `foundations/`, `pipeline/`, `optimize/`, `continuous-deployment/`) or `reference/`. Severity: `WARNING` if pointing to other anti-pattern or symptom pages (these are not wrong but may indicate a missed guide link). - **Under-construction links** - Flag any link to `under-construction/`. Severity: `INFO` (these are intentional drafts, just surface them). - **External links** - Do not validate external URLs, just note their presence. Severity: none. ### 4. Terminology consistency Scan for inconsistent usage within each file: - **"continuous delivery" vs "CD"** - Both are fine, but "Continuous Delivery" (capitalized) mid-sentence is wrong. Only capitalize at the start of a sentence or in a heading. Severity: `WARNING` - **"trunk" vs "main branch"** - Flag if both terms appear in the same file without explanation. Severity: `INFO` - **Endash and emdash** - Flag any `\u2013` (endash) or `\u2014` (emdash) characters. Severity: `ERROR` - **Emoji** - Flag any emoji characters. Severity: `ERROR` ## Output Format For each file, report: ``` ## [file path] Page type: [anti-pattern | symptom | guide] ### Errors (N) - [CHECK_CATEGORY] description of issue (line N) ### Warnings (N) - [CHECK_CATEGORY] description of issue (line N) ### Info (N) - [CHECK_CATEGORY] description of issue (line N) --- ``` If a file has no findings at any severity level, report: ``` ## [file path] Page type: [type] No issues found. ``` At the end, report a summary: ``` ## Summary Files audited: N Errors: N (across N files) Warnings: N (across N files) Info: N (across N files) ``` ## Notes - Do NOT modify files. This skill is read-only. - When auditing multiple files, process them in alphabetical order. - For glob patterns, expand them and process each matching file. - Skip `_index.md` files, `triage.md`, and `for-*.md` files (these have different structures). - Line numbers in reports should reference the actual file line numbers. - For tone and writing quality issues beyond endash/emdash/emoji, use `/tech-writing-review` - that skill handles passive voice, hedging, paragraph length, and reader experience.