analyze

name	analyze
description	Deep technical analysis — explore existing code, risks, alternatives. Triggers: "analyze" | "technical analysis" | "explore the problem" | "how deep is it" | "deep dive" | "investigate this" | "analyze this feature" | "what are the risks" | "explore the codebase" | "look into this".

Analyze

Success

I := α written ∧ committed ∧ shapes ∃ V := git log --oneline -1 | grep analysis ∧ ls artifacts/analyses/{N}-*.md*

Let: α := artifacts/analyses/{N}-{slug}-analysis.md φ := artifacts/frames/{slug}-frame.md ρ := expert reviewer set Ω := skill: "interview" Q := present choice, wait for user reply

Frame → analysis. Codebase exploration → expert review → user approval gate. ¬spec, ¬worktree. Shape phase only. Spec → /spec.

Entry

/analyze --issue N    → read frame for #N, produce α
/analyze --frame path → read frame at path, produce α

Pipeline

Step	ID	Required	Verifies via	Notes
0	resolve	✓	φ ∃	—
1	scan	—	α ∃?	—
2	explore	✓	α written	Glob+Grep+interview
2.5	investigate	—	hypothesis resolved	optional spike
3	review	—	agents return	∥ spawn
4	approval	✓	git log shows commit	gate

Pre-flight

Success: α written ∧ committed ∧ shapes ∃ Evidence: git log --oneline -1 | grep analysis Steps: resolve → scan → explore → review → approval ¬clear → STOP + ask: "Is this technical analysis or framing?"

Step 0 — Resolve Input

Parse args → locate φ.

--issue N:

# Find frame by issue number in frontmatter or filename
grep -rl "issue: N" artifacts/frames/ 2>/dev/null | head -1
# Fallback: glob by any slug
ls artifacts/frames/*.md* 2>/dev/null

--frame path → read directly. ¬φ found → ask user "No frame doc found. Run /frame --issue N first, or provide path directly?"

Read φ → extract: title, issue, tier, problem statement, constraints.

Step 1 — Scan Existing Analysis

Glob artifacts/analyses/* — match issue# or slug from φ.

∃ α:

• type: brainstorm ∈ frontmatter → treat as brainstorm (¬analysis), offer to promote.
• → present choice Reuse existing (→ Step 3) | Start fresh

Step 2 — Codebase Exploration + Interview

2a. Glob + Grep

Search codebase based on φ problem + constraints:

# Find files relevant to the domain (adapt to actual problem):
Glob("{backend.path}/src/**/*.ts")    # backend domain
Glob("{frontend.path}/src/**/*.tsx")  # frontend domain
Grep("keyword", type: "ts")           # symbol/pattern search

Read key files (max 5–8 most relevant). Note: paths, patterns, dependencies, risks.

2b. Interview

Ω, args: "topic text from frame" (Analysis type).

Captures: source (verbatim trigger) | problem (broken/missing) | outcome (success ¬prescribing solution) | appetite (time budget) | shapes (2–3 mutually exclusive arch approaches: name + trade-offs + scope) | constraint alignment (which constraints eliminate which shapes).

Pre-fill context from φ — skip answered questions.

Step 2c — Generate Analysis

F-lite/F-full: generate forge-chart sidecars per forge-chart-sidecar.md before writing α.

Write α:

---
title: "{title}"
description: "{one-line description}"
---

## Source

{verbatim trigger — exact quote, ticket, Slack message}

## Problem

{what is broken or missing today, in plain language}

## Outcome

{what success looks like — without prescribing a solution}

## Appetite

{time budget — e.g. "1-week cycle", "2 sprints"}

## Shapes

**Diagram:** [{shapes title}](../visuals/{N}-{slug}-shapes.html)

### Shape 1: {name}

{description}

**Trade-offs:**
- Pro: ...
- Con: ...

**Rough scope:** {XS | S | M | L | XL}

### Shape 2: {name}

...

## Fit Check

