Skip to content

My5t3r10us/cesizen / .agents/skills/apex

Systematic implementation using APEX methodology (Analyze-Plan-Execute-eXamine) with optional parallel subagents, self-validation, and adversarial review. Use when implementing features, fixing bugs, or making code changes that benefit from structured workflow.

steps/step-01-analyze.md

View on GitHub
---
name: step-01-analyze
description: Pure context gathering - explore codebase to understand WHAT EXISTS
next_step: steps/step-02-plan.md
---

# Step 1: Analyze (Context Gathering)

## MANDATORY EXECUTION RULES (READ FIRST):

- šŸ›‘ NEVER plan or design solutions - that's step 2
- šŸ›‘ NEVER create todos or implementation tasks
- šŸ›‘ NEVER decide HOW to implement anything
- šŸ›‘ NEVER mark analyze as "complete" BEFORE writing findings to `{output_dir}/01-analyze.md` (if save_mode)
- āœ… ALWAYS focus on discovering WHAT EXISTS
- āœ… ALWAYS report findings with file paths and line numbers
- āœ… IF save_mode: ALWAYS use Edit tool to append ALL findings to `{output_dir}/01-analyze.md` BEFORE proceeding
- šŸ“‹ YOU ARE AN EXPLORER, not a planner
- šŸ’¬ FOCUS on "What is here?" NOT "What should we build?"
- 🚫 FORBIDDEN to suggest implementations or approaches
- 🚫 FORBIDDEN to skip file saving when save_mode is true

## 🧠 SMART AGENT STRATEGY

<critical>
**ADAPTIVE AGENT LAUNCHING** (unless economy_mode is true)

Before exploring, THINK about what information you need and launch the RIGHT agents - between 1 and 10 depending on task complexity.

**DO NOT blindly launch all agents. BE SMART.**
</critical>

## EXECUTION PROTOCOLS:

- šŸŽÆ Launch parallel exploration agents (unless economy_mode)
- šŸ’¾ IF save_mode: Use Edit tool to append findings to `{output_dir}/01-analyze.md` AFTER agents complete and BEFORE showing summary
- šŸ“– Document patterns with specific file:line references
- 🚫 FORBIDDEN to proceed until context is complete
- 🚫 FORBIDDEN to proceed to step-02 without saving findings first (if save_mode)

## CONTEXT BOUNDARIES:

- Variables from step-00-init are available
- No implementation decisions have been made yet
- Codebase state is unknown - must be discovered
- Don't assume knowledge about the codebase

## YOUR TASK:

Gather ALL relevant context about WHAT CURRENTLY EXISTS in the codebase related to the task.

---

<available_state>
From step-00-init:

| Variable | Description |
|----------|-------------|
| `{task_description}` | What to implement |
| `{task_id}` | Kebab-case identifier |
| `{auto_mode}` | Skip confirmations |
| `{examine_mode}` | Auto-proceed to review |
| `{save_mode}` | Save outputs to files |
| `{test_mode}` | Include test steps |
| `{economy_mode}` | No subagents, direct tools |
| `{output_dir}` | Path to output (if save_mode) |
</available_state>

---

## EXECUTION SEQUENCE:

### 1. Initialize Save Output (if save_mode)

**If `{save_mode}` = true:**

```bash
bash {skill_dir}/scripts/update-progress.sh "{task_id}" "01" "analyze" "in_progress"
```

Append findings to `{output_dir}/01-analyze.md` as you work.

### 2. Extract Search Keywords

From the task description, identify:
- **Domain terms**: auth, user, payment, etc.
- **Technical terms**: API, route, component, etc.
- **Action hints**: create, update, fix, add, etc.

These keywords guide exploration - NOT planning.

### 3. Explore Codebase

**If `{economy_mode}` = true:**
→ Use direct tools (see step-00b-economy.md for rules)

```
1. Glob to find files: **/*{keyword}*
2. Grep to search content in likely locations
3. Read the most relevant 3-5 files
4. Skip web research unless stuck
```

**If `{economy_mode}` = false:**
→ Use SMART agent strategy below

---

### 🧠 STEP 3A: ANALYZE TASK COMPLEXITY

**Before launching agents, THINK:**

