dev-analyze

name	dev-analyze
description	Phân tích task/issue và đề xuất 2-3 phương án implement với trade-off. Dùng multi-agent để giữ context sạch. Trigger khi: user nói "analyze task", "phân tích issue", "xem có cách nào làm", "đề xuất phương án", "implementation options", hoặc gõ /dev-analyze.

Skill: /dev-analyze

Role: Developer
Mục đích: Phân tích task/issue và đề xuất các phương án thi công. Dùng multi-agent để giữ context sạch.

---

Brain Dump Pattern (input contract)

Trước khi chạy skill này, dev nên cung cấp context block sau để giảm hallucination:

Tech stack: [language, framework, DB, infra]
Relevant files: [file paths đã biết liên quan]
Constraints: [performance, security, backward compat, deadline]
Known gotchas: [vấn đề đã biết trong codebase]
Issue/Task: [link hoặc paste nội dung]

Nếu không có đủ context → skill sẽ hỏi trước khi tiếp tục.

---

Kiến trúc Multi-Agent

Skill này orchestrate các subagent để giữ context sạch:

dev-analyze (orchestrator)
├── [Subagent 1] task-reader    → parse issue → structured understanding
├── [Subagent 2] code-scout     → tìm code liên quan (read-only)
└── [Subagent 3] planner        → tổng hợp → đề xuất phương án

Mỗi subagent nhận chỉ context cần thiết, trả về kết quả nén.

Cách spawn subagent

Dùng Agent tool để spawn mỗi subagent. Prompt phải self-contained — không pass full conversation history.

Ví dụ spawn task-reader:

Agent(
  description: "Parse GitHub issue into structured JSON",
  prompt: "Read this issue and return structured JSON per agents/task-reader.md spec.\n\nISSUE CONTENT:\n[paste issue content here]",
  model: "haiku"
)

Ví dụ spawn code-scout:

Agent(
  description: "Find relevant files for auth task",
  prompt: "Find files relevant to this task. Return JSON per agents/code-scout.md spec.\n\nTASK SUMMARY: [summary]\nTECH STACK: [stack]\nAFFECTED AREAS: [areas]",
  model: "haiku"
)

Ví dụ spawn planner:

Agent(
  description: "Synthesize task + code map into implementation options",
  prompt: "Create 2-3 implementation options per agents/planner.md spec.\n\nTASK: [task-reader JSON]\nCODE MAP: [code-scout JSON]\nCONSTRAINTS: [from Gate 1]",
  model: "sonnet"
)

---

Hướng dẫn thực hiện

Bước 0 — Risk Classification

Trước khi spawn bất kỳ subagent nào, classify risk theo docs/risk-classifier.md:

## Risk Classification — [TASK-ID]

**Input type**: [new-spec | spec-slice | change-request | maintenance | new-initiative | framework-improvement]
**Risk checklist**: [chỉ liệt kê items YES — ví dụ: R-06 ✅ (shared config)]
**Lane**: tiny | normal | high-risk
**Lý do**: [1 câu]

• Tiny lane → skip toàn bộ skill này, patch trực tiếp
• High-risk lane → dừng ngay, hiện ⚠️ Ask First Gate, chờ confirm senior trước khi tiếp tục
• Normal lane → tiếp tục Bước 1 bên dưới

Bước 1 — Spawn Subagent: task-reader

Spawn subagent với nhiệm vụ:

"Đọc issue/task sau và trả về JSON structured:

• task_id, title, type (feature/bug/refactor)
• business_goal (tại sao cần làm)
• acceptance_criteria (list)
• technical_hints (nếu có trong issue)
• unknowns (những gì chưa rõ)

Issue content: [paste nội dung issue]"

Subagent CHỈ nhận nội dung issue, không nhận codebase context.

Bước 2 — Gate 1: Xác nhận hiểu task

## Tôi đọc task [TASK-ID] và hiểu như sau:

**Mục tiêu**: [business goal]
**Loại**: [Feature/Bug/Refactor]
**Acceptance Criteria**:
  - AC-001: [...]
  - AC-002: [...]

**Những điều chưa rõ**:
  - [?] [Điểm chưa rõ 1]
  - [?] [Điểm chưa rõ 2]

Trước khi tôi scan codebase, hãy xác nhận:

| # | Câu hỏi | Lựa chọn |
|---|---------|---------|
| 1 | Tôi hiểu đúng mục tiêu chưa? | A: Đúng rồi / B: Chưa — sửa lại: ___ / C: Khác: ___ |
| 2 | Có constraint nào không đề cập trong issue? | A: Không / B: Có — constraint: ___ / C: Khác: ___ |
| 3 | Có màn hình/API doc nào tôi nên đọc trước? | A: Không cần / B: Có — link/path: ___ / C: Khác: ___ |

Chờ confirm.

Bước 3 — Spawn Subagent: code-scout

Sau khi nhận confirm, spawn subagent với nhiệm vụ:

"Tìm trong codebase các file/module liên quan đến: [task summary]. Trả về:

• file_path:line_number cho mỗi điểm liên quan
• Mô tả ngắn tại sao file đó liên quan
• Patterns/conventions hiện tại cần theo

CHỈ đọc, không sửa gì cả."

Subagent nhận task summary + file patterns để tìm kiếm, không nhận full conversation history.

Bước 4 — Gate 2: Xác nhận code map

## Tôi tìm thấy các file liên quan:

| File | Line | Tại sao liên quan |
|------|------|-------------------|
| [path] | [N] | [...] |

**Conventions hiện tại**:
- [Pattern 1]
- [Pattern 2]

