# Instruction File Quality Checklist

Per-file evaluation criteria for agent instruction files. Use this checklist to score each instruction file during analysis. The full quality guidance lives in `docs/agent-instruction.md` — this is a distilled, actionable checklist.

## Evaluation Criteria

### 1. Commands Correct and Runnable

- [ ] All referenced commands exist in package.json scripts or are valid shell commands
- [ ] Command sequences match the documented build/test/lint workflow
- [ ] No placeholder commands (`{command}`, `TODO`, etc.) in non-template files
- **Severity if failing:** Medium (stale commands) or Critical (commands that would break builds)

### 2. Non-Negotiables Near Top

- [ ] Security rules, access controls, and data handling requirements appear in the first screenful (~30 lines)
- [ ] Canonical commands (install, dev, build, test, lint) appear before detailed conventions
- [ ] "Definition of Done" or acceptance criteria are present early
- **Severity if failing:** High (security non-negotiables missing) or Medium (ordering issue)

### 3. No Duplication Across Files

- [ ] Root file does not repeat content that scoped files cover
- [ ] Scoped files do not copy-paste root-level sections
- [ ] Cross-file `@import` or reference directives are used where appropriate
- **Severity if failing:** Medium

### 4. Size Within Budget

- [ ] Root files (AGENTS.md, CLAUDE.md): <300 lines (hard max 500)
- [ ] Scoped/package files: 40–150 lines
- [ ] Individual rules files: <80 lines
- [ ] Always-on baseline load is estimated and kept comfortably below the task budget
- [ ] Typical task load (root + one realistic scoped file + matching rules) is estimated and fits within the 32 KiB task budget
- [ ] Worst-case task load is estimated and explicitly called out if it is likely to strain the budget
- [ ] Aggregate repo total is reported separately for awareness, not treated as the operative task budget by itself
- **Severity if failing:** Medium (over budget) or Low (close to limit)

### 5. Scoped Only for Real Divergence

- [ ] Scoped files exist only where the directory has genuinely different stack, workflow, or domain requirements
- [ ] No scoped files that merely repeat root-level guidance
- **Severity if failing:** Low

### 6. Precedence Clear

- [ ] Override semantics are explicit (nearest-wins for AGENTS.md, import directives for CLAUDE.md)
- [ ] No ambiguous or conflicting instructions across scope levels
- **Severity if failing:** Medium

### 7. No Circular Imports

- [ ] File A does not import File B which imports File A
- [ ] Import chains are acyclic
- **Severity if failing:** High

### 8. Definition of Done Present

- [ ] Objective, verifiable criteria for when work is "done"
- [ ] Not vague ("write good code") — concrete checks (tests pass, lint clean, types valid)
- **Severity if failing:** Medium

### 9. Staleness

- [ ] Referenced file paths still exist in the repo
- [ ] Referenced commands still work
- [ ] Technology/framework references match current stack
- [ ] No references to removed features or deprecated patterns
- **Severity if failing:** Medium (stale references) or High (actively misleading)

### 10. Cross-Format Body Consistency

- [ ] Glob-scoped rules targeting the same paths have identical body content across providers
- [ ] Only frontmatter differs between Claude rules, Cursor rules, and Copilot instructions
- [ ] Body divergence is flagged as drift
- **Severity if failing:** Medium

### 11. Claims Are Evidence-Backed

- [ ] Every non-obvious convention is backed by a concrete repo source (config, docs, existing instructions, or representative code samples)
- [ ] Numeric claims (`N files`, split ratios, "only X uses Y") are backed by exhaustive repo-wide counts, not samples
- [ ] Recommendations that remove or contradict an existing rule cite the verification evidence that justifies the correction
- [ ] Formatting/style claims are omitted unless supported by repo evidence
- [ ] If a formatter or linter enforces the rule, the file prefers commands/links over prose restatement
- **Severity if failing:** High (actively misleading) or Medium (unsupported claim)

### 12. Progressive Disclosure Is Used

- [ ] Always-on instructions keep only the minimal essential guidance inline
- [ ] Deeper detail links to canonical docs/config/examples instead of copying them into the instruction file
- [ ] The file clearly distinguishes inline essentials from optional deeper reading
- **Severity if failing:** Medium

### 13. File-Type Conventions Covered

This criterion applies to the **overall instruction set**, not to individual files. Evaluate once per analysis.

- [ ] Common file-type patterns (tests, stories, styles, configs) with 5+ files have been evaluated for rule opportunities
- [ ] Patterns with >80% consistency and correctness impact are flagged as glob-scoped rule opportunities
- [ ] Patterns with competing sub-patterns (especially `40–60%` splits) are explicitly evaluated and flagged when agents are likely to guess wrong
- [ ] Materially different activation targets are split into separate rule recommendations when that improves precision
- [ ] Security-sensitive file-type patterns are explicitly evaluated for rule opportunities and severity
- [ ] Patterns that are exceptions to project-wide rules are explicitly called out (these are highest-value)
- [ ] Existing glob-scoped rules cover the identified patterns, or coverage gaps are recorded
- **Severity if failing:** Medium (missed pattern) or High (missed exception-to-rule pattern)

### 14. Available Documentation Is Referenced

This criterion uses the documentation inventory from Step 2 (Discover Documentation Surfaces).

- [ ] Instruction files reference relevant available documentation (READMEs, docs pages, architecture docs) in their References section
- [ ] Scoped instruction files reference docs topically relevant to their directory scope (e.g., a package AGENTS.md references the package's README or docs subtree)
- [ ] References point to existing, current documentation (not stale or removed)
- [ ] Content duplicated from available docs is flagged for `link_only` disclosure instead of inline repetition
- **Severity if failing:** Low (missing references) or Medium (duplicates content that exists in available docs)

## Scoring

For each file, count passing criteria out of the applicable set (some criteria only apply to certain file types).
A "miss" means one numbered criterion does not pass for that file after ignoring non-applicable checks within the criterion:

- **All applicable passing** → Quality: pass
- **1-2 misses** → Quality: minor issues
- **3-5 misses** → Quality: significant issues
- **6+ misses** → Quality: major issues
