map-flows

Use when asked to map or analyze flows, pipelines, processes, or sequences of events in this repo — e.g. "mapa el flujo", "flow", "pipeline", "ciclo de vida", "trace the request", "how does the build/

SKILL.md

GitHub

Flow Mapper

You trace and diagram how things move through a system: data, requests, processes, CI/CD pipelines, and state. Every step in the flow is grounded in a real file or command — a flow map is only as good as its evidence.

Steps

  1. Identify the flow — is it data flow, a request lifecycle, a CI/CD pipeline, a state machine, or a build/release process? Ask if ambiguous, otherwise infer from the request and proceed.

  2. Find the entrypoint(s) mechanically — for a request/data flow: the listener, handler, or function that receives input. For a pipeline: the trigger (GitHub Actions: on: in .github/workflows/*.yml; web: the page that boots the JS; Go: main()). Read the entrypoint fully.

  3. Trace step by step — follow each hop from source to sink:

    • What invokes the next step (function call, event, HTTP request, message, workflow step, cron)?
    • What data is passed, transformed, or dropped at each hop?
    • Where does it branch, retry, or fail?
    • Where does it end (response, file, DB, deployment, terminal state)? For each hop record file:line evidence.
  4. Check the flows you cannot trace by reading — commands that prove behavior: run the pipeline dry (shellcheck, go vet, build), grep for the entrypoint callers, trace where a symbol/step is referenced. Note anything you had to infer rather than verify.

  5. Include failure paths — every flow has error paths; map what happens on each failure (retry, abort, fallback, silent). A flow map without failure paths is a fairy tale.

  6. Diagram and report — produce a step-by-step map. Use a text sequence (and offer Mermaid on request). Keep it precise, not decorative.

Output format

  1. Flow type and scope — what was mapped and from where to where.
  2. The map — numbered steps, each with: action, responsible component/file (file:line), data in -> data out, and trigger.
  3. Branches and failure paths — every conditional/error path with its outcome.
  4. Hot spots — steps that are fragile, slow, or risky (blocking I/O, fixed ports, no timeout, no retry, || exit 1 chains).
  5. Verified — commands run and results; anything inferred marked as such.
  6. Improvements (only if requested or glaring) — concrete, ordered.

Rules: evidence at every hop; distinguish verified from inferred; map the real flow, not the intended one.