| # | Câu hỏi | Lựa chọn |
|---|---------|---------|
| 1 | Có file quan trọng nào tôi bỏ sót không? | A: Không / B: Có — file: ___ / C: Khác: ___ |
| 2 | Có module nào nên TRÁNH chạm vào trong task này? | A: Không / B: Có — module: ___ / C: Khác: ___ |

Chờ confirm.

Bước 5 — Spawn Subagent: planner

Spawn subagent với:

"Dựa trên:

• Task: [summary]
• AC: [list]
• Relevant files: [file map]
• Constraints: [từ Gate 1]

Đề xuất 2-3 phương án implement với trade-off. Mỗi phương án gồm: tên, mô tả, files cần thay đổi, estimate, ưu/nhược."

Bước 5.5 — Parallel Design Stubs (nếu planner xác định artifact type)

Dựa trên planner output, spawn parallel design agents trong cùng 1 message (chạy song song):

• Nếu task có màn hình mới hoặc sửa màn hình hiện tại → spawn screen-designer (model: haiku) theo agents/screen-designer.md
• Nếu task có API endpoint mới hoặc thay đổi contract API → spawn api-designer (model: haiku) theo agents/api-designer.md
• Nếu task không có màn hình / API → bỏ qua bước này, tiếp tục Bước 6

Mỗi agent nhận input:

TASK SUMMARY: [task-reader JSON summary]
SELECTED OPTION: [tên + mô tả phương án planner đề xuất cao nhất]
AFFECTED SCREENS / AFFECTED APIS: [từ planner output hoặc code-scout]
EXISTING DOCS: [nội dung docs/screens hoặc docs/api liên quan nếu có]

Merge kết quả từ các agents vào docs/tasks/[TASK-ID]/analysis.md dưới section riêng:

• ## Screen Design Stub — từ screen-designer output
• ## API Design Stub — từ api-designer output

Stub này giúp human có đủ thông tin để chọn phương án ở Bước 6.

✓ Design stubs đã sinh:
  - Screen: [N] màn hình — [tên danh sách]
  - API: [N] endpoint — [danh sách method + path]
  Xem chi tiết trong analysis.md trước khi chọn phương án.

---

Bước 6 — Gate 3: Trình bày phương án (QUAN TRỌNG NHẤT)

## Tôi có [N] phương án thi công:

### Phương án A: [Tên] — [Từ khóa đặc trưng]
**Mô tả**: [...]
**Files cần thay đổi**:
  - `[file]` — [lý do]
**Estimate**: [X giờ]
**Ưu**: [...]
**Nhược**: [...]
**Risk**: [...]

### Phương án B: [Tên]
[tương tự]

### Phương án C: [Tên] (nếu có)
[tương tự]

---
**Đề xuất của tôi**: Phương án [X] vì [lý do cụ thể].

Trước khi bạn chọn, tôi cần hỏi thêm:

| # | Câu hỏi | Lựa chọn |
|---|---------|---------|
| 1 | [Câu hỏi về constraint ảnh hưởng đến lựa chọn] | _(điền vào)_ |
| 2 | Priority: speed vs maintainability? | A: Ưu tiên tốc độ deliver / B: Ưu tiên maintainability / C: Cân bằng cả hai / D: Khác: ___ |

**Bạn muốn chọn phương án nào?**

| | Lựa chọn |
|---|---------|
| A | Phương án A |
| B | Phương án B |
| C | Phương án C |
| D | Khác: ___ |

Chờ human chọn phương án.

Bước 6.5 — Render HTML companion (so sánh phương án)

Trước khi human chọn ở Bước 6, sinh docs/tasks/[TASK-ID]/analysis-compare.html từ template templates/html-artifact.html:

• Inject <table id="options" data-sortable> với các cột: Phương án | Effort (h) | Risk | Files chạm | Ưu | Nhược
• Mỗi phương án 1 row, cột Effort dùng data-type="number" để sort
• Risk render bằng <span class="pill pill-ok|warn|err"> (Low/Med/High)
• Mỗi phương án có <details> mở rộng cho mô tả dài

File HTML là one-shot review artifact — KHÔNG commit (đã có .gitignore cho docs/tasks/**/*.html).

✓ Đã sinh `docs/tasks/[TASK-ID]/analysis-compare.html`
  Mở bằng browser để sort/filter trước khi quyết định.

Bước 7 — Tạo Task Doc

Sau khi human chọn, tạo docs/tasks/[TASK-ID]/analysis.md:

# Analysis: [TASK-ID]

## Phương án đã chọn: [Tên]
**Lý do**: [từ discussion]

## Files sẽ thay đổi
| File | Loại thay đổi | Ghi chú |
|------|--------------|---------|
| | | |

## Những phương án đã cân nhắc và lý do không chọn
- Phương án A: [lý do không chọn]
- Phương án B: [lý do không chọn]

## Câu hỏi mở còn lại
- [ ] [Question nếu có]

## Phân tích hoàn tất ✓

`docs/tasks/[TASK-ID]/analysis.md` đã được lưu.

**DỪNG TẠI ĐÂY.** Không tự động implement.

Hãy review `analysis.md`, sau đó dùng `/dev-implement` để bắt đầu code.

Chờ human trigger /dev-implement.
Không được tự ý bắt đầu implement dù user có vẻ đồng ý.

---

Lưu ý cho orchestrator

• Mỗi subagent nhận context tối thiểu cần thiết
• Không pass full conversation history vào subagent
• Kết quả từ subagent được tóm tắt trước khi dùng cho subagent tiếp theo
• Nếu subagent trả về quá nhiều file (>20), yêu cầu lọc thêm