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.

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.