Trace Backend Flow

Trace Backend Flow

Purpose

Use this skill to reconstruct backend business flows from code with an evidence trail. The goal is not to guess the architecture; it is to enumerate discovered entry points, trace representative and critical flows, and disclose uncertainty.

Core Rules

• Prefer code evidence over inference. Mark anything without direct evidence as inferred or unconfirmed.
• Build an entry coverage matrix before writing the narrative flow.
• For every core step, record file path plus function, method, class, or configuration key.
• Do not claim invisible services, generated code, runtime registration, or unavailable repositories were fully analyzed.
• Keep independent business flows and backend projects in separate output directories.

Output Layout

• Default each backend analysis leaf to docs/trace-code-flow/<flow-slug>/backend/<project-slug>/.
• Derive <flow-slug> from the business goal in lowercase hyphen-case, such as create-order or user-login.
• Derive <project-slug> from the service/application manifest or configuration name; fall back to the normalized project directory name.
• If one request covers multiple independent flows, create one <flow-slug> directory per flow.
• If one flow crosses multiple backend projects or services, create one <project-slug> directory per project.
• Treat a user-provided output path as the root for this layout unless the user explicitly identifies it as the final leaf directory.

Workflow

1. Determine scope and assumptions.

   • Use the user-provided path first.
   • If the path is missing, infer likely backend roots from repository structure and document the assumption.
   • Record exclusions such as tests, generated files, vendor code, or unavailable sibling repositories.

2. Discover backend entry points.

   • Look for HTTP/API controllers, RPC handlers, CLI commands, scheduled jobs, MQ consumers, event listeners, webhooks, and framework route configuration.
   • Use references/backend-search-patterns.md when choosing search terms.
   • Produce an entry coverage matrix with status: expanded, partially expanded, or not expanded.

3. Trace each selected core flow.

   • Start at user/system trigger.
   • Continue through validation, authorization, orchestration, domain decisions, transaction boundaries, persistence, event publication, external calls, and response/acknowledgement.
   • Include critical failure paths: validation failure, idempotency hit, downstream timeout, retry exhausted, transaction rollback, compensation, dead-letter, or degraded response.

4. Reconstruct system interactions.

   • Separate internal calls from external dependencies.
   • Identify DB, cache, MQ, object storage, third-party APIs, SDKs, RPC/HTTP clients, and shared libraries.
   • For cross-service calls, record service/repository boundary, protocol, endpoint/topic, contract source, timeout, retry, circuit breaker/degradation, and idempotency key when visible.

5. Generate artifacts.

   • Use references/backend-report-template.md for the report structure.
   • In each selected backend leaf directory, generate:
     • coverage-matrix.md
     • analysis-report.md
     • flow-core.puml
     • system-interaction.puml
   • PlantUML is preferred for backend activity and sequence diagrams.

6. Validate diagrams with graceful fallback.

   • Use $plantuml-check when it is installed and available.
   • If it is unavailable, perform a minimal static check and state that render-level validation was not completed.
   • Do not send diagrams to remote PlantUML or Kroki services unless the user explicitly permits it.
   • PlantUML-compatible PNG/SVG rendering is valid evidence; generative or manually produced images are not.

Evidence Format

Use this table shape for important steps:

Evidence types: direct, configuration, test, generated, inferred, unconfirmed.

Completion Checklist

• Entry coverage matrix lists all discovered backend entries in scope.
• Report explains scope, assumptions, main flow, failure paths, data/state changes, external interactions, and risks.
• Each core step has code evidence.
• Cross-service or cross-repository jumps are explicit; unavailable downstream code is listed as not expanded.
• Diagram files and report describe the same flow and do not contradict each other.
• Diagram validation result or fallback reason is recorded.