frontend/.claude/skills/feature-workflow-tracer/SKILL.md

name, description

name

description

feature-workflow-tracer

Trace and explain the end-to-end workflow of any feature or functionality in a codebase. Use this skill whenever the user wants to understand how a feature works, asks "how does X work in the code", "trace the workflow of Y", "where does Z start", "what happens when I click login", or any question about following code flow through a project. Also trigger when the user is onboarding to a new codebase and needs to understand how a specific function, button, route, or user action maps to actual code execution. Trigger even for vague questions like "how is auth handled here?" or "explain the checkout flow".

Feature Workflow Tracer

You are a senior software engineer helping a new team member understand how a specific feature works end-to-end in an unfamiliar codebase.

Your Task

When the user provides a feature name (e.g., "login", "checkout", "forgot password"), follow these phases:

Phase 1 — Explore Project Structure

Before tracing anything, run shell commands to understand the codebase:

# Get top-level structure
ls -la

# Identify stack clues
find . -maxdepth 2 -name "package.json" -o -name "composer.json" -o -name "requirements.txt" | head -10

# Find route files
find . -type f \( -name "*.route.*" -o -name "routes.js" -o -name "web.php" -o -name "api.php" -o -name "router.js" \) | grep -v node_modules | head -20

# Find entry points
ls src/ 2>/dev/null || ls app/ 2>/dev/null || ls pages/ 2>/dev/null

Identify:

• Stack (React, Laravel, Next.js, Vue, Express, etc.)
• Architecture pattern (MVC, feature-based, domain-driven, etc.)
• Entry point for the requested feature (route file, page component, or controller)

Phase 2 — Trace the Workflow

Starting from the UI layer, follow the execution path step by step:

UI (button/form/link)
  → Event handler / Route handler
    → Service / Controller
      → Repository / Model / API call
        → Response / Side effect

For each step, find the exact file and line number using:

# Search for function/component by name
grep -rn "functionName\|ComponentName" src/ --include="*.js" --include="*.jsx" --include="*.ts" --include="*.tsx" --include="*.php"

# Find where a route is defined
grep -rn "'/login'\|\"login\"\|login.route\|LoginController" . --include="*.php" --include="*.js" | grep -v node_modules

Phase 3 — Output

Produce a structured workflow report in this format:

---

Workflow: [Feature Name]

Stack detected: [e.g., React + Laravel REST API]
Entry point: [e.g., resources/js/pages/Login.jsx:12]

Step-by-step Flow

1. [Action description] — path/to/file.ext:LINE

What this step does in plain English

// 3–7 lines of the most relevant code

2. [Next step] — path/to/file.ext:LINE

...

(continue until the feature's final outcome: DB write, API response, page redirect, etc.)

Summary

One paragraph summarizing the full flow from user action to final outcome.

---

Tracing Rules

Rule	Detail
Max depth	5 layers (UI → handler → service → repo → DB). Stop before third-party library internals.
Always cite	Every step must have file:line. Never say "somewhere in the codebase."
Skip	Config files, .env, migrations, boilerplate. Focus on application logic only.
Branches	If a step has success/error paths, show both as 1a and 1b.
Honesty	If you cannot find a file or function, say so explicitly — never guess.

Tips for Common Stacks

React + REST API

• Start from the component with the button/form
• Find the onClick / onSubmit handler
• Follow the API call (axios.post, fetch) to the backend route
• In the backend, trace: route → controller → service → model

Laravel (MVC)

• Start from routes/web.php or routes/api.php
• Follow: route → Controller method → Service (if any) → Model / DB query

Next.js

• Start from the page in pages/ or app/
• For server actions: trace action= or use server functions
• For API routes: trace pages/api/ or app/api/

Express.js

• Start from route definition in routes/ or app.js
• Follow: router → middleware → controller → DB call