analyze-spec

What this skill does

# Spec Analysis Skill

You are initiating the spec analysis workflow. This process will analyze an existing spec for quality issues, optionally guide the user through resolving them interactively, and optionally create fix tasks from approved findings.

## Load Reference Skills

For task creation from findings (Step 8), load the Tasks reference:

```
Read ${CLAUDE_PLUGIN_ROOT}/../claude-tools/skills/claude-code-tasks/SKILL.md
```

## Workflow

### Step 1: Validate File

Verify the spec file exists at the provided path. If not found:
- Check if user provided relative path and try common locations
- Use Glob to search for similar filenames
- Ask user for correct path if needed

### Step 2: Read Spec Content

Read the entire spec file using the Read tool.

### Step 3: Detect Depth Level

Analyze the spec content to detect its depth level:

**Full-Tech Indicators** (check first):
- Contains `API Specifications` section OR `### 7.4 API` or similar
- Contains API endpoint definitions (`POST /api/`, `GET /api/`, etc.)
- Contains `Testing Strategy` section
- Contains data model schemas

**Detailed Indicators**:
- Uses numbered sections (`## 1.`, `### 2.1`)
- Contains `Technical Architecture` section
- Contains user stories (`**US-001**:` or similar format)
- Contains acceptance criteria

**High-Level Indicators**:
- Contains feature table with Priority column
- Executive summary focus
- No user stories or acceptance criteria
- Shorter document (~50-100 lines)

**Detection Priority**:
1. If Full-Tech indicators found → Full-Tech
2. Else if Detailed indicators found → Detailed
3. Else if High-Level indicators found → High-Level
4. Default → Detailed

### Step 4: Check Settings

Check for settings at `.claude/agent-alchemy.local.md` to get:
- Author name (if configured)
- Any custom preferences

### Step 5: Determine Report Paths

The analysis outputs should be saved in the same directory as the spec:

- Spec: `specs/SPEC-User-Auth.md`
- Report: `specs/SPEC-User-Auth.analysis.md`
- HTML Review: `specs/SPEC-User-Auth.analysis.html`

Extract the spec filename and construct both output paths.

### Step 6: Launch Analyzer Agent

Launch the Spec Analyzer Agent using the Task tool with subagent_type `agent-alchemy-sdd-tools:spec-analyzer`.

Provide this context in the prompt:

```
Analyze the spec at: {spec_path}

Spec Content:
{full_spec_content}

Detected Depth Level: {depth_level}
Report Output Path: {report_path}
HTML Review Path: {html_review_path}
HTML Template Path: skills/analyze-spec/templates/review-template.html
Author: {author_from_settings or "Not specified"}

Instructions:
1. Load the analysis skill, reference files, and HTML review guide
2. Perform systematic analysis based on the depth level
3. Generate the analysis report (.analysis.md)
4. Generate the interactive HTML review (.analysis.html)
5. Present findings summary
6. Ask user to choose review mode (HTML review, CLI update, or reports only)
7. Handle chosen mode accordingly
8. Update report with final resolution status
```

### Step 7: Handoff Complete

Once you have launched the Analyzer Agent, your role is mostly complete. The agent will handle:
- Loading analysis criteria for the depth level
- Performing comprehensive analysis
- Generating and saving the report (.analysis.md)
- Generating the interactive HTML review (.analysis.html)
- Offering three review modes: HTML review, CLI update, or reports only
- Updating the spec with approved changes

After the analyzer agent completes its work and returns, proceed to Step 8.

### Step 8: Create Fix Tasks (Optional)

After the analyzer agent has finished the review session and returned, check if there are approved findings that could be turned into tasks. This connects analysis output to the SDD task pipeline.

Use `AskUserQuestion` to offer task creation:

```yaml
questions:
  - header: "Fix Tasks"
    question: "Would you like to create tasks from the analysis findings? This connects them to the SDD pipeline for tracking and execution."
    options:
      - label: "Create fix tasks (Recommended)"
        description: "Create tasks from critical and warning findings for tracking via /run-tasks"
      - label: "Skip"
        description: "Analysis is complete, no tasks needed"
    multiSelect: false
```

If the user selects "Create fix tasks":

1. Read the analysis report at `{report_path}` to get the final findings with resolution status
2. Filter to findings that were **not resolved and not skipped** (still pending) with severity `critical` or `warning`
3. Derive `spec-name` slug from the spec filename (strip `SPEC-` prefix, strip `.md`, lowercase, hyphens)
4. For each qualifying finding, create a task via `TaskCreate`:
   - **subject**: `Fix: {finding title}` (imperative)
   - **description**: Include finding category, severity, location (section + line), issue description, and the proposed fix as acceptance criteria
   - **activeForm**: `Fixing {finding title}`
   - **metadata**:
     - `task_group`: `spec-fixes-{spec-name}`
     - `priority`: Map from severity — `critical` → `critical`, `warning` → `high`
     - `source_section`: Finding location reference
     - `spec_path`: Path to the spec file

5. After creating all tasks, display summary:
```
Created {N} fix tasks from {M} unresolved findings.
Task group: spec-fixes-{spec-name}

Run `/run-tasks --task-group spec-fixes-{spec-name}` to execute.
```

If the user selects "Skip", display:
```
Analysis complete. Reports saved to:
- {report_path}
- {html_review_path}
```

## Example Usage

```
/agent-alchemy-sdd:analyze-spec specs/SPEC-User-Authentication.md
```

This will:
1. Read the spec at the specified path
2. Detect it's a Detailed-level spec
3. Analyze for issues across all four categories
4. Save report to `specs/SPEC-User-Authentication.analysis.md`
5. Offer interactive resolution mode

## Notes

- Always read the full spec before launching the analyzer
- Depth detection determines which criteria apply
- Report is always saved alongside the spec
- The analyzer agent handles all user interaction for resolution

---

## Analysis Philosophy

### Depth-Aware Analysis

Spec analysis must respect the intended depth level of the document. A high-level spec should not be flagged for missing API specifications, just as a full-tech spec should be scrutinized for technical completeness.

**Key Principle**: Only flag what's expected at the document's depth level.

### Constructive Approach

Findings should be:
- **Actionable**: Clear recommendation for how to fix
- **Specific**: Exact location and description of issue
- **Prioritized**: Severity indicates importance
- **Helpful**: Explain why this matters, not just what's wrong

### Systematic Coverage

Analysis covers four distinct categories to ensure comprehensive review:
1. **Inconsistencies**: Internal contradictions or mismatches
2. **Missing Information**: Expected content that's absent
3. **Ambiguities**: Unclear or vague statements
4. **Structure Issues**: Formatting, organization, missing sections

---

## Finding Categories

### 1. Inconsistencies

Issues where the spec contradicts itself or uses conflicting information.

**What to Look For**:
- Feature named differently in different sections
- Priority mismatches (feature marked P2 but in Phase 1)
- Metrics that don't align with stated goals
- Contradictory requirements
- Timeline/phase misalignment

**Detection Strategy**:
1. Build glossary of feature names from first mention
2. Track priority assignments
3. Map goals to metrics
4. Compare requirements for conflicts

### 2. Missing Information

Expected content that is absent based on the spec's depth level.

**What to Look For**:
- Required sections for depth level
- Undefined technical terms
- Features without acceptance criteria (detailed/full-tech)
- Error scenarios not addressed
- Dependencies not listed
- Incomplete personas

**Detection Strategy**:
1. Compare against depth-level checklist
2. Identify domain terms without defi