| name | instruction-review |
| description | Audits a candidate instruction (.instructions.md) against five gates (spec compliance, content quality, scope fit, safety, currency & coherence) plus optional Gate 6 (token budget for always-on instructions). Use when reviewing a new instruction draft before commit, evaluating a Mall instruction or store instruction for adoption, or re-auditing existing instructions on a periodic cadence. |
| lastReviewed | 2026-05-31T00:00:00.000Z |
Instruction Review
Audit a candidate instruction against the five-gate contract plus optional Gate 6 (Token Budget). Instructions are always-on or pattern-applied rules — every match loads tokens, so the budget gate matters more than for any other artifact type.
When to Use
Three fire contexts:
- Author self-audit — dogfood your own draft before committing. Invoked from instruction-creator Phase 7.
- External candidate adoption — gate before pulling a Mall instruction or store instruction into this brain.
- Periodic re-audit — re-check existing instructions on a cadence (e.g., quarterly retraining).
The shared gate model lives in skill-review/SKILL.md § The Five Gates as the canonical contract. This file documents the instruction-specific criteria for each gate. If a gate definition here disagrees with skill-review, the gate concept in skill-review wins; this file owns only the per-type criteria.
A mechanical validator (e.g., a brain-qa script that ships with the heir) typically checks Gate 1 frontmatter compliance and the mechanical subset of Gate 5 (banned-entity, dead-xref, stale-date, H1/name divergence). Gates 2–6 are judgment-only.
The Five Gates + Gate 6 (Token Budget)
A candidate must pass all five to ship. Always-on instructions (applyTo: "**") must also pass Gate 6. Failure on any gate = decline or revise.
Gate 1 — Spec Compliance
| Check | Pass criterion |
|---|
| Frontmatter present AND minimal | description + applyTo + lastReviewed. Reject any of: name, type, application, tier, currency, inheritance, lifecycle, mode, user-invokable. |
description valid | Third-person, ≤1024 chars, names what the instruction enforces AND when/where it fires (the trigger condition or scope) |
applyTo valid glob | Non-empty, syntactically valid glob (e.g., **, **/*.ts, **/AI-Memory/**). Comma-separated globs allowed. |
| Filename pattern | <kebab-name>.instructions.md in .github/instructions/ (flat — no subfolders) |
| Markdown lints clean | No broken links, no missing code-fence languages, no MD060 spacing issues |
Gate 2 — Content Quality
| Check | Pass criterion |
|---|
| Directive voice | Tells the agent what to do under what condition. Not encyclopedic ("instructions are..."), not narrative ("when we introduced this..."). |
| Single rule scope | One topic per file. If the title contains "and" or "+", split. |
| Rule tables over prose | Where possible, express rules as Condition → Action tables. Prose is fine for rationale and anti-patterns; not for the rule itself. |
Has ## Would Revise If | At least one falsifier per the heir's falsifiability-deadlines discipline: literal date OR observable event OR count+time bound. Not "after sufficient passes" or "when conditions warrant". |
| At least one anti-pattern table or comparison | Surfaces what the instruction is not asking for. |
| ≤200 lines | Soft target. Pattern-applied instructions may go higher; always-on instructions should not. See Gate 6. |
Gate 3 — Scope Fit
| Check | Pass criterion |
|---|
applyTo calibrated | Glob matches the intended fire scope — neither so broad it fires on irrelevant work, nor so narrow it misses obvious cases. Test against 3 sample paths mentally. |
| Not framework-level | Does not modify the heir's framework foundations (manifesto, tenets, claims) — framework changes go through your decision-record protocol, not an instruction |
| Not redundant with existing instruction | Grep description: and applyTo: across .github/instructions/ — if another instruction covers ≥70% of this rule, extend that one instead |
| Lives in the right brain | Is this for every project (Edition baseline / heir-mirrored) or just this one project? File accordingly. |
| Not a skill in disguise | If it's a procedure with steps (not a rule), it's a skill, not an instruction. Instructions encode rules that fire on context match; skills encode operations the agent invokes |
Gate 4 — Safety
Same criteria as skill-review § Gate 4 — no destructive defaults, no hardcoded credentials/PII, no prompt-injection vectors, reversible.
Gate 5 — Currency & Coherence
Same criteria as skill-review § Gate 5. Instruction-specific note: the H1-vs-filename alignment check applies — H1 should reflect the instruction's actual scope per description, not a slogan.
Gate 6 — Token Budget (always-on instructions only)
Applies when applyTo: "**" or any pattern that fires on a meaningful fraction of typical work.
| Check | Pass criterion |
|---|
Body ≤150 lines for applyTo: "**" | Always-on instructions load on every match; the budget is shared with all other always-on instructions and every conversation turn. Over-budget = degrades every session. |
Body ≤200 lines for pattern-applied (applyTo: "**/*.ts" and similar) | Pattern-applied is bounded by the pattern's actual fire frequency — looser ceiling. |
| Always-on rationale named | If applyTo: "**", the instruction body explicitly names why it's always-on (load-bearing for every turn, or framework-level discipline). |
| No copy-paste from a skill | If the instruction's content duplicates a skill body, the skill is the source of truth — instruction should cross-link, not restate. |
Decision Matrix
| Gates passed | Action |
|---|
| All 5 (or all 6 for always-on) | Accept — land the change |
| 4 of 5 (or 5 of 6) | Revise — name the failing gate and patch the candidate |
| ≤3 of 5 (or ≤4 of 6) | Decline — name the rationale; if the decline sets precedent, record it where your heir tracks framework-level decisions |
Recording the Verdict
For self-audits and routine re-audits: the verdict lives in the commit message or the conversation. No separate file.
For external adoption (Mall instruction, store instruction) or any decline that sets precedent: write a verdict capturing gate results, rationale, required changes (if Revise), and the act-pass trail. Store wherever your heir keeps audit decisions (commit log, dedicated ledger, decision records).
Anti-Patterns
| Anti-pattern | Correction |
|---|
| Accepting an always-on instruction without checking Gate 6 | The token cost is invisible at commit time but compounds across every session. Always check. |
Letting applyTo: "**" ship without explicit "always-on rationale" prose | If you can't articulate why this fires every turn, narrow the glob. |
| Treating instructions as mini-skills with procedural steps | If it has steps, it's a skill. Move it. |
| Skipping Gate 3 dedup check because "there's no obvious overlap" | The instructions/ folder grows; grep description: first. |
| Gates drifting from skill-review's shared model | Gate names and meanings come from skill-review. Only the criteria are type-specific. |
Falsifiability
This skill's instruction-specific criteria have failed if any of the following occur within 90 days:
- An accepted instruction is reported broken by 2+ heirs (criteria miscalibrated)
- Gate 6 declines cluster on a single bound (150 / 200 line ceiling) and are reversed during re-audit (ceiling too tight)
- An instruction passes Gate 3 dedup check but later gets identified as overlapping an existing instruction ≥2 times in a quarter (dedup criterion too lax)
Track as you would any falsified discipline (commit log, retraining notes, or curation ledger if your repo ships one) tagged [INSTRUCTION-REVIEW-MISS].
Related
