Przejdź do treści
Biblioteka skilli
Programowanie · Analiza

trace-the-flow

/trace-the-flow

Śledzi jedną operację biznesową przez wszystkie warstwy i granice procesów, z cytowaniem każdego kroku, także ścieżek błędów.

Licencja
MIT
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
2
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Śledzi jedną operację biznesową przez wszystkie warstwy i granice procesów, z cytowaniem każdego kroku, także ścieżek błędów.

Wyzwalacze z opisu

what happens when a customer does X
Oryginalny opis (EN)

Follow one concrete business operation end to end through every layer and process boundary - entry point, orchestration, persistence, messaging, downstream calls, and the error and retry paths - producing a sequence narrative with a citation at every hop. Use when you need to know how something actually works before changing it, when asked "what happens when a customer does X", when debugging behavior you cannot explain from reading one file, or when a change lands on a request path you have not walked. Traces one operation deeply rather than mapping the whole system - run repo-recon first for

Jak działa

  1. Why this exists
  2. When this applies
  3. When it doesn't
  4. Prerequisites
  5. Procedure
  6. Output template
  7. Common traps
Sekcje z nagłówków SKILL.md, w oryginale · 176 linii, 1 572 słów
Podgląd SKILL.md
---
name: trace-the-flow
description: Follow one concrete business operation end to end through every layer and process boundary - entry point, orchestration, persistence, messaging, downstream calls, and the error and retry paths - producing a sequence narrative with a citation at every hop. Use when you need to know how something actually works before changing it, when asked "what happens when a customer does X", when debugging behavior you cannot explain from reading one file, or when a change lands on a request path you have not walked. Traces one operation deeply rather than mapping the whole system - run repo-recon first for breadth.
---

# Trace the flow

Walking one operation from end to end.

## Why this exists

`repo-recon` tells you where things are. It does not tell you what actually happens, and in a layered enterprise system those are very different questions. The call path for "customer places an order" typically crosses eight files, two process boundaries, a transaction, a message queue, and three error handlers — none of which is visible from any single file.

The specific danger this skill addresses is **plausible reconstruction**. Reading a controller and a service, it's easy to assemble a mental model that is coherent, confident, and wrong — because the actual dispatch goes through a framework-configured interceptor, or an event listener registered in XML, or a strategy selected by a config value. That model then becomes the basis for a change, and the change breaks something invisible.

A trace with a citation at every hop is the antidote. Where you can't establish a hop, the trace says so rather than bridging the gap with a reasonable guess.

## When this applies

- Before changing anything on a request path you haven't walked
- "What happens when a customer does X?"
- Behavior you can't explain from reading one file
- Debugging where the symptom and the cause are in different components
- Understanding an integration before modifying it

## When it doesn't

- You need breadth, not depth — run `repo-recon`
- The system is small enough to read outright
- You need the data model rather than the control flow — that's `data-archaeology` *(fde-data)*; if unavailable, record the data-model gap rather than claiming a complete analysis.
- You need to know *why* the code is shaped this way — that's `git-archaeology`

## Prerequisites

Resolve `<workspace>` before reading or writing artifacts: read `../_shared/workspace-conventions.md` and follow its location and header rules. All artifact paths below use that resolved workspace. Preserve existing sections when appending.

- `<workspace>/02-system-map.md` — you need to know the entry points before following one
- Ideally `<workspace>/01-environment.md` — being able to *run* the flow turns `[inferred]` hops into `[confirmed]` ones cheaply

## Procedure

### 1. Pick exactly one operation, named in business terms

Not "the OrderController" — **"a customer places an order with a saved card."**

Two reasons. A business-named trace is findable later by someone who doesn't know the class names, and it forces you to pick a *concrete* path rather than a general one. "Order placement" branches; "order placement with a saved card, in EUR, for an existing customer" does not.

Where variants matter, trace the main one and note the branch points. Tracing every variant at once produces a document nobody can follow.

### 2. Find the true entry point

From the system map. Be careful here: the apparent entry point is often not the first thing that runs. Filters, middleware, interceptors, and authentication layers execute before the handler, and they frequently do things that matter — tenant resolution, transaction demarcation, request mutation.

Check what's configured to run before the handler, not just the handler.

### 3. Follow each hop, citing as you go

At every step record: **what is called, where it's defined, what it does, and what it passes on.**

The discipline that makes this useful is refusing to skip. When you can't find where control goes next, you have hit indirection — read `references/following-indirection.md`, which covers dependency injection, dynamic dispatch, event buses, reflection, config-driven wiring, aspect-oriented interception, and code generation. Those mechanisms are why a call path disappears, and each has a way of being resolved.

If after that you still can't establish the next hop, **write the gap into the trace**:

> `OrderService:88` publishes `OrderPlaced`. Consumers not established `[unverified]` — no subscription found in this repo; likely in another service. Resolve by searching the org's repos for the event name, or asking the platform team.

A trace with a labelled gap is useful. A trace that bridges the gap with a plausible guess is dangerous, because it reads identically to the parts you verified.

### 4. Mark every boundary crossing

Boundaries are where behavior gets surprising and where changes break things. Flag each one explicitly:

| Boundary | Why it matters |
|---|---|
| **Process / network** | Can fail, time out, retry, or partially succeed |
| **Transaction** | Where it starts, commits, rolls back — and what's *outside* it |
| **Thread / async** | Ordering is no longer guaranteed; context may not propagate |
| **Message queue** | Delivery may be at-least-once; consumers may be idempotent, or may not be |
| **Team ownership** | Changes here need coordination, not just code |

The transaction boundary deserves particular attention. Work that happens outside the transaction — an email, an event publish, a cache write — will not roll back, and that asymmetry is the source of a large share of production data inconsistencies.

### 5. Follow the unhappy paths

