---
name: docs-analyze
description: Analyze codebase for a specific route or component without browser automation. Pure code analysis for understanding implementation.
---

# Codebase Analysis Workflow

**Goal:** Analyze the codebase to understand how a specific route/feature is implemented, including frontend components, backend handlers, validation rules, and side effects.

**Your Role:** You are a code analyst. You will search and read the codebase to document what a feature does based on its implementation.

---

## ARGUMENTS PARSING

Parse the arguments passed to this workflow. Expected format:
```
/docs:analyze <route-or-component> [--codebase ./src] [--output ./docs]
```

Extract:
- `route` (required) - The route path (e.g., `/campaigns`, `/users/:id`) or component name (e.g., `CampaignList`)
- `codebase` (optional, default: .) - Path to codebase for analysis
- `output` (optional, default: ./docs) - Output directory for analysis report

If route/component is missing, ask: "Please provide the route or component name to analyze."

---

## STEP 1: IDENTIFY RESOURCE

Parse the route/component to identify the resource:

**From route path:**
- `/campaigns` → resource: "campaigns"
- `/users/:id/settings` → resource: "users", subresource: "settings"
- `/api/v1/orders` → resource: "orders"

**From component name:**
- `CampaignList` → resource: "campaigns"
- `UserSettingsForm` → resource: "users", feature: "settings"

---

## STEP 2: SEARCH FRONTEND CODE

Search for frontend code related to this resource:

### 2.1 Find Component Files
Use Glob to find files matching patterns:
- `**/*{Resource}*.{vue,tsx,jsx,ts,js}` (e.g., `*Campaign*.vue`)
- `**/pages/*{resource}*/**` (Next.js/Nuxt pages)
- `**/views/*{resource}*/**`
- `**/components/*{resource}*/**`

### 2.2 Analyze Components
For each relevant file found, extract:

**Event Handlers:**
- `onClick`, `onSubmit`, `onChange`, `@click`, `@submit`
- What actions do they trigger?

**API Calls:**
- `fetch()`, `axios`, `useFetch`, `useQuery`
- What endpoints are called?
- What data is sent/received?

**State Management:**
- `useState`, `ref()`, `reactive()`, Vuex/Pinia stores
- What state is managed locally vs globally?

**Form Fields:**
- Input names, validation attributes
- Required fields, field types

---

## STEP 3: SEARCH BACKEND CODE

Search for backend code handling this resource:

### 3.1 Find Route Definitions

**Laravel:**
- Search in `routes/web.php`, `routes/api.php`
- Pattern: `Route::{method}('{resource}'`

**Express/Node:**
- Search for `router.{method}('/{resource}'`
- Search for `app.{method}('/{resource}'`

**NestJS:**
- Search for `@Controller('{resource}')`
- Search for `@Get()`, `@Post()`, etc.

### 3.2 Find Controllers/Handlers

**Laravel:**
- `app/Http/Controllers/*{Resource}Controller.php`

**Express:**
- `**/controllers/*{resource}*.{ts,js}`
- `**/handlers/*{resource}*.{ts,js}`

### 3.3 Extract Implementation Details

For each handler found, document:

**Validation Rules:**
- Laravel: `$request->validate([...])`, Form Requests
- Express: Joi, Zod, express-validator schemas
- What fields are required? What constraints?

**Database Operations:**
- What models/tables are touched?
- CRUD operations performed

**Side Effects:**
- Emails sent (`Mail::send`, `sendEmail`)
- Notifications (`Notification::send`)
- Events dispatched
- External API calls
- Queue jobs created

**Authorization:**
- What permissions are checked?
- Who can perform this action?

---

## STEP 4: GENERATE ANALYSIS REPORT

Create a markdown file with the structure:

```markdown
# {Resource} - Code Analysis

## Route: {route path}

## Frontend Implementation

### Components Found
- `path/to/Component.vue` - [purpose]

### User Interactions
| Action | Trigger | Handler | Effect |
|--------|---------|---------|--------|
| [Click button] | onClick | handleSubmit | Calls POST /api/... |

### State Management
- [What state is managed and how]

### Form Fields
| Field | Type | Required | Validation |
|-------|------|----------|------------|
| name | text | Yes | min:3, max:255 |

## Backend Implementation

### Routes
| Method | Path | Controller | Action |
|--------|------|------------|--------|
| GET | /campaigns | CampaignController | index |
| POST | /campaigns | CampaignController | store |

### Validation Rules
```
{extracted validation rules}
```

### Database Operations
- Creates/updates `{table}` table
- Relations: [belongs to, has many, etc.]

### Side Effects
- **Emails:** [list emails sent]
- **Notifications:** [list notifications]
- **Events:** [list events dispatched]
- **Jobs:** [list queued jobs]

## Authorization
- Required permissions: [list]
- Middleware: [list]

---

*Analysis generated by docs:analyze*
```

---

## STEP 5: SAVE AND REPORT

1. **Create output directory** if needed
2. **Write analysis file** to `{output}/{resource}-analysis.md`
3. **Report completion:**

```
✅ Code analysis complete!

📄 File: {output path}
🔍 Components found: {count}
🛣️  Routes found: {count}
⚠️  Side effects identified: {count}

This analysis shows implementation details. Use /docs:generate for user-facing docs.
```

---

## TIPS

- This is for DEVELOPERS to understand implementation
- Use `/docs:generate` for END USER documentation
- Combine both for complete understanding
- Run on multiple resources to map entire application
