Trace frontend flow

Trace Frontend Flow

Purpose

Use this skill to reconstruct frontend user flows from code with an evidence trail. The goal is to connect route entry, user action, component behavior, state changes, data fetching, and UI feedback without inventing missing runtime behavior.

Core Rules

• Prefer code evidence over inference. Mark anything without direct evidence as inferred or unconfirmed.
• Build a route/page coverage matrix before writing the narrative flow.
• For every core step, record file path plus component, hook, store, action, loader, server action, or configuration key.
• Treat runtime feature flags, dynamic routes, generated clients, CMS data, and unavailable backend code as uncertainty unless evidence is visible.
• Keep independent user flows and frontend projects in separate output directories.

Output Layout

• Default each frontend analysis leaf to docs/trace-code-flow/<flow-slug>/frontend/<project-slug>/.
• Derive <flow-slug> from the user or business goal in lowercase hyphen-case, such as checkout or user-login.
• Derive <project-slug> from the 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 frontend applications, create one <project-slug> directory per application.
• 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 app model.

   • Identify framework and rendering model: React, Next.js, Vue, Nuxt, Svelte, Remix, Angular, SPA, SSR, SSG, Server Components, or server actions.
   • Use the user-provided path first.
   • If the path is missing, infer likely frontend roots from repository structure and document the assumption.

2. Discover route and page entries.

   • Look for router configuration, filesystem routes, layouts, page components, loaders/actions, middleware, guards, and entry bundles.
   • Use references/frontend-search-patterns.md when choosing search terms.
   • Produce a route/page coverage matrix with status: expanded, partially expanded, or not expanded.

3. Trace selected user flows.

   • Start at navigation or visible page state.
   • Continue through user event, handler, validation, state update, API call, cache mutation, navigation, toast/modal feedback, and final UI state.
   • Include critical branches: loading, empty, error, disabled, unauthorized, stale cache, optimistic update rollback, form validation failure, and retry behavior.

4. Reconstruct component and state relationships.

   • Identify container/page components, presentational components, hooks, context providers, stores, query keys, mutations, selectors, and derived state.
   • Record data ownership: URL params, local state, global store, query cache, server props, persisted storage, or browser APIs.
   • Trace props/callbacks only as far as needed for the requested flow.

5. Reconstruct frontend-to-backend interactions.

   • Identify fetch/axios/GraphQL clients, SDKs, generated API clients, server actions, route handlers, and BFF calls.
   • Record endpoint, method, request shape, response shape, error handling, timeout/retry/cache policy, auth header, and idempotency key when visible.
   • If backend code is unavailable, mark it as cross-boundary not expanded.

6. Generate artifacts.

   • Use references/frontend-report-template.md for the report structure.
   • In each selected frontend leaf directory, generate:
     • route-coverage-matrix.md
     • analysis-report.md
     • user-flow.mmd
     • component-data-flow.mmd
     • api-interaction.puml when API sequence details matter
   • Mermaid is preferred for user flow and component/state flow inside Markdown reports.

7. Validate diagrams with graceful fallback.

   • Use Mermaid CLI or Markdown preview for .mmd when available.
   • For PlantUML sequence diagrams, 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.
   • Renderer-produced Mermaid/PlantUML PNG or SVG is valid evidence; generative or manually produced images are not.

Evidence Format

Use this table shape for important steps:

Step	Behavior	Evidence	Evidence Type	Confidence
S1	Submit checkout form	src/pages/Checkout.tsx#handleSubmit	direct	high

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

Completion Checklist

• Route/page coverage matrix lists all discovered frontend entries in scope.
• Report explains scope, assumptions, user flow, component/state flow, API interactions, UI states, and risks.
• Each core step has code evidence.
• Backend or external system boundaries are explicit; unavailable code is listed as not expanded.
• Mermaid/PlantUML files and report describe the same flow and do not contradict each other.
• Diagram validation result or fallback reason is recorded.