From docs-governance
Audit documentation against its declared hierarchy — broken links, duplicates, misplaced content, stale references, single-source-of-truth enforcement. Use for doc health reviews.
How this skill is triggered — by the user, by Claude, or both
Slash command
/docs-governance:enforcing-doc-hierarchyThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
**Scope**: $ARGUMENTS
Scope: $ARGUMENTS
Audits documentation against the project's declared hierarchy, then aligns violations with user approval.
Read the project's hierarchy declaration. Look for (in order):
CONTRIBUTING.md — "Documentation Hierarchy" section (table or list)AGENTS.md — "Key references" or "Information sources" sectionREADME.md — "Documentation" section (links to authoritative docs)Extract:
If no hierarchy is declared, report that as the first finding and stop.
Detect violations across the scope. For each finding, record:
| Source File | Line | Type | Description |
|---|---|---|---|
| path | Lnn | type | what's wrong |
<!-- markdownlint-disable/enable --> for a rule already disabled in .markdownlint.json. These are dead code that causes false positives when the enable directive re-activates a globally-disabled rule[key]: url link definition with no corresponding [text][key] or [key] reference in the fileDetermine scope from $ARGUMENTS:
.md files in that directoryfull or empty: audit every .md file in the repoCheck links: For each [text](path) and @file reference, verify the
target exists. Check case sensitivity.
Check duplicates: For each authority doc, search dependent docs for substantial repeated content (3+ lines or identical tables).
Check placement: For each doc, verify its content matches its declared authority. Flag content that belongs in a different doc per the authority map.
Check chain: Verify each doc in the hierarchy is referenced by at least one parent doc. Flag orphaned docs.
Run markdownlint (preferred) or manual lint check (fallback):
a) If markdownlint-cli is available (npx markdownlint-cli --version
succeeds): run it with the project config and parse output:
npx markdownlint-cli -c .markdownlint.json <scope> 2>&1
Map results to violation types: MD012 → double blanks (fix during align),
MD053 → unused-link-def, MD022/MD058 → spacing issues from prior
directive removal. Report rule ID + line + message.
b) Fallback (no markdownlint available): read .markdownlint.json
(or .markdownlintrc, .markdownlint.yaml) to get globally-disabled
rules, then manually:
lint-compat)<!-- markdownlint-disable/enable MDXXX --> where MDXXX is
already disabled in the config file (config-drift)[key]: url definitions with no corresponding reference
(unused-link-def)In both paths: read the lint config to detect config-drift — even
markdownlint doesn't flag dead inline directives for globally-disabled
rules. See frontmatter-convention.md rule for the required config
template.
Output findings table sorted by type, then file.
Resolve findings with user confirmation. Propose each fix and wait for approval.
| Violation | Fix |
|---|---|
| broken-link | Update path. If target deleted, remove reference. |
| duplicate | Keep in authority doc, replace in dependent doc with reference link. |
| misplaced | Move content to authority doc, replace original with reference link. |
| lint-compat | Remove HTML comments before frontmatter. |
| config-drift | Delete the inline directive — the rule is already handled by .markdownlint.json. Do NOT collapse surrounding blank lines (they may be required spacing around headings/tables). |
| unused-link-def | Add inline reference, or remove the definition if it serves no purpose. |
.markdownlint.json before adding any inline lint directives — if a
rule is globally disabled, inline toggles are dead code that causes false
positives when the enable half re-activates the rulesed)rules/frontmatter-convention.md — required .markdownlint.json config
template and anti-patterns for inline directivesFetches up-to-date documentation from Context7 for libraries and frameworks like React, Next.js, Prisma. Use for setup questions, API references, and code examples.
Applies a firm's KYC/AML rules grid to parsed onboarding records: assigns risk rating, checks required documents, outputs rule outcomes with citations, and routes for escalation.
Generates daily or weekly digests of activity from connected sources (chat, email, docs, tasks, CRM), highlighting action items, decisions, mentions, and project updates.
npx claudepluginhub qte77/claude-code-plugins --plugin docs-governance