KOKO\Mimi
4.4 KiB
4.4 KiB
name, description
| name | description |
|---|---|
| auditing-agents-md | Use when a user asks to audit, check, review, improve, update, or fix AGENTS.md or AGENTS.override.md files, or asks whether Codex repository guidance is accurate and current. |
Audit AGENTS.md
Overview
Audit Codex guidance against the repository that it governs. Treat instruction precedence, factual accuracy, scope, and conciseness as observable properties: report evidence before proposing a change, and propose before editing.
Workflow
- Resolve scope. Identify the project root, current working directory, and
requested audit scope. Resolve Codex home from
CODEX_HOME, falling back to~/.codex; inspect global guidance only when it is in scope. - Discover guidance. Find
AGENTS.override.mdandAGENTS.mdwhile excluding VCS metadata, dependencies, caches, and generated output. At each directory, an override is selected before the standard file. Map the active chain from project root to the working directory and label files that govern only other subtrees. - Inspect evidence. Read each selected file completely. Check commands, paths, architecture claims, and conventions against manifests, source, tests, config, and version control. Run only safe, relevant verification; do not deploy, mutate external state, or expose credentials to score a file.
- Score every file. Read quality-criteria.md. Use its six weighted criteria, 100-point total, and grade bands. Check conflicts, duplication, misplaced scope, override behavior, and the combined 32 KiB default instruction budget.
- Report before changing. Emit the output contract below even when the guidance is already strong.
- Propose targeted diffs. Read update-guidelines.md. Include only claims supported by repository evidence. Use templates.md only when a missing structure is genuinely useful.
- Request approval. Stop after the report and proposed diffs. Ask which changes the user wants applied.
- Apply and verify. Edit only approved files, preserve their organization, and re-check commands, paths, conflicts, active-chain order, and byte budget.
Required Report
## AGENTS.md Quality Report
### Summary
- Files found: N
- Active chain: path -> path
- Average score: N/100
- Files needing update: N
- Combined active-chain size: N bytes (default limit: 32 KiB)
### File-by-File Assessment
#### 1. path (scope; active/inactive)
**Score: N/100 (Grade: A-F)**
| Criterion | Score | Evidence |
| --- | ---: | --- |
| Commands and workflows | N/20 | ... |
| Repository map and instruction scope | N/20 | ... |
| Non-obvious constraints and gotchas | N/15 | ... |
| Conciseness and duplication | N/15 | ... |
| Currency against the codebase | N/15 | ... |
| Actionability and verifiability | N/15 | ... |
**Issues**
- ...
**Recommended changes**
- ...
After all assessments, show each proposed diff under ### Update: <path> with
a one-line Why:. End with an explicit approval question. Do not edit in the
same turn unless the user already approved the exact diff.
Quick Reference
| Question | Evidence |
|---|---|
| Which file applies? | Global selection, then one selected file per directory from root to working directory |
| Is a command current? | Manifest plus a safe command run when practical |
| Is a path accurate? | Filesystem and repository search |
| Is guidance misplaced? | Narrowest subtree where the rule is true |
| Is the chain too large? | Combined selected-file bytes versus configured/default limit |
| Should content be added? | Project-specific, durable, non-obvious, and actionable |
Example
If AGENTS.md requires npm test but package.json contains only
test:unit, score currency and actionability down, cite package.json, and
propose the verified command. Do not invent an aggregate script or silently
edit the file.
Common Mistakes
- Scoring the repository once instead of scoring every guidance file.
- Treating a nested override as deleting unrelated root guidance.
- Claiming a file is an entry point because its name looks plausible.
- Recommending generic best practices or facts obvious from code.
- Running destructive, deployment, or credential-sensitive commands to audit.
- Applying recommendations before the user approves the displayed diff.