---
name: step-01-analyze
description: Explore existing code to understand what exists — do NOT plan yet
model: opus
prev_step: steps/step-00-init.md
next_step: steps/step-02-plan.md
---

# Step 1: Analyze

**Goal:** Understand what EXISTS in the codebase. Pure exploration, NO planning.

## LOAD CONDITIONALLY

- If NOT `{economy_mode}`: read `references/agent-teams-protocol.md`

---

## 1. Context Sources

Read available context (in order of priority):

**A. PRD (if exists):**
```
Read {prd_path} → extract:
- filesToCreate (7 categories)
- brToCodeMapping
- permissionMatrix
- acceptance criteria
```

**B. Feature.json (if exists):**
```
Read {feature_path} → extract:
- Module structure (sections, resources)
- Business rules
- Entity definitions
- Permission structure
```

**C. Task description only:**
If neither PRD nor feature.json exists, rely on task description and code exploration.

---

## 2. Code Exploration

### If economy_mode: Direct Tools

Use Glob, Grep, Read, and MCP tools directly:

```
Backend:
- Glob("**/Domain/Entities/**/{module_code}/**/*.cs")
- Glob("**/Infrastructure/Persistence/Configurations/**/{module_code}/**/*.cs")
- Glob("**/Application/Services/**/{module_code}/**/*.cs")
- Glob("**/Api/Controllers/**/*{module_code}*Controller.cs")
- Glob("**/Infrastructure/Persistence/Seeding/Data/{module_code}/**/*.cs")

Frontend:
- Glob("src/pages/**/{module_code}/**/*.tsx")
- Glob("src/components/**/{module_code}/**/*.tsx")

MCP:
- mcp__smartstack__api_docs → existing API surface
- mcp__smartstack__analyze_extension_points → React extension points
```

### If NOT economy_mode: Agent Teams

> **Protocol:** See `references/agent-teams-protocol.md`

```
TeamCreate("apex-analyze", description: "Scan SmartStack project for existing code")

Spawn 3 teammates (Sonnet, read-only tools: Glob, Grep, Read):

1. scan-backend:
   "Scan backend code for module {module_code} in app {app_name}.
    Find: entities, EF configs, services, DTOs, validators, controllers.
    Report: file paths, class names, key patterns found.
    Folders: Domain/, Infrastructure/, Application/, Api/"

2. scan-frontend:
   "Scan frontend code for module {module_code} in app {app_name}.
    Find: pages, components, hooks, i18n files, route definitions.
    Report: file paths, component names, route patterns.
    Folders: src/pages/, src/components/, src/locales/"

3. scan-context:
   "Read context artifacts for module {module_code} in app {app_name}.
    Read: .ralph/prd-{module_code}.json, docs/business/**/feature.json.
    Report: sections, entities, business rules, permissions, acceptance criteria."

Wait for all 3 teammates to report via SendMessage (DM to lead).
Aggregate results.

Shutdown teammates → TeamDelete("apex-analyze")
```

---

## 3. Seed Data Inventory

Check existing seed data:

```
Glob("**/Seeding/Data/{module_code}/*SeedData.cs")
Glob("**/Seeding/*SeedDataProvider.cs")
```

Identify:
- NavigationModuleSeedData: exists? complete?
- PermissionsSeedData: exists? complete?
- RolesSeedData: exists? complete?
- SeedConstants: exists?
- IClientSeedDataProvider: exists? registered in DI?

---

## 4. Gap Analysis

Compare what EXISTS vs what the TASK REQUIRES:

```
For each element in the task description:
  - EXISTS and COMPLETE → mark as "skip"
  - EXISTS but INCOMPLETE → mark as "modify"
  - DOES NOT EXIST → mark as "create"
```

---

## 5. Analysis Summary

```
**APEX SmartStack - Analysis Complete**

**Existing Code:**
- Entities: {list with paths}
- EF Configs: {list with paths}
- Services: {list with paths}
- Controllers: {list with paths}
- Frontend pages: {list with paths}
- Seed data: {status per type}
- Tests: {list with paths}

**Required Changes:**
- Create: {list of new files/elements}
- Modify: {list of files to change}
- Skip: {list of existing complete elements}

**Acceptance Criteria:** (inferred from PRD/feature/task)
- AC1: {criterion}
- AC2: {criterion}
...
```

---

## 6. Save Output (if save_mode)

Write to `{output_dir}/01-analyze.md` with analysis results.

---

## NEXT STEP

Load `steps/step-02-plan.md`
