Skip to content
Skills Library
Programming · Planning

flow-map

/flow-map

Use when the user wants every path through a feature mapped before coding: happy paths, validation and auth failures, network errors, concurrency conflicts, timeouts, and recovery, or asks what are all the paths or for a state diagram.

Licence
MIT
Last repository change
15.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 15.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when the user wants every path through a feature mapped before coding: happy paths, validation and auth failures, network errors, concurrency conflicts, timeouts, and recovery, or asks what are all the paths or for a state diagram.

Original author description

Use when the user wants every path through a feature mapped before coding: happy paths, validation and auth failures, network errors, concurrency conflicts, timeouts, and recovery, or asks what are all the paths or for a state diagram.

How it works

  1. Workflow context
  2. Inputs (ask only if missing)
  3. How to map it
  4. Output format
  5. Anti-patterns to flag
  6. Quality bar
  7. Output contract
Original SKILL.md headings · 94 lines, 691 words
SKILL.md preview
---
name: flow-map
description: "Use when the user wants every path through a feature mapped before coding: happy paths, validation and auth failures, network errors, concurrency conflicts, timeouts, and recovery, or asks what are all the paths or for a state diagram."
---

# Flow map

Map every system state and transition of a feature, happy, failure, timeout, and recovery, before
implementation. Every path becomes a test case.

## Workflow context
- Boundary: this is the system's view (states, failure classes, concurrency, cleanup). `user-flow`
  is the user's view (screens, choices, messages). Reuse its journeys as entry paths; do not
  design screens or copy here.
- Follows `user-flow`, `design-doc`, `api-design`. Feeds `spec-to-impl` and `test-plan`.

## Inputs (ask only if missing)
Spec or PRD (or upstream handoff), endpoints involved, external dependencies, roles and permissions.

## How to map it
1. **Happy path first**: name every state the system passes through and every transition.
2. **Input validation**: per input, what can be invalid (empty, too long, wrong format or type,
   negative, out of range, injection). Group inputs that fail the same way into one path.
3. **Auth and authz**: no token, expired token, wrong role, wrong tenant, deleted or disabled user.
4. **External calls** (DB, API, queue, cache): timeout, refused connection, 5xx, malformed or
   partial response. A timeout after the request was sent means the outcome is **unknown**, not
   failed: map an unknown state resolved by status lookup or reconciliation.
5. **Concurrency**: two actors on the same resource, double submit, lost updates on counters or
   balances. Name the guard (optimistic lock, idempotency key, unique constraint).
6. **Recovery** per failure: retry (only for idempotent or idempotency-keyed operations, bounded by
   the operation's semantics and the provider's limits), surface an error, roll back, compensate,
   dead-letter, or hand to a person.
7. **Cleanup**: for every allocated resource (rows, uploads, messages, external reservations), what
   releases it on each failure path. Financial records are reversed with compensating entries,
   never deleted.

## Output format

### State diagram (Mermaid)
```mermaid
stateDiagram-v2
    [*] --> FormEntry
    FormEntry --> Validating: submit
    Validating --> FormEntry: invalid input
    Validating --> Submitting: valid
    Submitting --> Processing: API accepts
    Submitting --> UserError: non-retryable 4xx
    Submitting --> OutcomeUnknown: timeout after send
    OutcomeUnknown --> Processing: status lookup finds it
    OutcomeUnknown --> Submitting: confirmed not received, retry same key
    Processing --> Success: completed
    Processing --> Compensating: downstream failure
    Compensating --> UserError: compensation done
    Success --> [*]
```

### Path table
| # | Path | Entry state | Exit state | Trigger | Side effects | Cleanup | Test case |
|---|------|-------------|-----------|---------|-------------|---------|-----------|
| 1 | Happy path | FormEntry | Success | Valid submit | Row written, email queued | None | TC-001 |
| 2 | Validation fail | FormEntry | FormEntry | Invalid input | None | None | TC-002 |
| 3 | Timeout after send | Submitting | OutcomeUnknown | API timeout | Pending record | Resolved by lookup | TC-003 |
| 4 | Auth expired | Any | Login | Token expired | None | None | TC-004 |
| 5 | Concurrent edit | Processing | ConflictError | Version mismatch | None | None | TC-005 |
| 6 | Downstream fail | Processing | Compensating | Provider rejects | Partial state | Compensating action | TC-006 |

### Cleanup inventory
| Resource | Allocated when | Released when | Orphan risk | Mechanism |
|----------|---------------|---------------|-------------|-----------|
| Upload | Step 2 | Attached in step 6 | Steps 3-5 fail | Scheduled cleanup |
| Queue message | Step 4 | Consumer acks | Consumer crashes | Dead-letter queue |

## Anti-patterns to flag
- Happy path only, or external calls assumed to succeed.
- "TODO: handle error" on any path.
- A timeout treated as a failure for a non-idempotent operation.
- Allocated resources with no cleanup on failure.
- Concurrency dismissed ("users won't do that").
- Unbounded retry, or retry of an operation with no idempotency guarantee.

## Quality bar
- Every external dependency has its failure paths mapped.
- Every allocation has a cleanup path.
- Unhandled transitions are listed explicitly as out of scope, with a reason.
- Every path has a test case ID; every shared mutable resource has its concurrency case.
- The Mermaid diagram renders.

## Output contract
```yaml
produces:
  - type: flow-map
    format: markdown
    path: "claudedocs/<feature>-flow-map.md"
    sections: [state_diagram, path_table, cleanup_inventory]
    generates_test_cases: true
    handoff: "Write claudedocs/handoff-flow-map-<timestamp>.yaml - suggest: spec-to-impl, test-plan"
```

Versions

RepositoryScoreLicence
This page · omexit/claude-skills-pack100MIT
naticorrea-03/claude-code-skills100MIT
benjoox/code-viz100MIT
Gamebreack/flow-map90MIT

Database snapshot: 13.11.2026 · package version 40c876c7ea5c (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100user-flow
    Use when the user wants user journeys mapped through a feature or product: user flow, user journey, flow diagram, decision points, friction, error states, or edge cases.
  • 90exception-flow-analysis
    Traces how errors and exceptions flow through critical code paths to find swallowed errors and broken propagation. Use when analyzing exception handling on important paths.
  • 100impact-map
    Map everything in this project a change touches: code paths and consumers, APIs, data, jobs, external services, UI, permissions, tests and docs, each with path:line evidence. Use when someone asks what a feature or change would affect, and when a stage (architect) needs the…
  • 100draft-flow
    Use when asked to design a user flow, map how a user moves through a feature, create a wireframe or flow diagram, or document interaction design for a product brief. Examples: "design the flow for X", "map out the user journey", "create a wireframe for this feature", "how should…
  • 100test-scenarios
    Derives QA test scenarios and acceptance test cases from a spec or user story, covering happy paths, edge cases, error states, data variations, and ML quality-bar/eval cases. Use when you need to "write test cases for this story," "figure out what QA should check," "turn this…
  • 100negative-test-generator
    Covers the refusal paths a handler already implements but nothing tests - a batch endpoint that must apply all rows or none, optimistic-concurrency version conflicts between two editors, or a delete that deliberately separates who you are from what you may do from the state the…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.