```
Task: {task_description}

1. SCOPE: How many areas of the codebase are affected?
   - Single file/function → Low
   - Multiple related files → Medium
   - Cross-cutting concerns → High

2. LIBRARIES: Which external libraries are involved?
   - None or well-known basics → Skip docs
   - Unfamiliar library or specific API needed → Need docs
   - Multiple libraries interacting → Need multiple doc agents

3. PATTERNS: Do I need to understand existing patterns?
   - Simple addition → Maybe skip codebase exploration
   - Must integrate with existing code → Need codebase exploration

4. UNCERTAINTY: What am I unsure about?
   - Clear requirements, known approach → Fewer agents
   - Unclear approach, unfamiliar territory → More agents
```

---

### šŸŽÆ STEP 3B: CHOOSE YOUR AGENTS (1-10)

**Available Agent Types:**

| Agent | Use When |
|-------|----------|
| `explore-codebase` | Need to find existing patterns, related files, utilities |
| `explore-docs` | Unfamiliar library API, need current syntax, complex feature |
| `websearch` | Need common approaches, best practices, gotchas |

**Decision Matrix:**

| Task Type | Agents Needed | Example |
|-----------|---------------|---------|
| **Simple fix** | 1-2 | Bug fix in known file → 1x explore-codebase |
| **Add feature (familiar stack)** | 2-3 | Add button → 1x explore-codebase + 1x websearch |
| **Add feature (unfamiliar library)** | 3-5 | Add Stripe → 1x codebase + 1x explore-docs (Stripe) + 1x websearch |
| **Complex integration** | 5-8 | Auth + payments → 1x codebase + 2-3x explore-docs + 1-2x websearch |
| **Major feature (multiple systems)** | 6-10 | Full e-commerce → Multiple codebase areas + multiple docs + research |

---

### šŸš€ STEP 3C: LAUNCH AGENTS IN PARALLEL

**Launch ALL chosen agents in ONE message.**

**Agent Prompts:**

**`explore-codebase`** - Use for finding existing code:
```
Find existing code related to: {specific_area}

Report:
1. Files with paths and line numbers
2. Patterns used for similar features
3. Relevant utilities
4. Test patterns

DO NOT suggest implementations.
```

**`explore-docs`** - Use ONLY when you need specific library knowledge:
```
Research {library_name} documentation for: {specific_question}

Find:
1. Current API for {specific_feature}
2. Code examples
3. Configuration needed
```

**`websearch`** - Use for approaches and gotchas:
```
Search: {specific_question_or_approach}

Find common patterns and pitfalls.
```

---

### šŸ“‹ EXAMPLE AGENT LAUNCHES

**Simple task** (fix button styling) → 1 agent:
```
[Task: explore-codebase - find button components and styling patterns]
```

**Medium task** (add user profile page) → 3 agents:
```
[Task: explore-codebase - find user-related components and data fetching patterns]
[Task: explore-codebase - find page layout and routing patterns]
[Task: websearch - Next.js profile page best practices]
```

**Complex task** (add Stripe subscriptions) → 6 agents:
```
[Task: explore-codebase - find existing payment/billing code]
[Task: explore-codebase - find user account and settings patterns]
[Task: explore-docs - Stripe subscription API and webhooks]
[Task: explore-docs - Stripe Customer Portal integration]
[Task: websearch - Stripe subscriptions Next.js implementation]
[Task: websearch - Stripe webhook security best practices]
```

### 4. Synthesize Findings + Save to File

<critical>
**IF `{save_mode}` = true: You MUST write findings to the file BEFORE presenting the summary or proceeding.**
This is the most commonly skipped step. DO NOT skip it.
</critical>

Combine all agent results into structured context using this format:

```markdown
## Codebase Context

### Related Files Found
| File | Lines | Contains |
|------|-------|----------|
| `src/auth/login.ts` | 1-150 | Existing login implementation |
| `src/utils/validate.ts` | 20-45 | Email validation helper |

### Patterns Observed
- **Route pattern**: Uses Next.js App Router with `route.ts`
- **Validation**: Uses zod schemas in `schemas/` folder
- **Error handling**: Throws custom ApiError classes

### Utilities Available
- `src/lib/auth.ts` - JWT sign/verify functions
- `src/lib/db.ts` - Prisma client instance

### Similar Implementations
- `src/auth/login.ts:42` - Login flow (reference for patterns)

### Test Patterns
- Tests in `__tests__/` folders
- Uses vitest with testing-library

## Documentation Insights

### Libraries Used
- **jose**: JWT library - uses `SignJWT` class
- **prisma**: ORM - uses `prisma.user.create()` pattern

## Research Findings

### Common Approaches
- Registration: validate → hash → create → issue token
- Use httpOnly cookies for tokens
```