**Diagram:** [{data flow title}](../visuals/{N}-{slug}-data-flow.html)

{Which shape best fits constraints + appetite, and why. Which shapes are eliminated.}

Forge-Chart Sidecars (F-lite/F-full)

Read forge-chart-sidecar.md before generating visuals.

When analysis involves data flow or architectural choices, generate forge-chart sidecars (¬inline mermaid, ¬ASCII):

• ## Shapes (≥2 shapes) → {N}-{slug}-shapes.html — architecture diagram with zones per shape
• ## Fit Check (data flow or arch choice) → {N}-{slug}-data-flow.html — recommended shape topology

Link in α:

**Diagram:** [{title}](../visuals/{N}-{slug}-{kind}.html)

Files impacted table: always include when ≥3 files touched.

Tier S may omit Shapes + Fit Check sidecars.

∃ specific technical question → spawn domain expert via Task. See references/expert-consultation.md.

Step 2.5 — Investigation (Optional)

Skip if ¬technical uncertainty in Step 2 findings.

Signals: unfamiliar 3rd-party behavior | undocumented internal APIs | performance unknowns | conflicting docs.

∃ signals → present choice Spike now (throwaway worktree, test hypothesis) | Skip (→ expert review).

Spike flow:

1. EnterWorktree(name: "spike-{N}") — creates isolated throwaway worktree on branch spike-{N}
2. Investigate: minimal code, isolated test, confirm/reject hypothesis
3. Report findings → incorporate into α
4. ExitWorktree(action: "remove", discard_changes: true) — clean up throwaway worktree

See references/investigation.md if ∃, else use inline flow above.

Step 3 — Expert Review

Auto-select ρ (¬ask user):

ρ	When	Focus
doc-writer	Always	Structure, clarity
product-lead	Always	Product fit, Outcome quality, Problem↔Outcome alignment
architect	∃ arch / trade-offs / multi-domain	Technical soundness, shape feasibility
devops	∃ CI/CD / deploy / infra	Operational impact

∀ r ∈ ρ → spawn ∥ Task(subagent_type: "<r>", prompt: "Review α for <focus>. Return: good / needs improvement / concerns.").

Incorporate feedback → revise α → note unresolved concerns.

Step 4 — User Approval

Open α: code artifacts/analyses/{N}-{slug}-analysis.md.

Present summary: shapes found, trade-offs, recommended shape, unresolved concerns.

→ present choice Approve → update issue status → done | Revise → collect feedback → revise α → loop from Step 3.

On approval → commit: git add artifacts/analyses/{N}-{slug}-analysis.md artifacts/visuals/ + commit per CLAUDE.md Rule 5.

bun ${CLAUDE_PLUGIN_ROOT}/skills/issue-triage/triage.ts set <N> --status Analysis

Inform: "Analysis complete. Run /spec --issue <N> to generate the solution spec."

Edge Cases

Scenario	Behavior
No frame found	→ ask user run /frame first or provide path
∃ brainstorm (¬analysis)	Treat as no analysis — offer to promote via interview
∃ analysis, user picks reuse	Present existing → jump to Step 3
Expert subagent fails	Report error, continue without that reviewer
Tier S	Skip Shapes + Fit Check
Frame lacks appetite	Ask user during interview Phase 1

Chain Position

• Phase: Shape
• Predecessor: /frame (artifact: artifacts/frames/{N}-{slug}-frame.md)
• Successor: /spec
• Class: adv (continuous flow, no gate — user approves α inline in Step 4, not a pipeline gate)

Task Integration

• /dev owns the dev-pipeline task lifecycle externally
• This skill does NOT update its own dev-pipeline task
• Sub-tasks created: none

Exit

• Success via /dev: return control silently. ¬write summary. ¬ask user. ¬announce /spec. /dev re-scans and advances.
• Success standalone: print one line: Done. Next: /spec --issue N. Stop.
• Failure: return error. /dev presents Retry | Skip | Abort.

$ARGUMENTS