@su-record/vibe 2.9.21 → 2.9.23

package/commands/vibe.analyze.md

@@ -1,533 +1,533 @@
----
-description: Analyze any target — code, document, website, or Figma design
-argument-hint: "feature-name" or file.pdf or https://... or --code or --deps or --arch
----
-
-# /vibe.analyze
-
-Analyze any target: source code, documents, websites, or Figma designs.
-
-## Usage
-
-```
-/vibe.analyze                  # Full project quality analysis
-/vibe.analyze "login"          # Feature/module code exploration + context collection
-/vibe.analyze --code           # Code quality analysis only
-/vibe.analyze --deps           # Dependency analysis only
-/vibe.analyze --arch           # Architecture analysis only
-/vibe.analyze report.pdf       # Document analysis (PDF, markdown, slides)
-/vibe.analyze https://example.com  # Website analysis (UX, tech, SEO, accessibility)
-/vibe.analyze https://figma.com/design/...  # Figma design analysis
-```
-
-## Input Type Auto-Detection
-
-Determine analysis mode from the argument pattern:
-
-| Pattern | Mode | Description |
-|---------|------|-------------|
-| `*.pdf`, `*.docx`, `*.pptx`, `*.md` (file path) | **Document** | Structure, content, quality, applicability |
-| `http(s)://figma.com/*` | **Figma** | Design structure, components, tokens |
-| `http(s)://*` | **Website** | UX, tech stack, SEO, accessibility |
-| `--code`, `--deps`, `--arch` | **Project Quality** | Code quality, dependencies, architecture |
-| String (feature name) | **Feature/Module** | Source code exploration + flow analysis |
-| No argument | **Project Quality** | Full project analysis |
-
-**Detection order**: file extension → URL pattern → flag → string.
-
-## File Reading Policy (Mandatory)
-
-- **SPEC/Feature files**: Always use `Read` tool for the full file (never Grep for content)
-- **Source files**: Read the entire file before analyzing (no partial reads)
-- **Grep restriction**: Use only for locating files, not for understanding content
-- **Agent prompts**: Always include "Read target files in full before analyzing"
-- **No partial analysis**: Never judge a file by a few lines around a Grep match
-
-## Context Reset
-
-**When this command runs, previous conversation is ignored.**
-- Explore and analyze from scratch like a new session
-- Base analysis only on newly collected information
-
----
-
-> **Timer**: Record start time at the beginning. Include elapsed time in the final report.
-
-## Mode 1: Feature/Module Analysis (`/vibe.analyze "feature-name"`)
-
-### Goal
-
-Explore all source code related to the requested feature/module and analyze flow to:
-1. Understand current implementation status
-2. Map code structure and dependencies
-3. Build context for future development/modification requests
-
-### Process
-
-#### 1. Request Analysis
-
-Extract keywords from the user request:
-- Feature name (e.g., login, feed, payment)
-- Action (e.g., create, read, update, delete)
-- Scope (e.g., backend only, frontend only, full)
-
-#### 2. Understand Project Structure
-
-Read `CLAUDE.md`, `package.json`, `pyproject.toml`, etc. to identify tech stack:
-
-**Backend:**
-- FastAPI/Django: `app/api/`, `app/services/`, `app/models/`
-- Express/NestJS: `src/controllers/`, `src/services/`, `src/models/`
-
-**Frontend:**
-- React/Next.js: `src/components/`, `src/pages/`, `src/hooks/`
-- Flutter: `lib/screens/`, `lib/services/`, `lib/providers/`
-
-#### 3. Explore Related Code (Parallel Sub-Agents)
-
-**MANDATORY: Always use explorer sub-agents. Never explore in main session.**
-
-> Why: 3 explorer-low agents return ~600 tokens of summaries to main session.
-> Direct Glob/Grep/Read in main session would add 5-15K tokens of raw content.
-
-**Parallel exploration (ALL in ONE message):**
-
-```text
-Agent(subagent_type="explorer-low", model="haiku",
-  prompt="Find all [FEATURE] related API endpoints. List file paths, HTTP methods, routes, and auth requirements.")
-
-Agent(subagent_type="explorer-low", model="haiku",
-  prompt="Find all [FEATURE] related services, business logic, and utility functions. Map dependencies.")
-
-Agent(subagent_type="explorer-low", model="haiku",
-  prompt="Find all [FEATURE] related data models, schemas, and database queries. Document relationships and key fields.")
-```
-
-**Scale for large projects (6+ related files):**
-
-```text
-Agent(subagent_type="explorer-low", model="haiku",
-  prompt="Find all test files related to [FEATURE]. Identify tested vs untested paths.")
-
-Agent(subagent_type="explorer-low", model="haiku",
-  prompt="Analyze [FEATURE] configuration, environment variables, and external integrations.")
-```
-
-**After all agents return:**
-- Synthesize results → proceed to Flow Analysis
-- Only Read specific files in main session when agent summaries need clarification
-
-#### 4. Flow Analysis
-
-**API Flow:**
-- Endpoint URL and HTTP method
-- Request/response schema
-- Authentication/authorization requirements
-
-**Business Logic:**
-- Core methods and their roles
-- Validation rules
-- External service integrations
-
-**Data Flow:**
-- Related tables/models
-- Relationships (1:N, N:M)
-- Key query patterns
-
-#### 5. Output
-
-```markdown
-## [feature-name] Analysis Results
-
-### Overview
-- **Feature**: [one-line summary]
-- **Status**: [Complete / In progress / Not implemented]
-- **Files**: N related files
-
-### Structure
-
-#### API Endpoints
-| Method | Path | Description | Auth |
-|--------|------|-------------|------|
-| POST | /api/v1/auth/login | User login | None |
-
-#### Core Services
-- `auth_service.py`: Authentication logic
-  - `login()`: Processes login
-  - `verify_token()`: Validates JWT
-
-#### Data Models
-- `User`: User table
-  - Key fields: id, email, password_hash
-  - Relationships: Session (1:N)
-
-### Reference Files
-- src/api/auth/router.py:L10-50
-- src/services/auth_service.py:L1-100
-```
-
-#### 6. Next Steps
-
-After analysis, suggest mode-specific follow-up actions:
-
-**After code/feature analysis:**
-
-| Task Scope | Approach |
-|------------|----------|
-| Simple fix (1-2 files) | Plan Mode |
-| Complex feature (3+ files) | `/vibe.spec` |
-
-**After document analysis:**
-
-| Goal | Approach |
-|------|----------|
-| Apply findings to project | `/vibe.spec "feature-name"` |
-| Derive improvement direction | Plan Mode |
-| Compare with another source | `/vibe.analyze [other target]` |
-
-**After website analysis:**
-
-| Goal | Approach |
-|------|----------|
-| Build similar product | `/vibe.spec` |
-| Improve existing UI | `/vibe.figma` |
-| Compare with another site | `/vibe.analyze [other URL]` |
-
-Wait for user's choice before proceeding.
-
----
-
-## Mode 2: Document Analysis (PDF, Markdown, Slides)
-
-### Goal
-
-Analyze document **structure, key content, quality, and applicability** to:
-1. Extract and organize information from the document
-2. Map relevance to the current project
-3. Suggest follow-up actions (development, improvement, application)
-
-### Process
-
-#### 1. Read Document
-
-- **PDF**: Use `Read` tool with `pages` parameter (split large documents into chunks of 20 pages)
-- **Markdown/Text**: Use `Read` tool for the full file
-- **Image-heavy documents**: Analyze visual elements (slides, diagrams) alongside text
-
-#### 2. Classify Document Type
-
-| Type | Analysis Focus |
-|------|---------------|
-| Technical spec | API definitions, data models, sequence diagrams |
-| Presentation/slides | Key claims, frameworks, case studies |
-| PRD/requirements | User stories, acceptance criteria, scope |
-| Business document | Strategy, decision points, action items |
-| Research/academic | Methodology, conclusions, applicability |
-
-#### 3. Analyze Content (Parallel Sub-Agents)
-
-```text
-Agent(subagent_type="general-purpose", model="haiku",
-  prompt="Read the document at [PATH] and extract: 1) Section structure / table of contents 2) Key concepts and definitions 3) Main arguments or claims. Use the Read tool with pages parameter for PDFs.")
-
-Agent(subagent_type="general-purpose", model="haiku",
-  prompt="Read the document at [PATH] and extract: 1) Actionable recommendations 2) Data points, metrics, examples 3) References to external resources. Use the Read tool with pages parameter for PDFs.")
-```
-
-#### 4. Project Relevance Analysis
-
-- Map how document content applies to the current project
-- Check if patterns/tools/techniques mentioned are already implemented
-- Gap analysis: document recommendations vs current project state
-
-#### 5. Output
-
-```markdown
-## [Document Name] Analysis
-
-### Overview
-- **Type**: [Presentation / Technical spec / PRD / ...]
-- **Topic**: [one-line summary]
-- **Pages/Sections**: N
-- **Audience**: [Developers / PMs / Executives / ...]
-
-### Key Content
-1. **[Concept 1]**: Description
-2. **[Concept 2]**: Description
-
-### Frameworks/Models (if any)
-- [Systematic structure presented in the document]
-
-### Project Relevance
-| Recommendation | Current State | Gap |
-|----------------|---------------|-----|
-| ... | ... | ... |
-
-### Key Insights
-- [Most important takeaway]
-
-### Suggested Actions
-1. ...
-```
-
-#### Fallback
-
-If `Read` fails for a document format:
-1. Check file extension and try alternative parsing
-2. If binary format is unsupported, inform user and suggest converting to PDF/markdown
-3. Never produce an analysis based on partial or failed reads
-
----
-
-## Mode 3: Website Analysis (URL)
-
-### Goal
-
-Analyze website **tech stack, UX/UI, SEO, accessibility, and performance** to:
-1. Understand technical implementation
-2. Identify improvement opportunities
-3. Collect benchmarking insights
-
-### Process
-
-#### 1. Fetch Website
-
-- Use `WebFetch` tool to retrieve HTML
-- Fetch key pages (home, main feature pages, login, etc.)
-
-#### 2. Analyze (Parallel Sub-Agents)
-
-```text
-Agent(subagent_type="general-purpose", model="haiku",
-  prompt="Analyze the HTML from [URL] (use WebFetch). Extract: 1) Tech stack (framework, meta tags, scripts) 2) Page structure (header, nav, main sections, footer) 3) SEO elements (title, meta description, OG tags, structured data)")
-
-Agent(subagent_type="general-purpose", model="haiku",
-  prompt="Analyze the HTML from [URL] (use WebFetch). Extract: 1) Accessibility (ARIA labels, semantic HTML, alt texts, heading hierarchy) 2) Performance hints (script loading, image optimization) 3) Mobile responsiveness (viewport meta, media queries)")
-
-Agent(subagent_type="general-purpose", model="haiku",
-  prompt="Analyze the HTML from [URL] (use WebFetch). Extract: 1) UX patterns (navigation, CTA placement, form design) 2) Design system hints (CSS variables, component patterns) 3) Content strategy (copywriting tone, information hierarchy)")
-```
-
-#### 3. Figma URL Handling
-
-If a Figma URL is detected, switch to **Figma-specific analysis**:
-- Use `get_design_context` or `get_screenshot` to collect design data
-- Analyze component structure, design tokens, layout patterns
-- Compare design intent with current project code
-
-#### 4. Output
-
-```markdown
-## [URL] Analysis
-
-### Overview
-- **Site type**: [SaaS / E-commerce / Portfolio / ...]
-- **Tech stack**: [Next.js, Tailwind, ...]
-- **Overall score**: N/100
-
-### Technical Analysis
-| Area | Detection | Details |
-|------|-----------|---------|
-| Framework | React/Next.js | SSR enabled |
-| CSS | Tailwind CSS | v3.4 |
-
-### UX/UI Analysis
-- **Navigation**: [assessment]
-- **CTA placement**: [assessment]
-- **Responsive design**: [assessment]
-
-### SEO Analysis (N/100)
-| Element | Status | Recommendation |
-|---------|--------|----------------|
-| Title | Present | Appropriate length |
-| Meta Description | Missing | Add description |
-
-### Accessibility (WCAG 2.1 AA)
-- **Semantic HTML**: [assessment]
-- **Keyboard navigation**: [assessment]
-- **Screen reader support**: [assessment]
-
-### Improvement Suggestions
-1. [highest priority]
-2. ...
-```
-
-#### Fallback
-
-If `WebFetch` fails:
-1. Retry once with a simplified URL (strip query params)
-2. If still failing, inform user of the error (timeout, DNS, etc.)
-3. Suggest user provide HTML file directly: `/vibe.analyze page.html`
-
----
-
-## Mode 4: Project Quality Analysis (--code/--deps/--arch)
-
-### Scope
-
-- **Default** (`/vibe.analyze`): Full analysis (code + dependencies + architecture)
-- `--code`: Code quality only
-- `--deps`: Dependency analysis only
-- `--arch`: Architecture analysis only
-
-### Code Quality (--code)
-
-- Cyclomatic complexity analysis
-- Code quality validation
-- Coupling/cohesion assessment
-
-### Dependencies (--deps)
-
-- Read `package.json` / `pyproject.toml` / `pubspec.yaml`
-- Detect version conflicts, security vulnerabilities, outdated packages
-
-### Architecture (--arch)
-
-- Identify core modules
-- Map module dependencies
-- Detect circular dependencies and layer violations
-
-### Report
-
-Save to `.claude/vibe/reports/analysis-{date}.md`:
-
-```markdown
-# Project Analysis Report
-
-## Overview
-- Analysis date: YYYY-MM-DD HH:MM
-- Scope: Full / Code / Deps / Arch
-
-## Code Quality (N/100)
-- Average complexity: N (good/warning/critical)
-- High complexity files: N
-
-## Dependencies (N/100)
-- Total packages: N
-- Updates needed: N
-- Security issues: N
-
-## Architecture (N/100)
-- Circular dependencies: N found
-- Layer violations: N
-
-## Improvement Suggestions
-1. ...
-2. ...
-```
-
-## Core Tools (Semantic Analysis)
-
-### Tool Invocation
-
-```bash
-node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => t.TOOL_NAME({...args}).then(r => console.log(r.content[0].text)))"
-```
-
-### Available Tools
-
-| Tool | Purpose | When to Use |
-|------|---------|-------------|
-| `findSymbol` | Find symbol definitions | Locate function/class implementations |
-| `findReferences` | Find all references | Track usage patterns |
-| `analyzeComplexity` | Complexity analysis | Measure complexity metrics |
-| `validateCodeQuality` | Quality validation | Check code quality standards |
-| `saveMemory` | Save analysis results | Persist findings for future sessions |
-
----
-
-## Quality Gate (Mandatory)
-
-### Mode-Specific Checklists
-
-**Code/Feature Analysis:**
-
-| Category | Check Item | Weight |
-|----------|------------|--------|
-| Completeness | All related files identified | 20% |
-| Completeness | All API endpoints documented | 15% |
-| Completeness | All data models mapped | 15% |
-| Accuracy | File paths verified to exist | 10% |
-| Accuracy | Line numbers accurate | 10% |
-| Depth | Business logic explained | 10% |
-| Depth | Dependencies mapped | 10% |
-| Actionability | Next steps clearly defined | 10% |
-
-**Document Analysis:**
-
-| Category | Check Item | Weight |
-|----------|------------|--------|
-| Completeness | Full document read | 20% |
-| Completeness | All key concepts extracted | 20% |
-| Structure | Section structure identified | 15% |
-| Depth | Project relevance analyzed | 15% |
-| Depth | Gap analysis performed | 15% |
-| Actionability | Specific follow-up actions suggested | 15% |
-
-**Website Analysis:**
-
-| Category | Check Item | Weight |
-|----------|------------|--------|
-| Completeness | HTML fetched and parsed | 15% |
-| Tech | Tech stack identified | 15% |
-| UX | UX/UI patterns analyzed | 15% |
-| SEO | SEO elements inspected | 15% |
-| A11y | Accessibility checked | 15% |
-| Performance | Performance hints analyzed | 10% |
-| Actionability | Improvements suggested | 15% |
-
-### Score Calculation
-
-```
-Score = sum(checked items * weight) / 100
-
-Grades:
-- 95-100: EXCELLENT — comprehensive analysis
-- 90-94:  GOOD — minor gaps, additional exploration recommended
-- 80-89:  FAIR — needs deeper exploration
-- 0-79:   POOR — incomplete, re-analyze
-```
-
-### Depth Levels
-
-| Level | Scope | Output |
-|-------|-------|--------|
-| L1: Surface | File names, basic structure | File list |
-| L2: Structure | Functions, classes, imports | Structure map |
-| L3: Logic | Business logic, data flow | Flow analysis |
-| L4: Deep | Edge cases, dependencies, risks | Full analysis |
-
-**Minimum**: L3 for feature analysis, L2 for project overview.
-
-### Forbidden Patterns
-
-| Pattern | Problem | Fix |
-|---------|---------|-----|
-| "and more..." | Incomplete | List all items |
-| "etc." | Vague | Be specific |
-| "related files" without paths | Missing detail | Provide file paths |
-| Missing line numbers | Hard to navigate | Use `:L10-50` format |
-| No auth info on endpoints | Security gap | Always specify auth |
-
-### Quality Thresholds
-
-**Code (`--code`):**
-
-| Metric | Good | Warning | Critical |
-|--------|------|---------|----------|
-| Avg Complexity | ≤10 | 11-15 | >15 |
-| Max Function Length | ≤30 | 31-50 | >50 |
-| High Complexity Files | 0 | 1-3 | >3 |
-| Circular Dependencies | 0 | 1 | >1 |
-
-**Dependencies (`--deps`):**
-
-| Metric | Good | Warning | Critical |
-|--------|------|---------|----------|
-| Outdated Packages | 0-3 | 4-10 | >10 |
-| Security Vulnerabilities | 0 | 1-2 (low) | Any high/critical |
-| Major Version Behind | 0 | 1-2 | >2 |
-
----
-
-ARGUMENTS: $ARGUMENTS
+---
+description: Analyze any target — code, document, website, or Figma design
+argument-hint: "feature-name" or file.pdf or https://... or --code or --deps or --arch
+---
+
+# /vibe.analyze
+
+Analyze any target: source code, documents, websites, or Figma designs.
+
+## Usage
+
+```
+/vibe.analyze                  # Full project quality analysis
+/vibe.analyze "login"          # Feature/module code exploration + context collection
+/vibe.analyze --code           # Code quality analysis only
+/vibe.analyze --deps           # Dependency analysis only
+/vibe.analyze --arch           # Architecture analysis only
+/vibe.analyze report.pdf       # Document analysis (PDF, markdown, slides)
+/vibe.analyze https://example.com  # Website analysis (UX, tech, SEO, accessibility)
+/vibe.analyze https://figma.com/design/...  # Figma design analysis
+```
+
+## Input Type Auto-Detection
+
+Determine analysis mode from the argument pattern:
+
+| Pattern | Mode | Description |
+|---------|------|-------------|
+| `*.pdf`, `*.docx`, `*.pptx`, `*.md` (file path) | **Document** | Structure, content, quality, applicability |
+| `http(s)://figma.com/*` | **Figma** | Design structure, components, tokens |
+| `http(s)://*` | **Website** | UX, tech stack, SEO, accessibility |
+| `--code`, `--deps`, `--arch` | **Project Quality** | Code quality, dependencies, architecture |
+| String (feature name) | **Feature/Module** | Source code exploration + flow analysis |
+| No argument | **Project Quality** | Full project analysis |
+
+**Detection order**: file extension → URL pattern → flag → string.
+
+## File Reading Policy (Mandatory)
+
+- **SPEC/Feature files**: Always use `Read` tool for the full file (never Grep for content)
+- **Source files**: Read the entire file before analyzing (no partial reads)
+- **Grep restriction**: Use only for locating files, not for understanding content
+- **Agent prompts**: Always include "Read target files in full before analyzing"
+- **No partial analysis**: Never judge a file by a few lines around a Grep match
+
+## Context Reset
+
+**When this command runs, previous conversation is ignored.**
+- Explore and analyze from scratch like a new session
+- Base analysis only on newly collected information
+
+---
+
+> **Timer**: Record start time at the beginning. Include elapsed time in the final report.
+
+## Mode 1: Feature/Module Analysis (`/vibe.analyze "feature-name"`)
+
+### Goal
+
+Explore all source code related to the requested feature/module and analyze flow to:
+1. Understand current implementation status
+2. Map code structure and dependencies
+3. Build context for future development/modification requests
+
+### Process
+
+#### 1. Request Analysis
+
+Extract keywords from the user request:
+- Feature name (e.g., login, feed, payment)
+- Action (e.g., create, read, update, delete)
+- Scope (e.g., backend only, frontend only, full)
+
+#### 2. Understand Project Structure
+
+Read `CLAUDE.md`, `package.json`, `pyproject.toml`, etc. to identify tech stack:
+
+**Backend:**
+- FastAPI/Django: `app/api/`, `app/services/`, `app/models/`
+- Express/NestJS: `src/controllers/`, `src/services/`, `src/models/`
+
+**Frontend:**
+- React/Next.js: `src/components/`, `src/pages/`, `src/hooks/`
+- Flutter: `lib/screens/`, `lib/services/`, `lib/providers/`
+
+#### 3. Explore Related Code (Parallel Sub-Agents)
+
+**MANDATORY: Always use explorer sub-agents. Never explore in main session.**
+
+> Why: 3 explorer-low agents return ~600 tokens of summaries to main session.
+> Direct Glob/Grep/Read in main session would add 5-15K tokens of raw content.
+
+**Parallel exploration (ALL in ONE message):**
+
+```text
+Agent(subagent_type="explorer-low", model="haiku",
+  prompt="Find all [FEATURE] related API endpoints. List file paths, HTTP methods, routes, and auth requirements.")
+
+Agent(subagent_type="explorer-low", model="haiku",
+  prompt="Find all [FEATURE] related services, business logic, and utility functions. Map dependencies.")
+
+Agent(subagent_type="explorer-low", model="haiku",
+  prompt="Find all [FEATURE] related data models, schemas, and database queries. Document relationships and key fields.")
+```
+
+**Scale for large projects (6+ related files):**
+
+```text
+Agent(subagent_type="explorer-low", model="haiku",
+  prompt="Find all test files related to [FEATURE]. Identify tested vs untested paths.")
+
+Agent(subagent_type="explorer-low", model="haiku",
+  prompt="Analyze [FEATURE] configuration, environment variables, and external integrations.")
+```
+
+**After all agents return:**
+- Synthesize results → proceed to Flow Analysis
+- Only Read specific files in main session when agent summaries need clarification
+
+#### 4. Flow Analysis
+
+**API Flow:**
+- Endpoint URL and HTTP method
+- Request/response schema
+- Authentication/authorization requirements
+
+**Business Logic:**
+- Core methods and their roles
+- Validation rules
+- External service integrations
+
+**Data Flow:**
+- Related tables/models
+- Relationships (1:N, N:M)
+- Key query patterns
+
+#### 5. Output
+
+```markdown
+## [feature-name] Analysis Results
+
+### Overview
+- **Feature**: [one-line summary]
+- **Status**: [Complete / In progress / Not implemented]
+- **Files**: N related files
+
+### Structure
+
+#### API Endpoints
+| Method | Path | Description | Auth |
+|--------|------|-------------|------|
+| POST | /api/v1/auth/login | User login | None |
+
+#### Core Services
+- `auth_service.py`: Authentication logic
+  - `login()`: Processes login
+  - `verify_token()`: Validates JWT
+
+#### Data Models
+- `User`: User table
+  - Key fields: id, email, password_hash
+  - Relationships: Session (1:N)
+
+### Reference Files
+- src/api/auth/router.py:L10-50
+- src/services/auth_service.py:L1-100
+```
+
+#### 6. Next Steps
+
+After analysis, suggest mode-specific follow-up actions:
+
+**After code/feature analysis:**
+
+| Task Scope | Approach |
+|------------|----------|
+| Simple fix (1-2 files) | Plan Mode |
+| Complex feature (3+ files) | `/vibe.spec` |
+
+**After document analysis:**
+
+| Goal | Approach |
+|------|----------|
+| Apply findings to project | `/vibe.spec "feature-name"` |
+| Derive improvement direction | Plan Mode |
+| Compare with another source | `/vibe.analyze [other target]` |
+
+**After website analysis:**
+
+| Goal | Approach |
+|------|----------|
+| Build similar product | `/vibe.spec` |
+| Improve existing UI | `/vibe.figma` |
+| Compare with another site | `/vibe.analyze [other URL]` |
+
+Wait for user's choice before proceeding.
+
+---
+
+## Mode 2: Document Analysis (PDF, Markdown, Slides)
+
+### Goal
+
+Analyze document **structure, key content, quality, and applicability** to:
+1. Extract and organize information from the document
+2. Map relevance to the current project
+3. Suggest follow-up actions (development, improvement, application)
+
+### Process
+
+#### 1. Read Document
+
+- **PDF**: Use `Read` tool with `pages` parameter (split large documents into chunks of 20 pages)
+- **Markdown/Text**: Use `Read` tool for the full file
+- **Image-heavy documents**: Analyze visual elements (slides, diagrams) alongside text
+
+#### 2. Classify Document Type
+
+| Type | Analysis Focus |
+|------|---------------|
+| Technical spec | API definitions, data models, sequence diagrams |
+| Presentation/slides | Key claims, frameworks, case studies |
+| PRD/requirements | User stories, acceptance criteria, scope |
+| Business document | Strategy, decision points, action items |
+| Research/academic | Methodology, conclusions, applicability |
+
+#### 3. Analyze Content (Parallel Sub-Agents)
+
+```text
+Agent(subagent_type="general-purpose", model="haiku",
+  prompt="Read the document at [PATH] and extract: 1) Section structure / table of contents 2) Key concepts and definitions 3) Main arguments or claims. Use the Read tool with pages parameter for PDFs.")
+
+Agent(subagent_type="general-purpose", model="haiku",
+  prompt="Read the document at [PATH] and extract: 1) Actionable recommendations 2) Data points, metrics, examples 3) References to external resources. Use the Read tool with pages parameter for PDFs.")
+```
+
+#### 4. Project Relevance Analysis
+
+- Map how document content applies to the current project
+- Check if patterns/tools/techniques mentioned are already implemented
+- Gap analysis: document recommendations vs current project state
+
+#### 5. Output
+
+```markdown
+## [Document Name] Analysis
+
+### Overview
+- **Type**: [Presentation / Technical spec / PRD / ...]
+- **Topic**: [one-line summary]
+- **Pages/Sections**: N
+- **Audience**: [Developers / PMs / Executives / ...]
+
+### Key Content
+1. **[Concept 1]**: Description
+2. **[Concept 2]**: Description
+
+### Frameworks/Models (if any)
+- [Systematic structure presented in the document]
+
+### Project Relevance
+| Recommendation | Current State | Gap |
+|----------------|---------------|-----|
+| ... | ... | ... |
+
+### Key Insights
+- [Most important takeaway]
+
+### Suggested Actions
+1. ...
+```
+
+#### Fallback
+
+If `Read` fails for a document format:
+1. Check file extension and try alternative parsing
+2. If binary format is unsupported, inform user and suggest converting to PDF/markdown
+3. Never produce an analysis based on partial or failed reads
+
+---
+
+## Mode 3: Website Analysis (URL)
+
+### Goal
+
+Analyze website **tech stack, UX/UI, SEO, accessibility, and performance** to:
+1. Understand technical implementation
+2. Identify improvement opportunities
+3. Collect benchmarking insights
+
+### Process
+
+#### 1. Fetch Website
+
+- Use `WebFetch` tool to retrieve HTML
+- Fetch key pages (home, main feature pages, login, etc.)
+
+#### 2. Analyze (Parallel Sub-Agents)
+
+```text
+Agent(subagent_type="general-purpose", model="haiku",
+  prompt="Analyze the HTML from [URL] (use WebFetch). Extract: 1) Tech stack (framework, meta tags, scripts) 2) Page structure (header, nav, main sections, footer) 3) SEO elements (title, meta description, OG tags, structured data)")
+
+Agent(subagent_type="general-purpose", model="haiku",
+  prompt="Analyze the HTML from [URL] (use WebFetch). Extract: 1) Accessibility (ARIA labels, semantic HTML, alt texts, heading hierarchy) 2) Performance hints (script loading, image optimization) 3) Mobile responsiveness (viewport meta, media queries)")
+
+Agent(subagent_type="general-purpose", model="haiku",
+  prompt="Analyze the HTML from [URL] (use WebFetch). Extract: 1) UX patterns (navigation, CTA placement, form design) 2) Design system hints (CSS variables, component patterns) 3) Content strategy (copywriting tone, information hierarchy)")
+```
+
+#### 3. Figma URL Handling
+
+If a Figma URL is detected, switch to **Figma-specific analysis**:
+- Use `get_design_context` or `get_screenshot` to collect design data
+- Analyze component structure, design tokens, layout patterns
+- Compare design intent with current project code
+
+#### 4. Output
+
+```markdown
+## [URL] Analysis
+
+### Overview
+- **Site type**: [SaaS / E-commerce / Portfolio / ...]
+- **Tech stack**: [Next.js, Tailwind, ...]
+- **Overall score**: N/100
+
+### Technical Analysis
+| Area | Detection | Details |
+|------|-----------|---------|
+| Framework | React/Next.js | SSR enabled |
+| CSS | Tailwind CSS | v3.4 |
+
+### UX/UI Analysis
+- **Navigation**: [assessment]
+- **CTA placement**: [assessment]
+- **Responsive design**: [assessment]
+
+### SEO Analysis (N/100)
+| Element | Status | Recommendation |
+|---------|--------|----------------|
+| Title | Present | Appropriate length |
+| Meta Description | Missing | Add description |
+
+### Accessibility (WCAG 2.1 AA)
+- **Semantic HTML**: [assessment]
+- **Keyboard navigation**: [assessment]
+- **Screen reader support**: [assessment]
+
+### Improvement Suggestions
+1. [highest priority]
+2. ...
+```
+
+#### Fallback
+
+If `WebFetch` fails:
+1. Retry once with a simplified URL (strip query params)
+2. If still failing, inform user of the error (timeout, DNS, etc.)
+3. Suggest user provide HTML file directly: `/vibe.analyze page.html`
+
+---
+
+## Mode 4: Project Quality Analysis (--code/--deps/--arch)
+
+### Scope
+
+- **Default** (`/vibe.analyze`): Full analysis (code + dependencies + architecture)
+- `--code`: Code quality only
+- `--deps`: Dependency analysis only
+- `--arch`: Architecture analysis only
+
+### Code Quality (--code)
+
+- Cyclomatic complexity analysis
+- Code quality validation
+- Coupling/cohesion assessment
+
+### Dependencies (--deps)
+
+- Read `package.json` / `pyproject.toml` / `pubspec.yaml`
+- Detect version conflicts, security vulnerabilities, outdated packages
+
+### Architecture (--arch)
+
+- Identify core modules
+- Map module dependencies
+- Detect circular dependencies and layer violations
+
+### Report
+
+Save to `.claude/vibe/reports/analysis-{date}.md`:
+
+```markdown
+# Project Analysis Report
+
+## Overview
+- Analysis date: YYYY-MM-DD HH:MM
+- Scope: Full / Code / Deps / Arch
+
+## Code Quality (N/100)
+- Average complexity: N (good/warning/critical)
+- High complexity files: N
+
+## Dependencies (N/100)
+- Total packages: N
+- Updates needed: N
+- Security issues: N
+
+## Architecture (N/100)
+- Circular dependencies: N found
+- Layer violations: N
+
+## Improvement Suggestions
+1. ...
+2. ...
+```
+
+## Core Tools (Semantic Analysis)
+
+### Tool Invocation
+
+```bash
+node -e "import('{{VIBE_PATH_URL}}/node_modules/@su-record/vibe/dist/tools/index.js').then(t => t.TOOL_NAME({...args}).then(r => console.log(r.content[0].text)))"
+```
+
+### Available Tools
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `findSymbol` | Find symbol definitions | Locate function/class implementations |
+| `findReferences` | Find all references | Track usage patterns |
+| `analyzeComplexity` | Complexity analysis | Measure complexity metrics |
+| `validateCodeQuality` | Quality validation | Check code quality standards |
+| `saveMemory` | Save analysis results | Persist findings for future sessions |
+
+---
+
+## Quality Gate (Mandatory)
+
+### Mode-Specific Checklists
+
+**Code/Feature Analysis:**
+
+| Category | Check Item | Weight |
+|----------|------------|--------|
+| Completeness | All related files identified | 20% |
+| Completeness | All API endpoints documented | 15% |
+| Completeness | All data models mapped | 15% |
+| Accuracy | File paths verified to exist | 10% |
+| Accuracy | Line numbers accurate | 10% |
+| Depth | Business logic explained | 10% |
+| Depth | Dependencies mapped | 10% |
+| Actionability | Next steps clearly defined | 10% |
+
+**Document Analysis:**
+
+| Category | Check Item | Weight |
+|----------|------------|--------|
+| Completeness | Full document read | 20% |
+| Completeness | All key concepts extracted | 20% |
+| Structure | Section structure identified | 15% |
+| Depth | Project relevance analyzed | 15% |
+| Depth | Gap analysis performed | 15% |
+| Actionability | Specific follow-up actions suggested | 15% |
+
+**Website Analysis:**
+
+| Category | Check Item | Weight |
+|----------|------------|--------|
+| Completeness | HTML fetched and parsed | 15% |
+| Tech | Tech stack identified | 15% |
+| UX | UX/UI patterns analyzed | 15% |
+| SEO | SEO elements inspected | 15% |
+| A11y | Accessibility checked | 15% |
+| Performance | Performance hints analyzed | 10% |
+| Actionability | Improvements suggested | 15% |
+
+### Score Calculation
+
+```
+Score = sum(checked items * weight) / 100
+
+Grades:
+- 95-100: EXCELLENT — comprehensive analysis
+- 90-94:  GOOD — minor gaps, additional exploration recommended
+- 80-89:  FAIR — needs deeper exploration
+- 0-79:   POOR — incomplete, re-analyze
+```
+
+### Depth Levels
+
+| Level | Scope | Output |
+|-------|-------|--------|
+| L1: Surface | File names, basic structure | File list |
+| L2: Structure | Functions, classes, imports | Structure map |
+| L3: Logic | Business logic, data flow | Flow analysis |
+| L4: Deep | Edge cases, dependencies, risks | Full analysis |
+
+**Minimum**: L3 for feature analysis, L2 for project overview.
+
+### Forbidden Patterns
+
+| Pattern | Problem | Fix |
+|---------|---------|-----|
+| "and more..." | Incomplete | List all items |
+| "etc." | Vague | Be specific |
+| "related files" without paths | Missing detail | Provide file paths |
+| Missing line numbers | Hard to navigate | Use `:L10-50` format |
+| No auth info on endpoints | Security gap | Always specify auth |
+
+### Quality Thresholds
+
+**Code (`--code`):**
+
+| Metric | Good | Warning | Critical |
+|--------|------|---------|----------|
+| Avg Complexity | ≤10 | 11-15 | >15 |
+| Max Function Length | ≤30 | 31-50 | >50 |
+| High Complexity Files | 0 | 1-3 | >3 |
+| Circular Dependencies | 0 | 1 | >1 |
+
+**Dependencies (`--deps`):**
+
+| Metric | Good | Warning | Critical |
+|--------|------|---------|----------|
+| Outdated Packages | 0-3 | 4-10 | >10 |
+| Security Vulnerabilities | 0 | 1-2 (low) | Any high/critical |
+| Major Version Behind | 0 | 1-2 | >2 |
+
+---
+
+ARGUMENTS: $ARGUMENTS