state-audit
Skill1 starsChanged 4 months agoMITView on GitHub
Audit whether a demo, page plan, flow draft, or prototype sufficiently covers the states that matter, and identify likely missing, weak, or misleading states before downstream freeze or delivery. Use when Codex needs to check happy-path bias, missing outcomes, missing exceptional states, or weak state expression in product demo work.
In this repository17 other files it gives its agents.
- audience-judgment-framingSkill
- embedded-prd-auditSkill
- freeze-readiness-checkSkill
- memory-export-summarySkill
- pm-demo-designSkill
- pm-design-absorptionSkill
- pm-devil-advocateSkill
- pm-embedded-prdSkill
- pm-prd-writerSkill
- pm-project-opsSkill
- pm-react-prototype-executionSkill
- pm-requirement-intakeSkill
- pm-requirement-reverse-auditSkill
- pm-value-anchorSkill
- prototype-export-intakeSkill
- request-triageSkill
- rule-change-signalSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
23 rules. About 0 are common, 21 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈21
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 19
Use this skill to stop product demo work from looking complete while hiding state incompleteness.
- Very specific: line 35
If a suspected missing state actually points to a changed rule baseline, say so and recommend routing through rule-change-signal.
- Distinctive: line 48
Do not require a full spec before auditing.
- Distinctive: line 52
Treat a state as a meaningfully different condition that changes what the user sees, can do, or should understand.
- Distinctive: line 64
Do not reduce state only to visual UI modes.
- Distinctive: line 95
Do not pretend coverage exists if it is only vaguely hinted.
- Distinctive: line 99
Always scan across these classes when relevant:
- Distinctive: line 153
Not fatal to understanding, but likely to create review friction, rework, or hidden ambiguity.
- Very specific: line 164
If the second case is more likely, say it is not only a state gap and recommend rule-change-signal or upstream clarification.
- Distinctive: line 169
no meaningful freeze impact
- Distinctive: line 181
add 2-3 missing core states before next review
- Distinctive: line 188
Prefer this compact structure:
- Distinctive: line 211
Use these tests when unsure.
- Distinctive: line 215
If this state is absent, would the user misunderstand what is happening or what they can do?
- Distinctive: line 217
If yes, treat it as higher priority.
- Distinctive: line 223
If no, treat the gap as high risk.
- Distinctive: line 229
If not, scan for transition states.
- Distinctive: line 235
If yes, increase scrutiny.
- Distinctive: line 258
Read these only when useful:
- Distinctive: line 266
When the audit finds mainly presentation-level omissions:
- Distinctive: line 267
keep the issue inside demo work
- Distinctive: line 269
When the audit finds missing states that materially distort current logic:
- Distinctive: line 273
When the audit finds that the "missing state" is actually a rule dispute:
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 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
State Audit
Act as a command-style skill for checking whether demo or page work has enough state coverage to be trustworthy.
Core job
Review a page plan, demo draft, prototype, or flow description and output a compact state audit that:
- lists clearly covered states
- identifies likely missing states
- highlights high-risk state gaps
- distinguishes business-critical gaps from minor polish gaps
- recommends what to add before freeze or downstream delivery
Use this skill to stop product demo work from looking complete while hiding state incompleteness.
Boundaries
This skill is responsible for:
- auditing state coverage
- spotting likely missing state classes
- prioritizing state gaps
- judging whether missing states are freeze-risk or only quality debt
This skill is not responsible for:
- fully redesigning the demo
- redoing requirement intake from scratch
- deciding final business truth for disputed rules
- replacing dedicated rule-change classification when the issue is really about changed business logic
If a suspected missing state actually points to a changed rule baseline, say so and recommend routing through rule-change-signal.
Inputs
Work from whatever is available, such as:
- page/module description
- current state list
- flow description
- demo screenshots / code / prototype notes
- requirement skeleton or rule summary
- known triggers and outcomes
- claimed freeze intent, if any
Do not require a full spec before auditing. Use the evidence available.
What counts as a state
Treat a state as a meaningfully different condition that changes what the user sees, can do, or should understand.
State may come from:
- business status
- process step
- eligibility result
- transaction result
- config-driven variation
- loading / empty / error / unavailable condition
- permission or role difference
- historical vs current condition
Do not reduce state only to visual UI modes.
Working flow
1) Identify the audit object
First say what is being audited:
- one page
- one module
- one flow segment
- one multi-page demo round
Then say what level of completeness is expected:
- rough validation coverage
- review-ready coverage
- freeze-ready coverage
2) Extract the obvious covered states
List states that are already explicitly represented or clearly implied.
Examples:
- active
- pending
- paused
- expired
- success
- failed
- empty
- permission denied
Do not pretend coverage exists if it is only vaguely hinted.
3) Scan for likely missing state classes
Always scan across these classes when relevant:
A. Default and basic UI states
- default
- loading
- empty
- error
- disabled
- unavailable
B. Business result states
- success
- failed
- pending
- partially completed
- expired
- paused
- cancelled
- refunded
C. Transition and timing states
- before action
- during action
- after action
- delayed effect
- waiting / processing
- retry / re-entry
D. Role / permission states
- different role visibility
- gated actions
- permission denied
- limited access
E. Config / strategy-driven states
- same page behaves differently under different config
- different labels, tags, warnings, or actions due to config or rule results
F. Historical / compatibility states
- historical data behavior
- stock-user vs new-user behavior
- legacy path vs current path
4) Judge importance of the gaps
Classify each likely gap as:
- critical gap
- important gap
- optional gap
Critical gap
Without it, the page/demo misrepresents the product logic or would mislead freeze/delivery.
Important gap
Not fatal to understanding, but likely to create review friction, rework, or hidden ambiguity.
Optional gap
Nice to have for completeness, but not essential for the current stage.
5) Judge whether the gap is a state problem or a rule problem
Ask:
- is the state missing because the demo forgot to express it?
- or is the state missing because the underlying rule is not actually settled?
If the second case is more likely, say it is not only a state gap and recommend rule-change-signal or upstream clarification.
6) Judge freeze impact
Output one of:
- no meaningful freeze impact
- weak freeze risk
- strong freeze risk
Default heuristics:
- missing critical business states usually create strong freeze risk
- missing basic UI states may create weak or moderate risk depending on stage
- optional states usually do not block freeze by themselves
7) Recommend next move
Examples:
- add 2-3 missing core states before next review
- separate exploratory branch from baseline branch
- route suspected rule change through
rule-change-signal - acceptable for rough demo, but not for freeze
Output format
Prefer this compact structure:
## State audit
- Audit object:
- Completeness target:
- Clearly covered states:
- Likely missing states:
- Critical gaps:
- Important gaps:
- Optional gaps:
- Freeze impact:
- Recommended next move:Be concise, but do not omit:
- clearly covered states
- likely missing states
- freeze impact
- next move
Decision heuristics
Use these tests when unsure.
Test 1: User-meaning test
Ask:
- If this state is absent, would the user misunderstand what is happening or what they can do?
If yes, treat it as higher priority.
Test 2: Rule-truthfulness test
Ask:
- Does the current state set still tell the truth about the underlying business logic?
If no, treat the gap as high risk.
Test 3: Trigger-path test
Ask:
- Have we covered what happens before, during, and after the key trigger or event?
If not, scan for transition states.
Test 4: Special-case blindness test
Ask:
- Are we only covering the main path while hiding edge but meaningful paths like refund, expiry, retry, pause, or history compatibility?
If yes, increase scrutiny.
Typical state gap patterns
Watch for these recurring failures:
- happy path exists, but failure/exception path missing
- active state exists, but pending/paused/expired state missing
- purchase success exists, but cancel/refund/retry missing
- current user path exists, but historical-user path missing
- config-default path exists, but alternative config effects missing
- one role is shown, but role-restricted visibility/action states are missing
Anti-patterns
Avoid these mistakes:
- treating state audit like a pure UI checklist
- listing dozens of theoretical states with no prioritization
- mistaking unresolved rules for mere missing-state presentation
- assuming a polished screen means sufficient state coverage
- blocking freeze over trivial optional states while missing real business-critical ones
References to load when needed
Read these only when useful:
../pm-demo-design/SKILL.mdfor demo-generation expectations around pages, modules, states, and interactions../pm-demo-design/references/design-context-template.mdwhen state expression needs to respect audience/product context../pm-requirement-intake/references/readiness-gates.mdwhen state completeness affects freeze-stage judgment../rule-change-signal/SKILL.mdwhen a missing state may actually reflect changed business logic
Handoff expectations
When the audit finds mainly presentation-level omissions:
- keep the issue inside demo work
When the audit finds missing states that materially distort current logic:
- mark strong freeze risk
- recommend adding them before freeze or delivery
When the audit finds that the "missing state" is actually a rule dispute:
- route it toward
rule-change-signalor upstream clarification instead of pretending it is only a state-list issue
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.

