Map Use Cases

Treat code as evidence for what a user can experience. Produce use-case documentation only: never implement behavior, create tests, or modify application code.

Workflow

1. Bound the target. Read repository instructions, supplied artifacts, domain docs, and the referenced code before asking questions. Identify the included public interfaces and their consumers: human roles, API clients, CLI operators, or external callers. If several boundaries remain plausible, present concrete choices after exploration. Load only the matching branches from references/inspection-lenses.md.

   • Complete when: every included public interface and consumer is named, and adjacent excluded behavior has an explicit boundary.

2. Seed the frontier. Inventory public entry points, navigation, commands, exported interfaces, domain objects and states, permissions, validation, errors, flags, transient states, and observable side effects. Treat existing tests as supporting evidence, not authority. Trace each entry point forward to outcomes and each user-visible state backward to the consumers and actions that reach it. Seed every reachable combination of user, interface, goal, and entry point.

   • Complete when: every discovered public entry point is seeded or excluded with evidence.

3. Expand to a fixed point. For each frontier item, inspect relevant starting states, roles, configuration, allowed and denied actions, meaningful input groups, success and failure outcomes, recovery, state changes, side effects, and newly exposed actions. Add every novel public behavior back to the frontier.

   • Merge cases whose complete observable contract is identical; split cases when an outcome, transition, denial, or visible side effect differs.
   • Write You cannot... scenarios only for enforced limits or explicitly unsupported adjacent actions. Put uncertain absences under Questions To Confirm; do not invent missing product features.
   • When the frontier empties, challenge the map for omitted actors, entry points, states, permissions, validation boundaries, empty/loading/partial states, dependency failures, retry/cancel paths, and side effects. Repeat if the challenge discovers anything.
   • Keep a private coverage ledger for users, interfaces, states, outcomes, and side effects. Do not put this ledger in the guide.
   • Complete when: the frontier is empty, every ledger item is covered, not relevant, or explicitly unknown, and a challenge pass adds no case.