Enforce Documentation Hierarchy
Scope: $ARGUMENTS
Audits documentation against authority chains, then aligns violations with user
approval.
Authority Chains
1. Project Documentation
Discover from the project's CONTRIBUTING.md "Documentation Hierarchy" section
(or equivalent). Typical chain:
UserStory / PRD (requirements, scope — PRIMARY AUTHORITY)
→ architecture.md (technical design)
→ Sprint / implementation docs (current state)
→ Usage guides / howtos (operations)
^ Research / landscape docs (INFORMATIONAL ONLY — never requirements)
2. Claude Code Infrastructure
CLAUDE.md (entry point)
→ AGENTS.md (behavioral rules, compliance, decision framework)
→ CONTRIBUTING.md (technical workflows, commands, coding standards)
→ .claude/rules/*.md (session-loaded rules)
→ .claude/skills/*/SKILL.md (on-demand capabilities)
Content Authority
| Content Type |
Authoritative Source |
NOT here |
| Requirements/scope |
PRDs ONLY |
architecture, howtos, research |
| User workflows |
User stories ONLY |
architecture, sprint docs |
| Technical design |
architecture.md ONLY |
sprint docs, howtos, research |
| Current status |
Sprint/impl docs ONLY |
architecture, user stories |
| Operations |
Usage guides ONLY |
architecture, sprint docs |
| Research |
Research/landscape docs |
INFORMATIONAL — never requirements |
When to Use
- After moving/renaming/deleting documentation files
- Before or after a sprint to verify doc health
- When adding new documents (verify correct tier placement)
- When reviewing PRs that touch docs
- Periodically as hygiene (
/enforcing-doc-hierarchy full)
Phase 1: Audit
Detect violations across the scope. For each finding, record:
| Source File |
Line |
Type |
Description |
| path |
Lnn |
type |
what's wrong |
Violation Types
- broken-ref: Reference points to moved, renamed, or deleted file
- stale-path: File path in docs doesn't match actual location
- duplicate: Same content in multiple documents (DRY violation)
- scope-creep: Requirement-like content in research/landscape docs
- wrong-authority: Content in wrong doc per Content Authority table
- chain-break: Missing link in an authority chain
Audit Procedure
Determine scope from $ARGUMENTS:
- Specific file: audit that file's references and content placement
- Directory: audit all
.md files in that directory
full or empty: audit both authority chains end-to-end
Validate cross-references: Run make lint_links if available (lychee).
Then grep for @file references and relative paths that lychee may miss.
Detect duplicates: Look for substantial content (3+ lines) in both an
authoritative document and a dependent document.
Check content placement against Content Authority table:
- Research/landscape: flag requirement-like language (
must, shall,
required, will implement) — scope-creep
- architecture.md: flag user workflows or acceptance criteria — wrong-authority
- Sprint docs: flag design decisions belonging in architecture.md
- Distinguish informational references from project-level mandates.
Verify chain integrity: Confirm each document in both chains references
the next document in the chain.
Output findings table sorted by violation type.
Phase 2: Align
Resolve findings with user confirmation. Propose each fix and wait for approval.
| Violation |
Procedure |
| broken-ref |
Update path. If target deleted, remove reference. |
| stale-path |
Grep all docs for old path, replace with current. |
| duplicate |
Identify authority by tier. Replace duplicate with reference link. |
| scope-creep |
Move requirement-like content to PRD/architecture. Leave summary. |
| wrong-authority |
Move to correct doc per table. Replace with reference link. |
| chain-break |
Add missing reference to restore chain link. |
Alignment Rules
- Update the authoritative document first, then fix dependents
- Never duplicate — replace with a reference to the authority
- Confirm each fix with user before applying
- Keep edits minimal and targeted
References
- CONTRIBUTING.md "Documentation Hierarchy" — authority structure and rules
- AGENTS.md "Decision Framework" — anti-scope-creep and anti-redundancy rules
.claude/rules/core-principles.md — DRY, KISS principles
1---2name: enforcing-doc-hierarchy3description: Audits and aligns project documentation against authority chains (project docs and Claude Code infrastructure). Detects broken references, duplicates, scope creep, and chain breaks. Use when reviewing documentation health, fixing stale references, or enforcing single-source-of-truth.4compatibility: Designed for Claude Code5metadata:6 source: https://skillmd.com/skills/qte77/enforcing-doc-hierarchy7 argument-hint: [file-directory-or-full]8 allowed-tools: Read, Grep, Glob, Edit9---1011# Enforce Documentation Hierarchy1213**Scope**: $ARGUMENTS1415Audits documentation against authority chains, then aligns violations with user16approval.1718## Authority Chains1920### 1. Project Documentation2122Discover from the project's `CONTRIBUTING.md` "Documentation Hierarchy" section23(or equivalent). Typical chain:2425```26UserStory / PRD (requirements, scope — PRIMARY AUTHORITY)27 → architecture.md (technical design)28 → Sprint / implementation docs (current state)29 → Usage guides / howtos (operations)30 ^ Research / landscape docs (INFORMATIONAL ONLY — never requirements)31```3233### 2. Claude Code Infrastructure3435```36CLAUDE.md (entry point)37 → AGENTS.md (behavioral rules, compliance, decision framework)38 → CONTRIBUTING.md (technical workflows, commands, coding standards)39 → .claude/rules/*.md (session-loaded rules)40 → .claude/skills/*/SKILL.md (on-demand capabilities)41```4243### Content Authority4445| Content Type | Authoritative Source | NOT here |46|---|---|---|47| Requirements/scope | PRDs ONLY | architecture, howtos, research |48| User workflows | User stories ONLY | architecture, sprint docs |49| Technical design | architecture.md ONLY | sprint docs, howtos, research |50| Current status | Sprint/impl docs ONLY | architecture, user stories |51| Operations | Usage guides ONLY | architecture, sprint docs |52| Research | Research/landscape docs | INFORMATIONAL — never requirements |5354## When to Use5556- After moving/renaming/deleting documentation files57- Before or after a sprint to verify doc health58- When adding new documents (verify correct tier placement)59- When reviewing PRs that touch docs60- Periodically as hygiene (`/enforcing-doc-hierarchy full`)6162## Phase 1: Audit6364Detect violations across the scope. For each finding, record:6566| Source File | Line | Type | Description |67|-------------|------|------|-------------|68| path | Lnn | type | what's wrong |6970### Violation Types7172- **broken-ref**: Reference points to moved, renamed, or deleted file73- **stale-path**: File path in docs doesn't match actual location74- **duplicate**: Same content in multiple documents (DRY violation)75- **scope-creep**: Requirement-like content in research/landscape docs76- **wrong-authority**: Content in wrong doc per Content Authority table77- **chain-break**: Missing link in an authority chain7879### Audit Procedure80811. **Determine scope** from `$ARGUMENTS`:82 - Specific file: audit that file's references and content placement83 - Directory: audit all `.md` files in that directory84 - `full` or empty: audit both authority chains end-to-end85862. **Validate cross-references**: Run `make lint_links` if available (lychee).87 Then grep for `@file` references and relative paths that lychee may miss.88893. **Detect duplicates**: Look for substantial content (3+ lines) in both an90 authoritative document and a dependent document.91924. **Check content placement** against Content Authority table:93 - Research/landscape: flag requirement-like language (`must`, `shall`,94 `required`, `will implement`) — scope-creep95 - architecture.md: flag user workflows or acceptance criteria — wrong-authority96 - Sprint docs: flag design decisions belonging in architecture.md97 - Distinguish informational references from project-level mandates.98995. **Verify chain integrity**: Confirm each document in both chains references100 the next document in the chain.1011026. **Output findings table** sorted by violation type.103104## Phase 2: Align105106Resolve findings with user confirmation. Propose each fix and wait for approval.107108| Violation | Procedure |109|---|---|110| **broken-ref** | Update path. If target deleted, remove reference. |111| **stale-path** | Grep all docs for old path, replace with current. |112| **duplicate** | Identify authority by tier. Replace duplicate with reference link. |113| **scope-creep** | Move requirement-like content to PRD/architecture. Leave summary. |114| **wrong-authority** | Move to correct doc per table. Replace with reference link. |115| **chain-break** | Add missing reference to restore chain link. |116117### Alignment Rules118119- Update the **authoritative** document first, then fix dependents120- Never duplicate — replace with a reference to the authority121- Confirm each fix with user before applying122- Keep edits minimal and targeted123124## References125126- CONTRIBUTING.md "Documentation Hierarchy" — authority structure and rules127- AGENTS.md "Decision Framework" — anti-scope-creep and anti-redundancy rules128- `.claude/rules/core-principles.md` — DRY, KISS principles