call-sequence-tracer

name	call-sequence-tracer
description	Use when the user asks for call order, startup order, command lifecycle, request lifecycle, experiment lifecycle, skill routing, agent dispatch, or how execution moves through a codebase.

Call Sequence Tracer

Mission

Explain an execution flow as a numbered, evidence-backed sequence. The main output is the call sequence and evidence table. Mermaid is optional and only supports comprehension.

Boundaries

• Keep confirmed and inferred steps separate.
• Do not invent calls to make a prettier diagram.
• Follow the native architecture boundary in ../references/native-boundaries.md; do not read .env secrets.
• Do not update architecture-map.json unless the user explicitly asks to refresh architecture assets.
• Prefer one narrow, named flow over a vague whole-project trace.

Load References

Read:

• ../references/native-boundaries.md
• references/flow-types.md
• references/sequence-output-format.md
• references/sequence-examples.md

Use only the sections matching the detected flow type. Load sequence-examples.md when the flow has branches, async boundaries, ML lifecycle, or plugin/agent routing.

Workflow

1. Identify the flow scope.
   • If the user names a command, route, script, experiment, worker, skill, or agent, trace that exact surface.
   • If the user is vague, choose the smallest useful flow and state the assumption.
2. Locate the entrypoint.
   • CLI: package bin, command router, script.
   • Web/API: route, controller, handler, middleware.
   • ML: train/eval script, config loader, experiment runner.
   • Plugin/agent: catalog, skill command, profile resolver, dispatcher.
3. Follow execution one boundary at a time.
   • entrypoint -> parser/router -> dispatcher/controller -> service/module -> state/output
   • include async/event/worker boundaries when present
   • include config/state touched at the step where it is read or written
   • record flow context: trigger, entrypoints, state/config touched, artifacts produced, external boundaries, tests, confidence summary, and unknowns.
4. Record evidence for every important step.
   • cite project-relative paths
   • include optional line spans when already known or easy to locate
   • mark direct code evidence as confirmed
   • mark naming/docs/structure as inferred
5. Identify tests and missing tests.
   • Report existing coverage when found.
   • Suggest tests when the flow is important but uncovered.
6. Model complex control flow explicitly.
   • Use branch, async boundary, and failure path shapes from sequence-examples.md.
   • Do not collapse generated dispatch, callbacks, queues, watchers, or runtime overlays into a single vague step.
7. Produce the sequence output.
   • Use the format in sequence-output-format.md.
   • Include Mermaid sequenceDiagram only when ordering is clearer visually.

Quality Bar

• A reader should be able to follow the flow without opening the code first.
• Each step should explain what changes: control, data, state, config, artifact, external boundary, or user-visible output.
• The flow summary should be useful even when no diagram is rendered: trigger, entrypoint, state, artifacts, external boundaries, tests, and unknowns must be explicit.
• Branches, failure paths, async callbacks, and generated dispatch should be called out rather than flattened away.
• Unknown steps should remain visible.