45 lines
1.8 KiB
Markdown
45 lines
1.8 KiB
Markdown
---
|
|
name: agent-docs-audit
|
|
description: Use when auditing AGENTS.md or agent-docs without editing files, especially for instruction quality review, adherence-risk assessment, findings-first reports, or rationality critiques.
|
|
---
|
|
|
|
# Agent Docs Audit
|
|
|
|
## Overview
|
|
|
|
Use this skill for read-only assessment of AGENTS and `agent-docs`. The output should prioritize findings, evidence, residual risks, and adherence impact instead of proposing patches first.
|
|
|
|
## When to Use
|
|
|
|
- The user asks for a review, audit, rationality check, or instruction-adherence assessment
|
|
- The user asks what remains wrong after a refactor
|
|
- The user asks why agents still fail to follow the docs
|
|
- The task is to list bugs, risks, or remaining problems before making changes
|
|
|
|
Do not use this skill as the main workflow when the task is to edit files. Switch to `agent-docs-refactor` for that.
|
|
|
|
## Workflow
|
|
|
|
1. Read the root `AGENTS.md` and every active child doc in scope.
|
|
2. Read `../agent-docs/references/audit-checklist.md`.
|
|
3. Use `../agent-docs/references/refactor-checklist.md` as the structural baseline.
|
|
4. Separate observed facts from inferences:
|
|
- observed facts: file contents, references, checklists, routing text, command output
|
|
- inferences: likely adherence impact, likely confusion points, likely maintenance risk
|
|
5. Evaluate:
|
|
- routing clarity
|
|
- single authoritative rule ownership
|
|
- shape fitness: rule doc vs inventory doc
|
|
- instruction density and likely adherence load
|
|
- residual cycles or secondary-index behavior
|
|
6. Report findings first, ordered by severity.
|
|
|
|
## Reporting
|
|
|
|
- Findings first
|
|
- Then open questions or assumptions
|
|
- Then an adherence assessment
|
|
- Then any optional summary
|
|
|
|
If no findings are discovered, state that explicitly and mention residual risks or coverage limits.
|