Most traces only follow the success case, which is the least interesting one. For each hop ask: what happens if this fails?

- Is the exception caught, and where?
- Is it retried? How many times, with what backoff, and is the operation idempotent?
- Is there a timeout, and what is it? An unset timeout is a finding.
- Is there a circuit breaker or fallback?
- What does the caller see?
- Is anything left in an inconsistent state?

Retry against a non-idempotent operation is a bug waiting for a slow downstream. It is common, it is invisible in the success path, and finding one is often the most valuable output of a trace.

### 6. Verify by running it, where you can

If you can execute the flow, do. Add logging or a breakpoint and confirm the path you reconstructed is the path taken. This is the cheapest possible upgrade from `[inferred]` to `[confirmed]`, and reconstructions are wrong more often than they feel.

Where you can't run it, say so in the Confidence line.

### 7. Stop at the boundary of your question

A trace can expand forever — every downstream call is another trace. Stop when you've covered the operation you named, and record downstream systems as endpoints rather than following into them.

If a downstream turns out to be where the interesting behavior is, that's a *second* trace with its own document.

## Output template

Write to `<workspace>/traces/<business-operation>.md`:

```markdown
# Trace — <operation in business terms>

**Engagement:** <name>
**Author:** FDE
**Date:** <YYYY-MM-DD>
**Status:** draft
**Source revision:** <repo>@<short SHA>
**Confidence:** <how much is confirmed by running it vs. read>
**Verified by running:** yes / no — <how>

## Operation
<The concrete scenario, in business terms. State the variant traced and the ones not traced.>

## Sequence

| # | Where | What happens | Boundary | Confidence |
|---|---|---|---|---|
| 1 | `AuthFilter:34` | Resolves tenant from JWT, sets thread-local | — | confirmed |
| 2 | `OrderController:44` | Validates payload, maps to command | — | confirmed |
| 3 | `OrderService:88` | **Opens transaction** | transaction start | confirmed |
| 4 | `InventoryClient:22` | HTTP POST to inventory-service, 2s timeout | **network** | confirmed |
| 5 | `OrderRepository:140` | Inserts order + lines | — | confirmed |
| 6 | `OrderService:132` | **Commits** | transaction end | confirmed |
| 7 | `EventPublisher:19` | Publishes `OrderPlaced` — **outside the transaction** | queue | confirmed |
| 8 | ? | Consumers unknown | — | **unverified** |

## Boundaries
| Boundary | Where | Implication |
|---|---|---|
| Transaction | opens `OrderService:88`, commits `:132` | Event publish at `:19` is outside it — will not roll back |

## Error and retry behavior
| Hop | On failure | Retry | Idempotent? | Caller sees |
|---|---|---|---|---|
| 4 | `InventoryException` | 3×, 100ms fixed | **No** `[confirmed: no idempotency key sent]` | 503 |

## Findings
<Things worth someone's attention. This section is often the real output.>

- Retry at hop 4 is not idempotent — a slow downstream could double-reserve inventory `[confirmed]`
- Event publish at hop 7 is outside the transaction — a crash between commit and publish loses the event `[confirmed]`

## Gaps
| # | What's unknown | Why it matters | To resolve |
|---|---|---|---|
| 1 | Consumers of `OrderPlaced` | Can't assess blast radius of a schema change | Search org repos, or ask platform team |

## Not traced
<Variants and downstream systems deliberately excluded, so a reader knows the limits.>
```

## Common traps

**Bridging a gap with a plausible guess.** The failure this skill exists to prevent. An unverified hop must be labelled, because it reads identically to a verified one.

**Missing what runs before the handler.** Filters, middleware, and interceptors do real work and are invisible in the handler.

**Only tracing the success path.** The error paths are where the surprises and the findings are.

**Not marking the transaction boundary.** Work outside the transaction doesn't roll back, and that asymmetry causes a large share of data inconsistencies.

**Ignoring timeouts and idempotency.** An unset timeout and a non-idempotent retry are both common and both serious.

**Tracing "order placement" instead of a concrete scenario.** The general case branches; the document becomes unreadable.

**Following every downstream.** Each is its own trace. Record it as an endpoint and stop.

**Naming the trace after a class.** `traces/OrderController.md` is unfindable by the person who needs it. Name the business operation.
Pliki w paczce (2)
  • SKILL.md 10 KB
  • references/following-indirection.md 7 KB

Wersje

W bazie nie ma innych skilli o nazwie trace-the-flow.

Migawka bazy z 13.11.2026 · wersja paczki bcebb0a025a7 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100trace-data-flow
    Śledzi przepływ danych w istniejącym projekcie od wejścia przez walidację i zapis aż do wyniku, wraz z dowodami z kodu.
  • 90trace
    Śledzi fragment kodu do wszystkich miejsc, gdzie zaczyna się jego przepływ, i do danych, których dotyka, także przez zainstalowane pakiety.
  • 100oldhand-trace
    Mapuje rzeczywistą ścieżkę zmiany lub błędu krok po kroku od punktu wejścia do wyniku, z plikiem i linią, konfiguracją, granicami zaufania oraz wszystkimi wywołującymi kodu.
  • 90sequence-flow
    Śledzi prawdziwe wywołania w kodzie, by pokazać, jak żądanie lub funkcja działa w praktyce, i zapisuje diagram przepływu w dokumentacji.
  • 90trace-the-flow-end-to-end
    Mapuje każdy krok nowego pola lub stanu od wejścia użytkownika do zapisu i odczytu, szuka miejsc cichej utraty danych i nazywa test dla każdego styku.
  • 100code-flow-tracer
    Śledzi ścieżki wykonania kodu i przepływ danych: jak działa dana funkcja, co się dzieje przy wywołaniu i skąd pochodzą dane.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.