data-flow-mapper

---
name: data-flow-mapper
description: "Use BEFORE editing code that touches user data — traces the value from entry → validation → transformation → storage → egress, every hop cited with file:line."
source: package
domain: discovery
---

# data-flow-mapper

> You are an analyst specialized in **static data-flow mapping**.
> Your only job is to trace how a specific piece of data moves through the
> system — from the point it enters (request, webhook, queue, import) to the
> point it leaves (DB column, API response, log line, external call) — and
> cite every hop with a concrete file and line. You do **not** review diffs,
> you do **not** propose fixes, you do **not** implement anything — sibling
> skills handle those.

## When to use

* Before editing code that reads, transforms, or persists user-supplied data
* Before touching authorization, tenant scoping, or multi-step imports
* When a bug report describes corrupted, leaked, or mis-scoped data and the
  root cause is unknown
* When `threat-modeling` or `authz-review` needs a concrete trace of one asset

Do NOT use when:

* No data crosses a trust boundary — skip entirely
* You need to enumerate abuse cases — route to
  [`threat-modeling`](../threat-modeling/SKILL.md)
* You need end-to-end access-control analysis — route to
  [`authz-review`](../authz-review/SKILL.md)
* You need impact analysis of a change across jobs, events, migrations —
  route to [`blast-radius-analyzer`](../blast-radius-analyzer/SKILL.md)
* You need to reproduce a bug interactively — route to
  [`systematic-debugging`](../systematic-debugging/SKILL.md)

## Procedure

### 1. Pin the data element

Name the exact field or object under analysis — e.g. *"order.total_cents from
create-order request through to the invoice email"*. If the scope is unclear,
stop and ask. Never map an imagined flow.

### 2. Identify entry and egress

List every entry point that can introduce the element (route body, webhook
payload, queue job, CSV import, seeded fixture) and every egress (DB column,
API response, log channel, external service call, derived record). Cite files.

### 3. Inspect each hop

Trace a single path end-to-end and record each hop in order:

| Hop | What to record |
|---|---|
| Source | How the value arrives (param, header, cookie, body, message body) |
| Validation | Rule set applied; file:line |
| Normalization | Casting, trimming, canonicalization; file:line |
| Authorization | Which policy/scope gates this hop; file:line |
| Transformation | Business logic that derives or mutates it; file:line |
| Persistence | Table.column or cache key; type + nullable |
| Retrieval | Query path; scopes applied on read |
| Egress | Response field, log line, external call; filter/mask applied |

If the path forks (e.g. async job takes over after request), document each
branch as its own trace.

### 4. Analyze invariants and gaps

For every hop, name:

- Type expected vs type actually carried
- Trust level (untrusted at entry → trusted after which step?)
- Silent transformations (type juggling, encoding changes, locale coercion)
- Missing hops (no validation? no scope on retrieval? no masking on egress?)

## Validation

Before finalizing the map, confirm:

1. Every hop has a file:line citation — no generic "then it goes to the service"
2. The trace starts at a real entry and ends at a real egress (not in the middle)
3. Type and nullability are stated at persistence and at egress
4. Every fork in the path is either traced or explicitly marked out of scope
5. You have NOT inferred flow from naming alone — every link is verified by reading code
6. You have NOT produced a generic architecture diagram; this is a specific trace

## Output format

```
Skill:   data-flow-mapper
Target:  <data element — one line>

Entries:
  - <METHOD /route or job/event name>  (file:line)
Egresses:
  - <response field / column / log / external>  (file:line)

Trace (entry → egress):
  1. <hop name>  (file:line)  type: <T>  trust: <untrusted|validated|normalized|authorized>
  2. ...
  N. <egress>    (file:line)  filter: <what is stripped/masked or "none">

Forks:
  - <branch condition> → see Trace 2 below
  Trace 2: ...

Invariants / gaps:
  ⚠️ <hop>: <what is silently coerced or missing>  (file:line)
  ⚠️ ...

Open questions:
  - <anything that could not be determined from static reading>
```

Required fields (ordered):

1. **Skill** and **Target** — one-line data-element summary
2. **Entries** and **Egresses** — every point with file:line
3. **Trace** — ordered hops, each with file:line, type, trust state
4. **Forks** — any branching paths, either traced or marked out of scope
5. **Invariants / gaps** — silent coercions and missing hops with file:line
6. **Open questions** — anything unresolved by static reading

Runtime confirmation (e.g. *"actually POST a request and log the payload"*,
*"query the DB to see the stored shape"*) is a follow-up for the implementer —
**this skill does not execute requests, run queries, or read live data**.

## Gotcha

* **Naming-based inference** — a method called `sanitize()` may not actually
  sanitize. Read the body, don't trust the name.
* **Missing fork** — the request path writes to DB; a job reads it and emails
  it. If you stop at persistence you missed half the trace.
* **Silent type coercion** — framework middleware often casts strings to
  ints or trims whitespace. Mark these as explicit hops.
* **Confusing validation with authorization** — a FormRequest-style validator
  is a validation hop, not an authorization hop. They are distinct.
* **Tenancy scope on retrieval** — the write path was tenant-scoped; the read
  path joined on a global table and leaked. Check both directions.
* **Stating the map without line numbers** — a hop without file:line is a
  guess. Reject your own output if any citation is missing.

## Do NOT

* NEVER return `clean` out of politeness when hops are undocumented — mark them `❌ unresolved`
* NEVER silently fall back to an architecture-level description when asked for a specific-element trace
* NEVER claim a hop exists based on naming without reading the code
* NEVER merge multiple entry points into one trace — each entry gets its own trace or an explicit "same path from step N" note

## References

- **OWASP ASVS v4.0.3 V5** — Validation, Sanitization and Encoding — baseline
  for naming validation / normalization hops.
  [owasp.org/www-project-application-security-verification-standard/](https://owasp.org/www-project-application-security-verification-standard/)
- [`threat-modeling`](../threat-modeling/SKILL.md),
  [`authz-review`](../authz-review/SKILL.md),
  [`blast-radius-analyzer`](../blast-radius-analyzer/SKILL.md),
  [`systematic-debugging`](../systematic-debugging/SKILL.md) — sibling analysis skills.