Prompt Review
Audit a candidate prompt against the five-gate contract. Prompts are workflow entry points — short, imperative, single-goal. No optional Gate 6 (prompts are short by nature; no scaling concern Gates 1–5 miss).
When to Use
Three fire contexts:
- Author self-audit — dogfood your own draft before committing. Invoked from prompt-creator Phase 7.
- External candidate adoption — gate before pulling a Mall prompt or store prompt into this brain.
- Periodic re-audit — re-check existing prompts on a cadence (e.g., quarterly retraining).
The shared gate model lives in skill-review/SKILL.md § The Five Gates. This file documents the prompt-specific criteria for each gate.
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. Gates 2–5 are judgment-only.
The Five Gates
A candidate must pass all five to ship. Failure on any gate = decline or revise.
Gate 1 — Spec Compliance
| Check |
Pass criterion |
| Frontmatter present AND minimal |
description + lastReviewed. Reject any of: name, type, application, tier, currency, inheritance, lifecycle, user-invokable, evidence. |
mode: field handling |
Per current Microsoft Learn prompt-files spec, mode: agent is deprecated. Existing prompts may carry it during sweep transition; new prompts should not introduce it. Flag as Gate 1 fail if a new prompt adds mode:. |
description valid |
Third-person, ≤1024 chars, names what the prompt does AND when to invoke it (slash-command UX). |
| Filename pattern |
<kebab-name>.prompt.md in .github/prompts/ (flat — no subfolders) |
| Markdown lints clean |
No broken links, no missing code-fence languages |
Gate 2 — Content Quality
| Check |
Pass criterion |
| Imperative voice |
Verbs in the imperative ("Run X", "Read Y", "Apply Z"). Prompts are commands to the agent, not explanations. |
| Single workflow scope |
One goal per prompt. If the title contains "and" or "+", split. Prompts that are menus of unrelated commands fail this gate. |
| Numbered steps |
The prompt's body is a numbered step list. Brief context paragraph allowed before the steps; nothing else. |
Has ## Would Revise If OR justification for omission |
Prompts under 30 lines may inline the falsifier; longer prompts must have an explicit section per your heir's falsifiability-deadlines discipline. |
| ≤100 lines |
Soft target. Long prompts signal that the workflow belongs in a skill; the prompt should just invoke the skill. |
Gate 3 — Scope Fit
| Check |
Pass criterion |
| Workflow entry-point, not workflow body |
The prompt invokes a skill (or runs a short coordinated sequence). The skill carries the procedure; the prompt is the front door. |
| Not redundant with existing prompt |
Grep description: across .github/prompts/ — if another prompt covers the same workflow, extend that one. |
| Discoverable as slash-command |
The prompt's name (filename without .prompt.md) is something a user would intuitively type after /. /review-instruction good; /v2-thing-do bad. |
| Lives in the right brain |
Generic developer workflows → heir baseline. Project-specific workflows → that project's local repo. |
Gate 4 — Safety
Same criteria as skill-review § Gate 4. Prompt-specific note: prompts that invoke destructive operations (force-push, drop, delete) must include an explicit user-confirmation step before the destructive call.
Gate 5 — Currency & Coherence
Same criteria as skill-review § Gate 5. Prompt-specific note: the prompt must reference live skills/instructions in its steps. A prompt that calls a retired skill is a Gate 5 failure even if the prompt itself is well-written.
Decision Matrix
| Gates passed |
Action |
| All 5 |
Accept — land the change |
| 4 of 5 |
Revise — name the failing gate and patch the candidate |
| ≤3 of 5 |
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 prompt, store prompt) 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.
Anti-Patterns
| Anti-pattern |
Correction |
| Accepting a prompt that carries the workflow inline instead of invoking a skill |
If the prompt has more than the step list, the workflow belongs in a skill |
Letting mode: agent ship on a new prompt |
Per Microsoft Learn current spec, deprecated. Flag at Gate 1. |
| Accepting "menu" prompts that bundle unrelated commands |
One workflow per prompt. Multi-purpose prompts confuse the slash-picker. |
| Skipping the slash-picker discoverability check |
Filename = user typing. If the name is cryptic, the prompt won't get found. |
| Prompt references a retired skill |
Gate 5 semantic failure. Check the Steps: block resolves to live artifacts. |
Falsifiability
This skill's prompt-specific criteria have failed if any of the following occur within 90 days:
- An accepted prompt is reported broken (workflow doesn't fire, or fires wrong) by 2+ heirs
- Gate 2 ≤100 lines threshold is reversed ≥3 times for legitimate complex workflows (ceiling too tight)
- Prompts accepted via this skill are typed via slash-picker <50% of the time when applicable (discoverability criterion miscalibrated)
Track as you would any falsified discipline (commit log, retraining notes, or curation ledger if your repo ships one) tagged [PROMPT-REVIEW-MISS].
Related
1---2name: prompt-review3description: Audits a candidate prompt (.prompt.md) against five gates (spec compliance, content quality, scope fit, safety, currency & coherence). Use when reviewing a new prompt draft before commit, evaluating a Mall prompt or store prompt for adoption, or re-auditing existing prompts on a periodic cadence.4---5
6<!-- intentional divergence from Supervisor: Edition expands gate names inline and strips Supervisor-only ADR-007 ref. Same five gates. Audited 2026-05-31. -->
7
8# Prompt Review
9
10Audit a candidate prompt against the five-gate contract. Prompts are workflow entry points — short, imperative, single-goal. No optional Gate 6 (prompts are short by nature; no scaling concern Gates 1–5 miss).
11
12## When to Use
13
14Three fire contexts:
15
161. **Author self-audit** — dogfood your own draft before committing. Invoked from [prompt-creator](../prompt-creator/SKILL.md) Phase 7.
172. **External candidate adoption** — gate before pulling a Mall prompt or store prompt into this brain.
183. **Periodic re-audit** — re-check existing prompts on a cadence (e.g., quarterly retraining).
19
20The shared gate model lives in [skill-review/SKILL.md § The Five Gates](../skill-review/SKILL.md). This file documents the **prompt-specific criteria** for each gate.
21
22A 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. Gates 2–5 are judgment-only.
23
24## The Five Gates
25
26A candidate must pass **all five** to ship. Failure on any gate = decline or revise.
27
28### Gate 1 — Spec Compliance
29
30| Check | Pass criterion |
31|---|---|
32| Frontmatter present AND minimal | `description` + `lastReviewed`. Reject any of: `name`, `type`, `application`, `tier`, `currency`, `inheritance`, `lifecycle`, `user-invokable`, `evidence`. |
33| `mode:` field handling | Per current Microsoft Learn prompt-files spec, `mode: agent` is deprecated. Existing prompts may carry it during sweep transition; new prompts should not introduce it. Flag as Gate 1 fail if a new prompt adds `mode:`. |
34| `description` valid | Third-person, ≤1024 chars, names what the prompt does AND when to invoke it (slash-command UX). |
35| Filename pattern | `<kebab-name>.prompt.md` in `.github/prompts/` (flat — no subfolders) |
36| Markdown lints clean | No broken links, no missing code-fence languages |
37
38### Gate 2 — Content Quality
39
40| Check | Pass criterion |
41|---|---|
42| Imperative voice | Verbs in the imperative ("Run X", "Read Y", "Apply Z"). Prompts are commands to the agent, not explanations. |
43| Single workflow scope | One goal per prompt. If the title contains "and" or "+", split. Prompts that are menus of unrelated commands fail this gate. |
44| Numbered steps | The prompt's body is a numbered step list. Brief context paragraph allowed before the steps; nothing else. |
45| Has `## Would Revise If` OR justification for omission | Prompts under 30 lines may inline the falsifier; longer prompts must have an explicit section per your heir's falsifiability-deadlines discipline. |
46| ≤100 lines | Soft target. Long prompts signal that the workflow belongs in a skill; the prompt should just invoke the skill. |
47
48### Gate 3 — Scope Fit
49
50| Check | Pass criterion |
51|---|---|
52| Workflow entry-point, not workflow body | The prompt invokes a skill (or runs a short coordinated sequence). The skill carries the procedure; the prompt is the front door. |
53| Not redundant with existing prompt | Grep `description:` across `.github/prompts/` — if another prompt covers the same workflow, extend that one. |
54| Discoverable as slash-command | The prompt's name (filename without `.prompt.md`) is something a user would intuitively type after `/`. `/review-instruction` good; `/v2-thing-do` bad. |
55| Lives in the right brain | Generic developer workflows → heir baseline. Project-specific workflows → that project's local repo. |
56
57### Gate 4 — Safety
58
59Same criteria as [skill-review § Gate 4](../skill-review/SKILL.md). Prompt-specific note: prompts that invoke destructive operations (force-push, drop, delete) must include an explicit user-confirmation step before the destructive call.
60
61### Gate 5 — Currency & Coherence
62
63Same criteria as [skill-review § Gate 5](../skill-review/SKILL.md). Prompt-specific note: the prompt must reference *live* skills/instructions in its steps. A prompt that calls a retired skill is a Gate 5 failure even if the prompt itself is well-written.
64
65## Decision Matrix
66
67| Gates passed | Action |
68|---|---|
69| All 5 | **Accept** — land the change |
70| 4 of 5 | **Revise** — name the failing gate and patch the candidate |
71| ≤3 of 5 | **Decline** — name the rationale; if the decline sets precedent, record it where your heir tracks framework-level decisions |
72
73## Recording the Verdict
74
75For self-audits and routine re-audits: the verdict lives in the commit message or the conversation. No separate file.
76
77For external adoption (Mall prompt, store prompt) 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.
78
79## Anti-Patterns
80
81| Anti-pattern | Correction |
82|---|---|
83| Accepting a prompt that carries the workflow inline instead of invoking a skill | If the prompt has more than the step list, the workflow belongs in a skill |
84| Letting `mode: agent` ship on a new prompt | Per Microsoft Learn current spec, deprecated. Flag at Gate 1. |
85| Accepting "menu" prompts that bundle unrelated commands | One workflow per prompt. Multi-purpose prompts confuse the slash-picker. |
86| Skipping the slash-picker discoverability check | Filename = user typing. If the name is cryptic, the prompt won't get found. |
87| Prompt references a retired skill | Gate 5 semantic failure. Check the `Steps:` block resolves to live artifacts. |
88
89## Falsifiability
90
91This skill's prompt-specific criteria have failed if any of the following occur within 90 days:
92
93- An accepted prompt is reported broken (workflow doesn't fire, or fires wrong) by 2+ heirs
94- Gate 2 ≤100 lines threshold is reversed ≥3 times for legitimate complex workflows (ceiling too tight)
95- Prompts accepted via this skill are typed via slash-picker <50% of the time when applicable (discoverability criterion miscalibrated)
96
97Track as you would any falsified discipline (commit log, retraining notes, or curation ledger if your repo ships one) tagged `[PROMPT-REVIEW-MISS]`.
98
99## Related
100
101- [skill-review](../skill-review/SKILL.md) — sibling for skills; canonical source of the shared five-gate contract
102- [prompt-creator](../prompt-creator/SKILL.md) — inverts these gates into authoring phases
103- [instruction-review](../instruction-review/SKILL.md) — sibling for instructions
104- [agent-review](../agent-review/SKILL.md) — sibling for agents
105- [act-pass](../../instructions/act-pass.instructions.md) — required for medium-stakes audits
106- `/review-prompt` prompt — slash-command entry point
gabrielmoreira