---
name: agent-docs-consistency
description: Use when checking the AGENTS.md and agent-docs graph for reachability, cycles, depth, duplicate authority, routing clarity, or rule-doc versus inventory-doc consistency.
---

# Agent Docs Consistency

## Overview

Use this skill for structural consistency checks across AGENTS and `agent-docs`. It focuses on the document graph and authority model, not repository behavior.

## When to Use

- The user asks whether there are cycles
- The user asks for document depth or routing structure
- The user asks whether two docs both own the same rule
- The user asks whether two sibling docs both apply to the same task
- The user asks whether a doc has become a secondary router or mixed-shape document

## Workflow

1. Read the root `AGENTS.md`.
2. Read the active child docs in scope.
3. Read `../agent-docs/references/consistency-checklist.md`.
4. Read `../agent-docs/references/severity-model.md`.
5. Read `../agent-docs/references/report-format.md`.
6. Inspect:
   - root reachability
   - shortest routing depth
   - direct cycles and high-noise cross-links
   - duplicate authority candidates
   - equally specific overlapping docs
   - out-degree hotspots
   - rule-doc vs inventory-doc shape mismatches
7. Apply the default structure budget unless a narrower doc explicitly justifies an exception:
   - recommended shortest root-to-leaf routing depth: `<= 3`
   - recommended active downstream references from one doc: `<= 7`
   - treat budget overruns as structural warnings, then decide whether they remain acceptable or now require refactor
8. Distinguish:
   - blocking structural ambiguity such as duplicate authority or equally specific overlapping docs
   - other high-noise structural problems
   - acceptable cross-references
9. Report the structural findings without drifting into repository implementation review. Use the consistency shape from `report-format.md`. Use `agent-docs-repo-alignment` for repo-fact comparison.

## Output

- Reachability summary
- Cycle summary
- Blocking structural ambiguity findings
- Structural warnings such as depth or out-degree overruns
- Other duplicate-authority or shape findings
- Residual risk assessment