**IF `{save_mode}` = true (MANDATORY - DO THIS NOW):**

Use the **Edit tool** to append the full synthesis to `{output_dir}/01-analyze.md`. Replace the placeholder text `_Findings will be appended here as exploration progresses..._` with all the structured findings above.

### 5. Infer Acceptance Criteria

Based on task and context, infer success criteria:

```markdown
## Inferred Acceptance Criteria

Based on "{task_description}" and existing patterns:

- [ ] AC1: [specific measurable outcome]
- [ ] AC2: [specific measurable outcome]
- [ ] AC3: [specific measurable outcome]

_These will be refined in the planning step._
```

**If `{save_mode}` = true:** Append acceptance criteria to `{output_dir}/01-analyze.md` using Edit tool.

### 6. Complete Save Output (if save_mode)

<critical>
**This step MUST happen BEFORE presenting the summary to the user.**
The file must already contain all findings before you proceed.
</critical>

**If `{save_mode}` = true:**

1. Verify `{output_dir}/01-analyze.md` contains the full analysis (Read it to confirm)
2. Update progress:

```bash
bash {skill_dir}/scripts/update-progress.sh "{task_id}" "01" "analyze" "complete"
bash {skill_dir}/scripts/update-progress.sh "{task_id}" "02" "plan" "in_progress"
```

### 7. Present Context Summary

**Always (regardless of auto_mode):**

Present summary and proceed directly to planning:

```
**Context Gathering Complete**

**Files analyzed:** {count}
**Patterns identified:** {count}
**Utilities found:** {count}

**Key findings:**
- {summary of relevant files}
- {patterns that will guide implementation}

→ Proceeding to planning phase...
```

<critical>
Do NOT ask for user confirmation here - always proceed directly to step-02-plan.
</critical>

---

## SUCCESS METRICS:

āœ… Related files identified with paths and line numbers
āœ… Existing patterns documented with specific examples
āœ… Available utilities noted
āœ… Dependencies listed
āœ… Acceptance criteria inferred
āœ… NO planning or implementation decisions made
āœ… Output saved (if save_mode)
āœ… Task complexity analyzed BEFORE launching agents
āœ… Right NUMBER of agents launched (1-10 based on complexity)
āœ… Right TYPE of agents chosen for the task
āœ… All agents launched in PARALLEL (single message)

## FAILURE MODES:

āŒ **CRITICAL**: Skipping file save when save_mode is true (proceeding to plan without writing to 01-analyze.md)
āŒ Starting to plan or design (that's step 2!)
āŒ Suggesting implementations or approaches
āŒ Missing obvious related files
āŒ Not documenting patterns with file:line references
āŒ Launching agents sequentially instead of parallel
āŒ Using subagents when economy_mode is true
āŒ **CRITICAL**: Blocking workflow with unnecessary confirmation prompts
āŒ Launching too many agents for a simple task (wasteful)
āŒ Launching too few agents for a complex task (insufficient context)
āŒ Not analyzing task complexity before choosing agents
āŒ Skipping `explore-docs` when genuinely unfamiliar with a library API

## ANALYZE PROTOCOLS:

- This step is ONLY about discovery
- Report what EXISTS, not what SHOULD BE
- Include file paths and line numbers for all findings
- Don't assume - verify by reading files
- In economy mode, use direct tools only

---

## NEXT STEP:

Always proceed directly to `./step-02-plan.md` after presenting context summary.

<critical>
Remember: Analysis is ONLY about "What exists?" - save all planning for step-02!
Do NOT ask for confirmation - proceed directly!
IF save_mode = true: The 01-analyze.md file MUST contain all findings BEFORE you load step-02-plan.md.
</critical>
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall