agentleFS
suibianqugenichenghaolesuibianqugenichenghaole/pm-workflow-system/skills/public/state-audit/SKILL.md

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.

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
  1. Distinctive:

    Use this skill to stop product demo work from looking complete while hiding state incompleteness.

    line 19
  2. Very specific:

    If a suspected missing state actually points to a changed rule baseline, say so and recommend routing through rule-change-signal.

    line 35
  3. Distinctive:

    Do not require a full spec before auditing.

    line 48
  4. Distinctive:

    Treat a state as a meaningfully different condition that changes what the user sees, can do, or should understand.

    line 52
  5. Distinctive:

    Do not reduce state only to visual UI modes.

    line 64
  6. Distinctive:

    Do not pretend coverage exists if it is only vaguely hinted.

    line 95
  7. Distinctive:

    Always scan across these classes when relevant:

    line 99
  8. Distinctive:

    Not fatal to understanding, but likely to create review friction, rework, or hidden ambiguity.

    line 153
  9. Very specific:

    If the second case is more likely, say it is not only a state gap and recommend rule-change-signal or upstream clarification.

    line 164
  10. Distinctive:

    no meaningful freeze impact

    line 169
  11. Distinctive:

    add 2-3 missing core states before next review

    line 181
  12. Distinctive:

    Prefer this compact structure:

    line 188
  13. Distinctive:

    Use these tests when unsure.

    line 211
  14. Distinctive:

    If this state is absent, would the user misunderstand what is happening or what they can do?

    line 215
  15. Distinctive:

    If yes, treat it as higher priority.

    line 217
  16. Distinctive:

    If no, treat the gap as high risk.

    line 223
  17. Distinctive:

    If not, scan for transition states.

    line 229
  18. Distinctive:

    If yes, increase scrutiny.

    line 235
  19. Distinctive:

    Read these only when useful:

    line 258
  20. Distinctive:

    When the audit finds mainly presentation-level omissions:

    line 266
  21. Distinctive:

    keep the issue inside demo work

    line 267
  22. Distinctive:

    When the audit finds missing states that materially distort current logic:

    line 269
  23. Distinctive:

    When the audit finds that the "missing state" is actually a rule dispute:

    line 273

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.md for demo-generation expectations around pages, modules, states, and interactions
  • ../pm-demo-design/references/design-context-template.md when state expression needs to respect audience/product context
  • ../pm-requirement-intake/references/readiness-gates.md when state completeness affects freeze-stage judgment
  • ../rule-change-signal/SKILL.md when 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-signal or upstream clarification instead of pretending it is only a state-list issue

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.