prompt-comprehension-audits
Skill3 starsChanged 2 months agoMITView on GitHub
Test whether a fresh agent's interpretation is semantically equivalent to the intended request. The interpreter and reviewer provide advisory evidence; the audit coordinator owns the final status. Run Prompt Audit when requested or required by the accepted task or repository. Maintainer absence alone does not require it. One request or Ticket otherwise stays with its current implementation owner, whether the maintainer stays or authorizes continuation while away. When an audit is required, preserve its isolation and status rules below. For…
In this repository31 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- codebase-designSkill
- code-reviewSkill
- diagnosing-bugsSkill
- dispatch-ticketsSkill
- grill-with-docsSkill
- implementSkill
- improve-codebase-architectureSkill
- orchestrateSkill
- prototypeSkill
- researchSkill
- resolving-merge-conflictsSkill
- setup-omskillsSkill
- tddSkill
- to-specSkill
- to-ticketsSkill
- triageSkill
- wayfinderSkill
- cavemanSkill
- designSkill
- excalidrawSkill
- grill-meSkill
- handoffSkill
- model-routingSkill
- teachSkill
- tmux-workerSkill
- voiceSkill
- wormholeSkill
- write-a-skillSkill
- writing-great-skillsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
19 rules. About 0 are common, 15 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈15
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 11
Test whether a fresh agent's interpretation is semantically equivalent to the intended request.
- Distinctive: line 15
Run Prompt Audit when requested or required by the accepted task or repository.
- Distinctive: line 26
Read-only audit leaves return missing prerequisites to their responsible caller instead of writing setup.
- Distinctive: line 31
Before delegation, read the complete original request and every artifact it explicitly requires.
- Very specific: line 45
If the accepted sources do not determine material authority or the contract changes materially after the reference is fixed, choose FAIL, …
- Very specific: line 50
When the maintainer explicitly waives the comprehension audit for the exact contract, skip the agent passes and consider only BYPASS or …
- Distinctive: line 58
Read model-routing before selecting models for the interpreter and reviewer.
- Distinctive: line 72
Every delegated pass is a fresh, independent, read-only, non-delegating leaf that performs its assigned comparison directly.
- Distinctive: line 85
Before each launch, preflight the tools and providers required for that pass and the absence of inherited conversation.
- Distinctive: line 104
Run the passes sequentially even when asynchronous delivery is available: the interpreter must settle before the reviewer starts.
- Distinctive: line 121
Start one fresh agent for the interpreter pass and, only after it settles, another fresh independent agent for the reviewer pass.
- Distinctive: line 145
After interpreter settlement, give the reviewer only:
- Distinctive: line 171
Only after both passes settle, compare the original request, fixed reference intent, interpreter response, and reviewer judgment.
- Distinctive: line 175
Treat a difference as material semantic divergence only when it changes the understood outcome, scope, required workflow or order, …
- Distinctive: line 184
If the fixed reference determines one clear meaning and the differing reading is not supported, record that adjudication and continue.
- Very specific: line 186
If plausible readings materially differ, authority remains unresolved, or fixing the ambiguity would change the audited contract, choose …
- Very specific: line 197
Treat any semantic PASS or explicit BYPASS above as provisional.
- Distinctive: line 215
Never infer this waiver or represent a bypass as a pass.
- Distinctive: line 220
When the execution contract is a tracked issue or an agent brief on one, post a new comment without editing prior audit history:
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Audit Prompt Comprehension
Test whether a fresh agent's interpretation is semantically equivalent to the intended request. The interpreter and reviewer provide advisory evidence; the audit coordinator owns the final status.
Run Prompt Audit when requested or required by the accepted task or repository. Maintainer absence alone does not require it. One request or Ticket otherwise stays with its current implementation owner, whether the maintainer stays or authorizes continuation while away. When an audit is required, preserve its isolation and status rules below.
For a tracked implementation Ticket, read the configured issue tracker and triage-label mapping before delegation. Requested audits use the same readiness rules regardless of maintainer availability. If required configuration is unavailable, follow setup-omskills and its scoped authorization gate before delegation, including in headless runs. Read-only audit leaves return missing prerequisites to their responsible caller instead of writing setup. Untracked prompt audits require neither configuration.
Fix the reference intent
Before delegation, read the complete original request and every artifact it explicitly requires. For a tracked Ticket, also read the complete final Issue body, labels, comments, incorporated Agent Brief, relations, governing domain terms, ADRs, and repository rules. The final Ticket Issue must contain or identify every accepted outcome, scope boundary, required workflow or order, deliverable, acceptance criterion, relation, and completion condition; conversation and audit history supply no hidden implementation requirement.
Fix one reference intent for the exact contract version. Record its requested outcome, scope, required actions and order, deliverables, completion point, explicit deferrals, and ambiguities that could materially change any of them. Do not infer adjacent work. This step is complete only when the reference is stable before any delegated pass.
If the accepted sources do not determine material authority or the contract
changes materially after the reference is fixed, choose FAIL, record it as
specified below, and end. The changed contract requires a new Prompt Audit;
evidence from the older version is stale.
When the maintainer explicitly waives the comprehension audit for the exact
contract, skip the agent passes and consider only BYPASS or FAIL through the
fit and status rules below. The waiver satisfies an execution gate; it does not
select the Ticket into a Mission, cannot be inferred, and is never represented
as PASS.
Select isolated pass delivery
Read model-routing before selecting models for the
interpreter and reviewer. Before reading relative links, run
cd '<loaded-skill-directory>' && pwd -P with this loaded file's directory to
obtain the physical base, then resolve links against that printed directory.
Resolve the source symlink before applying ..; read linked files even when
their skills are absent from the discovery list. Use model-routing's
Prompt Audit preference as
an adaptable starting point, honoring explicitly selected routes and the actual
comprehension/comparison task. Apply routing through lifecycle fields only,
without adding coordinator assessments or routing rationale to either pass's
restricted semantic inputs. A lower-tier model understanding a prompt is
evidence for that run, not proof that every other model will interpret it
identically.
Every delegated pass is a fresh, independent, read-only, non-delegating leaf that performs its assigned comparison directly. Disposable notes are allowed under Working files, which must be read before using them; keep the audited sources unchanged and each pass limited to its permitted inputs. A role or name does not grant isolation, tools, or delivery behavior. Never continue a prior pass session or give a later pass hidden access to it. Explicit maintainer recovery may replace a mechanically settled but incomplete pass with a fresh isolated pass before terminal status recording. Keep the fixed reference and required role inputs unchanged, retain failed-attempt evidence in the audit record, and preserve interpreter-before-reviewer order. Unknown acceptance is not settled failure. This exception does not rerun a completed semantic judgment, edit the contract, or reopen a terminal audit.
Before each launch, preflight the tools and providers required for that pass and
the absence of inherited conversation. Where the active harness exposes lineage
controls, inherit the existing depth ceiling and set the child's direct-child
ceiling to zero or remove delegation capability. A designated pass leaf performs
its assigned comparison directly without launching another pass. Missing
isolation or capability requires FAIL unless explicitly authorized recovery
can establish a fresh valid pass; a role's absolute depth is not itself a
failure.
Choose delivery from actual harness mode:
- A root interactive coordinator may use the active harness's documented asynchronous delivery. After acceptance it does not wait, sleep, or poll; it resumes the audit from the matching completion notification.
- A print or managed nested coordinator uses direct delivery, as may a root RPC coordinator for dependent work when supported. Direct settlement returns once through the pending call and emits no later asynchronous completion notification.
Run the passes sequentially even when asynchronous delivery is available: the interpreter must settle before the reviewer starts. Never issue these passes as concurrent siblings or assess the interpreter for the reviewer.
For every pass, require a mechanically completed terminal outcome and a complete
decision-bearing response. When terminal text is bounded, recover the complete
response from the returned native session reference or another predeclared
result channel before assessment. Temporary transport is not durable audit
history; preserve the required status and evidence as specified below. Reading
persisted evidence does not add context to the child. If the pass is failed, interrupted, cancelled, missing
its response, or cannot be recovered without weakening isolation, apply only an
already authorized fresh-pass recovery as defined above; otherwise record FAIL
and end. A partial response cannot support PASS, and recovery cannot reuse the
failed child's context.
Run two isolated agent passes
Start one fresh agent for the interpreter pass and, only after it settles, another fresh independent agent for the reviewer pass. Beyond baseline harness instructions, both passes receive only the inputs listed for their role. Neither receives parent conversational turns or hidden coordinator analysis.
1. Run the interpreter pass
Give the interpreter only:
- the original request;
- artifacts that the request explicitly requires; and
- this question: "What do you understand you are being asked to do?"
Require a reconstruction of the requested outcome, scope boundaries, required actions and order, deliverables, completion point, and ambiguities that could materially change any of those items. Keep the interpreter read-only and non-delegating. It explains the request as written without executing it, revising it, or adding unstated requirements.
Interpreter settlement is complete only when its full decision-bearing response is available to the coordinator and can be passed unchanged to the reviewer.
2. Run the reviewer pass
After interpreter settlement, give the reviewer only:
- the complete final Ticket Issue and fixed reference intent for a tracked audit, or the original request and fixed reference intent for an untracked audit;
- artifacts explicitly required by that request; and
- the interpreter's complete response.
Withhold any coordinator assessment, desired verdict, or desired answer. Keep the reviewer read-only and non-delegating. Require one adversarial comparison: actively challenge semantic equivalence across every requested outcome, scope boundary, required action and order, deliverable, completion point, and material ambiguity. Continue after the first divergence and return every supported addition, omission, or change with quoted or paraphrased evidence and its semantic consequence; there is no finding quota or top-findings cutoff. State problems directly without sugar-coating or softening their impact. Compare meaning, not wording or the reviewer's preferred implementation workflow, and invent no divergences to satisfy the adversarial role.
Require PASS or DIVERGENCE with the complete findings and any coverage or
evidence limitations. Reviewer settlement is complete only when all comparison
dimensions have been examined and its full decision-bearing response is
available to the coordinator; incomplete coverage cannot support PASS.
3. Adjudicate both passes
Only after both passes settle, compare the original request, fixed reference intent, interpreter response, and reviewer judgment. The coordinator, not either delegated agent, owns the result.
Treat a difference as material semantic divergence only when it changes the understood outcome, scope, required workflow or order, deliverables, or completion point. Compression or omission of an enumeration is not material when its governing boundary remains intact. Do not add release work, tests, artifacts, fallbacks, documentation, or implementation details unless the fixed reference intent requires them.
For every reported difference:
- If the fixed reference determines one clear meaning and the differing reading is not supported, record that adjudication and continue.
- If plausible readings materially differ, authority remains unresolved, or
fixing the ambiguity would change the audited contract, choose
FAILand require a separate contract correction and fresh Prompt Audit.
Choose PASS only when no material semantic divergence survives adjudication.
Adjudication does not edit the contract, run confirmation passes, or repeat
semantic comparisons to obtain a preferred verdict. Fresh-pass recovery applies
only to incomplete evidence under the explicit authorization above.
Check implementation-unit fit when applicable
Treat any semantic PASS or explicit BYPASS above as provisional. When the
audited contract is one repository code or behavior-changing Ticket, read
to-tickets and confirm that it
satisfies the tracer-bullet rules, including fit in one fresh agent context with
room to understand the relevant behavior, implement the end-to-end change, and
verify it. If it does not, choose FAIL and report that decomposition is
required before autonomous delivery. Isolation failure, unresolved material
authority, and one-context-fit failure always produce FAIL. For every other
audited text, this check does not apply.
Record the prompt audit status
Choose exactly one status:
PASS— no material semantic divergence about outcome, scope, required workflow or order, deliverables, or completion survives audit-coordinator adjudication, and every applicable one-context-fit check succeeds.BYPASS— the maintainer explicitly waivesPASSfor this exact contract. Never infer this waiver or represent a bypass as a pass.FAIL— the audit cannot establish equivalent clean-context comprehension, including when isolation fails, material authority remains unresolved, a material divergence survives, or an applicable one-context-fit check fails.
When the execution contract is a tracked issue or an agent brief on one, post a new comment without editing prior audit history:
## Prompt Audit
**Status:** PASS | BYPASS | FAIL **Contract:** <issue or agent-brief reference>
**Basis:** <concise evidence or explicit maintainer authorization>For an untracked prompt, report the same fields to the invoking workflow. A newer status supersedes an older one only when it applies to the same execution contract. A material change to the requested outcome, scope, required workflow or order, deliverables, acceptance criteria, relations, or completion point makes the prior status stale.
For a complete tracked implementation Ticket with stable parent, blocking and
conflict relations and exactly one category role, current PASS or explicit
maintainer BYPASS applies ready-for-agent regardless of availability.
Replace the previous state role, including needs-triage; retain exactly one
category and one state. The Ticket body may contain the whole execution contract
without a separate Agent Brief. On FAIL or material staleness, remove
readiness and restore needs-triage. The audit creates no adjacent work.
Readiness validates the contract; it never selects work or authorizes
implementation.
Complete the audit
Report the recorded status and readiness transition. An audit-only request ends
here; FAIL blocks implementation. An explicit combined audit-and-implement
request already supplies implementation authorization: after PASS (or an
explicitly authorized BYPASS), the owning workflow may continue without
another approval, but only into a fresh implementation context.
The audit-coordinating context must not implement or correct the audited work. Transfer the complete durable contract to a fresh session or clean-context implementation owner, who retains decisions and follows orchestrate's review policy, adjudication, corrections, verification, and delivery. No mandatory dispatcher layer or automatic writer/reviewer loop is introduced. For example, “audit #42” records readiness and stops; “audit and implement #42” continues after PASS through that fresh owner.
Audit boundary
The audit evaluates communication of intent only. Runtime-readiness inspection, test execution, release preparation, and runtime-behavior establishment belong to later delivery work.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

