jaisonerick/trace-flow

Run this to follow one thing — a value, an event, a request — through every hop of the real code and report exactly what happens to it and where it breaks. This is the move that, done properly during architecture, eliminated fix cycles in past runs (an emit symbol silently tr("_",".")-converted before hitting a contract; a token field renamed mid-chain). Do it the way an engineer does at their desk: click go-to-definition through each call, or set a breakpoint and read the real stack — not by reading files and guessing.

This skill runs in an isolated forked Explore child and returns only its tight conclusion — so the caller's context stays clean.

Procedure

1. Detect the project language and load only that language's toolkit card:

   find ~/.claude/plugins -type f -path '*spec-plugin/references/<lang>.md' 2>/dev/null | head -1
   

   Read the matching card (ruby.md / typescript.md / python.md) for the exact navigate + execute + debugger commands.
2. Fix the start and the end — the entry point (route, emitted event, function call) and the sink you care about (DB column, OpenAPI type, rendered response, another service's input).
3. Walk hop by hop with semantic navigation — never grep-spelunk. Use the card's "Navigate" commands: go-to-definition at each call to step into the next layer (native LSP where available; Ruby uses source_location); find-references to see who feeds/consumes a hop.
4. At each hop, record the transformation the value undergoes: rename, type coercion, string munging (tr/gsub/JSON.parse), serialization, defaulting, truncation. Silent conversions are where contracts break.
5. When static reading is ambiguous, run it — don't speculate. Use the card's REPL eval to see the real value at a hop, or its debugger to capture the exact stack + locals at the point of interest.
6. Compare against the contract — hold the observed end-state against what the spec/OpenAPI/types/another-service expects, and flag every divergence (the payoff).

For a big surface, use Bash (rg/find) to map candidate hops first, then trace the real path. Tool versions resolve via asdf automatically.

Output

TRACE: <start> → <end>
PATH:
  1. <file:line>  <what happens to the value here>
  2. <file:line>  <transformation — e.g. "tr('_','.') → 'customer.kyc.updated'">
  ...
  N. <sink>       <final shape/value>
OBSERVED VIA: <go-to-def reading | REPL eval | debugger breakpoint> at the hops that needed it
DIVERGENCES: <every place real behavior differs from the contract/spec/types — or "none">

Trace and report; don't fix. Be precise about each transformation — a vague trace is worthless. If a hop can't be resolved statically, run it before reporting.