State audit

Skill mskayyali/Stateful/skills/state-audit

A way of designing software where the conditions it can be in are treated as the work, not as edge cases to handle later.

Install

npx -y skills add mskayyali/Stateful --skill state-audit

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
4 stars4 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Audit an existing software feature or surface by deriving an expected, evidence-sourced condition inventory and comparing it with code, tests, designs, telemetry, incidents, support history, requirements, and domain rules. Use to find undesigned or unimplemented lifecycle states, failures, interruptions, and surfaces with file-line evidence and risk-aware prioritisation. Do not call code-only inference independent evidence or turn the output into a bug list.

SKILL.md

3.3 KB, as published. Nobody here has run it

State Audit

Compare an expected condition inventory with observed product handling. Separate intended behavior evidence from implementation evidence.

Procedure

Determine the feature or surface. If the user named a directory or scope, proceed. Otherwise show the detected root and ask for a narrower path or confirmation.
Read STATEFUL.md and existing maps without overwriting confirmed decisions.
Inventory available evidence:
- requirements, policies, research, domain rules;
- analytics, incidents, support history;
- designs and prototypes;
- code, tests, schedulers, enums, data models, dependencies.
Derive the expected inventory first from non-implementation evidence. Use code for structural clues only when necessary and mark those records as hypotheses; code cannot prove what ought to exist.
Build the four lenses: lifecycle states, failures with cause, interruption contexts, and surfaces. Record evidence and confidence per condition.
Inspect actual handling in routes, components, reducers, controllers, jobs, validation, errors, loading/empty branches, tests, stories, templates, notifications, data models, and infrastructure. Cite file:line.
Compare expected and observed behavior. Distinguish:
- undesigned;
- designed but unimplemented;
- implemented without deliberate design;
- implemented but unverified;
- evidence conflict requiring a decision.
Score likelihood, impact, and confidence. Rank by risk, not likelihood alone.
For the top 3–5 gaps, state current behavior, evidence, design/engineering implication, layers, owner needed, and the next acceptance criterion—not a prescriptive fix unless the user asks.
Update the ## Audit section of STATEFUL.md. Preserve evidence sources and known unknowns.
Ask whether to produce or update a v0.2 JSON mirror. New gap records begin at status: discovered; do not invent scope. Preserve scenarios and typed relationships, and keep metadata.maturity: working until the handoff gate passes.

Output

## Evidence consulted
| Type | Reference | What it establishes |

## Expected condition inventory
<four lenses with evidence and confidence>

## Observed handling
| Condition | Status | Evidence | Current behavior |

## Gaps
| Condition | Gap type | Likelihood | Impact | Confidence | Evidence | Implication |

## Top gaps
1. <risk-aware narrative with file:line evidence>

## Known unknowns
- <unconsulted evidence or unresolved domain question>

Failure modes

Claiming independent derivation while using the implementation as the only source.
Treating absence from code as proof that a condition should exist.
Reporting a missing condition without observed current behavior.
Ranking only by traffic.
Conflating design gaps, implementation gaps, and verification gaps.
Auditing an entire product at once.