---
name: step-02-analyze
description: Validate component structure, frontmatter, and cross-references
next_step: steps/step-03-report.md
---

# Step 2: Analyze Components

## MANDATORY EXECUTION RULES:
- Validate EVERY component found in Step 1
- Load reference checklists from `references/` directory
- Record all issues with severity (ERROR, WARN, INFO)
- Check cross-references between component types

## YOUR TASK:
Validate each component against official Claude Code conventions and check cross-references.

---

## EXECUTION SEQUENCE:

### 1. Load Checklists

```
Read reference checklists:
  Read: "references/skill-checklist.md"
  Read: "references/agent-checklist.md"
  Read: "references/hook-checklist.md"
```

### 2. Validate Skills

For each skill in {skills_found}, check:

**Frontmatter (required):**
- `name` exists and is lowercase, max 64 chars → ERROR if missing
- `description` exists and is non-empty → ERROR if missing

**Frontmatter (recommended):**
- `argument-hint` present if skill accepts arguments → WARN if missing
- `disable-model-invocation` explicitly set for side-effect skills → WARN

**SKILL.md quality:**
- Line count < 500 → WARN if exceeded
- Contains `<objective>` section → WARN if missing
- Contains `<entry_point>` section (if has steps/) → ERROR if missing
- Contains `<workflow>` or `<step_files>` section → INFO if missing

**Step files validation (if steps/ exists):**
- Each step file has frontmatter with `name` and `description` → ERROR if missing
- Each step file (except last) has `next_step` in frontmatter → ERROR if missing
- `next_step` paths resolve to existing files → ERROR if broken
- Steps follow sequential naming (step-00, step-01, ...) → WARN if not
- Each step has "NEXT STEP" or "SUCCESS METRICS" section → INFO if missing

**File references:**
- All files referenced in SKILL.md exist → ERROR if missing
- Templates, references, scripts directories referenced exist → WARN if missing

**Record issues in {issues}:**
```
{component_name, component_type: "skill", severity, message, file_path, line_number}
```

### 3. Validate Agents

For each agent in {agents_found}, check:

**Frontmatter (required):**
- `name` exists → ERROR if missing
- `description` exists and is non-empty → ERROR if missing

**Frontmatter (recommended):**
- `model` is valid (haiku, sonnet, opus, inherit) or absent → ERROR if invalid
- `tools` references valid tool names → WARN if unrecognized tool
- `permissionMode` is valid (default, acceptEdits, dontAsk, bypassPermissions, plan) → ERROR if invalid
- `skills` references existing skill names → WARN if not found

**Content quality:**
- Has workflow or instructions section → INFO if very short (< 10 lines)
- System prompt is clear and actionable → INFO

**Record issues in {issues}:**
```
{component_name, component_type: "agent", severity, message, file_path}
```

### 4. Validate Hooks

For each hook in {hooks_found}, check:

**Structure:**
- Event name is valid (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification, SubagentStart, SubagentStop, Stop, PreCompact, SessionEnd) → ERROR if invalid
- Hook type is valid (command, prompt, agent) → ERROR if invalid

**Command hooks:**
- Referenced script/command exists → ERROR if missing
- Script is executable (on Unix) → WARN if not

**Prompt hooks:**
- `prompt` field is non-empty → ERROR if missing
- `model` is valid if specified → WARN if invalid

**Matcher patterns:**
- Regex is valid → ERROR if invalid syntax
- Pattern matches at least one known tool/event → INFO if no match

### 5. Validate Cross-References

```
Check skills → agents:
  For skills with `context: fork` and `agent: {name}`:
    Verify agent exists in {agents_found} or is built-in (Explore, Plan, general-purpose, Bash)
    → WARN if agent not found

Check agents → skills:
  For agents with `skills: [...]`:
    Verify each skill exists in {skills_found}
    → WARN if skill not found

Check hooks → scripts:
  For command hooks:
    Verify referenced script exists on filesystem
    → ERROR if missing

Check settings → permissions:
  For permission rules referencing tools:
    Verify tool names are valid
    → WARN if unrecognized
```

### 6. Display Analysis Summary

```
Analysis Complete:

| Severity | Count |
|----------|-------|
| ERROR | {count} |
| WARN | {count} |
| INFO | {count} |

Top issues:
{list top 5 most critical issues}

→ Generating report...
```

---

## SUCCESS METRICS:
- All components validated against checklists
- Cross-references checked
- All issues recorded with severity
- Summary counts displayed

## NEXT STEP:
After showing analysis summary, proceed directly to `./step-03-report.md`
