dw-kit 1.2.1 → 1.3.4

package/.claude/skills/dw-retroactive/SKILL.md

@@ -1,311 +1,195 @@
----
-name: dw-retroactive
-description: "Retroactively document một feature/task đã được implement trước khi dùng dw. Reverse-engineer từ code + git history, tạo đầy đủ context + as-built plan + progress docs. Dùng khi cần AI hiểu sâu một module cũ."
-argument-hint: "[feature-name]"
-allowed-tools:
-  - Read
-  - Grep
-  - Glob
-  - Write
-  - "Bash(git log *)"
-  - "Bash(git diff *)"
-  - "Bash(git show *)"
-  - "Bash(git blame *)"
-  - "Bash(git shortlog *)"
-  - "Bash(ls *)"
----
-
-# dw-retroactive — Retroactive Documentation
-
-Feature: **$ARGUMENTS**
-
-> Reverse-engineer feature đã tồn tại từ code và git history. Tạo đầy đủ task docs như thể đã đi qua workflow dw — để AI (và team) có context đầy đủ khi làm việc liên quan feature này.
-
----
-
-## Đọc Config
-
-Đọc `.dw/config/dw.config.yml`:
-- `paths.tasks` → output location (mặc định `.dw/tasks`)
-- `project.language` → ngôn ngữ docs
-
-## Kiểm tra đã có docs chưa
-
-Kiểm tra `{paths.tasks}/$ARGUMENTS/` đã tồn tại chưa:
-- Nếu rồi → hỏi user: "Đã có task docs cho `$ARGUMENTS`. Overwrite hay skip?"
-- Nếu chưa → tiếp tục
-
----
-
-## Bước 1: Tìm files liên quan
-
-Dùng tên `$ARGUMENTS` như keyword để tìm:
-
-```
-Glob: **/*$ARGUMENTS*
-Grep: "$ARGUMENTS" trong toàn codebase (case-insensitive)
-Grep: tên function/class/route liên quan (nếu có thể suy ra từ tên)
-```
-
-Nếu không tìm được → hỏi user: "Không tìm thấy files liên quan `$ARGUMENTS`. Bạn có thể cung cấp thêm keyword hoặc path không?"
-
-## Bước 2: Đọc và phân tích code
-
-Với mỗi file tìm được:
-
-1. **Đọc toàn bộ file** (hoặc phần liên quan)
-2. Xác định:
-   - Vai trò của file trong feature này
-   - Logic chính / business rules
-   - Input/Output/Side effects
-   - Error handling patterns
-3. **Trace data flow**: đầu vào từ đâu → xử lý gì → kết quả đi đâu
-4. **Tìm dependencies**: module này gọi gì? Ai gọi module này?
-5. **Tìm tests**: test files liên quan, coverage hiện tại
-
-## Bước 3: Phân tích git history
-
-```bash
-# Commits liên quan feature
-git log --oneline --follow -- [files-found]
-
-# Ai đã implement
-git shortlog -sn -- [files-found]
-
-# Thay đổi đáng kể
-git log --oneline --diff-filter=A -- [files-found]   # khi files được tạo
-
-# Context của lần commit đầu tiên
-git show [first-commit] --stat
-```
-
-Xác định:
-- Feature được tạo khi nào
-- Ai implement (để biết ai có thể được hỏi)
-- Có breaking changes nào đã được fix sau đó không
-- Tech debt nào đang tồn tại (TODO, FIXME trong code)
-
-## Bước 4: Áp dụng tư duy phản biện
-
-Từ framework `core/THINKING.md` (hoặc `.claude/skills/dw-thinking/THINKING.md`):
-
-- **Giả định**: Code đang giả định gì về input, state, environment?
-- **Failure modes**: Điều gì có thể làm feature này fail? Edge cases nào?
-- **Tech debt**: Có TODO/FIXME? Có antipatterns? Code mùi?
-- **Security**: Có điểm nào đáng lo ngại về auth, validation, data exposure?
-
-## Bước 5: Tạo task docs
-
-Tạo thư mục `{paths.tasks}/$ARGUMENTS/` và 3 files:
-
-### 5a. Context doc
-
-Tạo `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-context.md`:
-
-```markdown
-# Context: $ARGUMENTS
-
-## Ngày khảo sát: [date]
-## Loại: Retroactive Documentation
-## Người thực hiện: agent (dw-retroactive)
-
----
-
-## Mô Tả Feature
-
-[2-3 câu mô tả feature làm gì, phục vụ ai]
-
-## Codebase Analysis
-
-### Files Liên Quan
-
-| # | File | Vai trò | Ghi chú |
-|---|------|---------|---------|
-| 1 | [file] | [vai trò] | |
-
-### Kiến Trúc
-
-```
-[ASCII diagram hoặc mô tả luồng]
-Input → [Module] → Output
-           ↓
-      [Dependencies]
-```
-
-### Data Flow
-
-- **Input**: [từ đâu, format gì]
-- **Processing**: [logic chính]
-- **Output**: [đi đâu, format gì]
-- **Side effects**: [DB writes, events, external calls]
-
-## Dependencies
-
-### Upstream (feature phụ thuộc vào)
-- [ ] [Module/Service] — [vai trò]
-
-### Downstream (ai phụ thuộc vào feature này)
-- [ ] [Module/Service] — [ảnh hưởng thế nào]
-
-## Git History
-
-- **Tạo lần đầu**: [date] bởi [author]
-- **Commits**: [N commits]
-- **Maintainer chính**: [author]
-- **Thay đổi đáng kể**: [mô tả nếu có]
-
-## Test Coverage
-
-- [ ] Có tests: [Có/Không]
-- Test files: [danh sách]
-- Coverage: [mô tả]
-- Gaps: [thiếu test ở đâu]
-
-## Giả Định & Hạn Chế
-
-| # | Giả định/Hạn chế | Mức độ rủi ro |
-|---|-----------------|--------------|
-| 1 | [giả định trong code] | Cao/TB/Thấp |
-
-## Tech Debt & Warnings
-
-- [ ] [TODO/FIXME đang có]
-- [ ] [Antipatterns phát hiện]
-- [ ] [Security concerns]
-
-## Ghi Chú Cho AI
-
-> Context quan trọng khi làm task liên quan feature này:
-- [Gotcha 1]
-- [Gotcha 2]
-```
-
-### 5b. As-Built Plan doc
-
-Tạo `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md`:
-
-```markdown
-# As-Built Plan: $ARGUMENTS
-
-## Ngày tạo: [date]
-## Loại: As-Built (Retroactive) — không phải forward plan
-## Trạng thái: Done (implemented trước khi adopt dw)
-## Implemented by: [author từ git history]
-
----
-
-> ⚠ Đây là tài liệu retroactive — mô tả những gì ĐÃ được implement,
-> không phải plan cho việc sẽ làm. Dùng để AI và team hiểu context.
-
-## Tóm Tắt Giải Pháp Đã Implement
-
-[Mô tả approach được dùng, dựa trên code analysis]
-
-## Những Gì Đã Implement
-
-### Component 1: [Tên]
-- **Mô tả**: [làm gì]
-- **Files**: [danh sách]
-- **Cách hoạt động**: [tóm tắt logic]
-
-### Component 2: [Tên]
-...
-
-## Quyết Định Kỹ Thuật Đáng Chú Ý
-
-| Quyết định | Approach đã dùng | Lý do suy đoán |
-|-----------|-----------------|----------------|
-| [decision] | [approach] | [inferred from code/commits] |
-
-## Rủi Ro & Hạn Chế Đã Biết
-
-| # | Mô tả | Mức độ | Trạng thái |
-|---|-------|--------|-----------|
-| 1 | [risk] | Cao/TB/Thấp | Open/Resolved |
-
-## Edge Cases
-
-- [ ] [Edge case được xử lý hay chưa?]
-
-## Tác Động Hệ Thống
-
-- **Modules ảnh hưởng**: [danh sách]
-- **API**: [endpoints liên quan]
-- **Database**: [schema/tables liên quan]
-```
-
-### 5c. Progress doc
-
-Tạo `{paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md`:
-
-```markdown
-# Progress: $ARGUMENTS
-
-## Trạng thái: Done (Pre-dw Implementation)
-## Loại: Retroactive Documentation
-## Documented on: [date]
-
----
-
-> Feature này đã được implement trước khi adopt dw-kit.
-> File này được tạo retroactively để AI có context khi làm task liên quan.
-
-## Implementation History (từ git)
-
-| Thời điểm | Sự kiện | Author |
-|-----------|---------|--------|
-| [date] | Feature được tạo | [author] |
-| [date] | [notable change] | [author] |
-
-## Known Issues / Open Items
-
-- [ ] [Issue đang mở nếu có]
-- [ ] [Tech debt cần xử lý]
-
-## Handoff Notes cho AI
-
-Khi làm task liên quan feature này:
-- **Đọc trước**: `$ARGUMENTS-context.md` để hiểu architecture
-- **Cẩn thận**: [warning 1]
-- **Không thay đổi**: [phần nào là stable contract]
-- **Có thể refactor**: [phần nào an toàn để thay đổi]
-```
-
----
-
-## Bước 6: Báo cáo kết quả
-
-```
-╔══════════════════════════════════════════════════════╗
-║  ✅ dw-retroactive complete: $ARGUMENTS
-╠══════════════════════════════════════════════════════╣
-║  Files khảo sát    : [N files]
-║  Git commits       : [N commits, từ [date] đến [date]]
-║  Maintainer chính  : [author]
-╠══════════════════════════════════════════════════════╣
-║  Docs đã tạo:
-║    {paths.tasks}/$ARGUMENTS/$ARGUMENTS-context.md
-║    {paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md  (as-built)
-║    {paths.tasks}/$ARGUMENTS/$ARGUMENTS-progress.md
-╠══════════════════════════════════════════════════════╣
-║  Key findings:
-║  • [Finding 1]
-║  • [Finding 2]
-║  • [Finding 3]
-╠══════════════════════════════════════════════════════╣
-║  Tech debt / warnings:
-║  • [Warning nếu có]
-╠══════════════════════════════════════════════════════╣
-║  Tiếp theo:
-║  → Khi cần task liên quan: /dw-research $ARGUMENTS
-║     (AI sẽ đọc context docs vừa tạo làm foundation)
-╚══════════════════════════════════════════════════════╝
-```
-
----
-
-## Lưu ý
-
-- **As-built ≠ forward plan**: Docs này mô tả hiện trạng, không phải kế hoạch
-- **Best-effort**: AI chỉ thấy được những gì có trong code và git — context ẩn (verbal decisions, Slack threads) có thể thiếu. Cần human review và bổ sung.
-- **Sau khi tạo**: Khuyến khích dev liên quan review và bổ sung `## Ghi Chú Cho AI` section
+---
+name: dw:retroactive
+description: "Retroactively document một feature/task đã được implement trước khi dùng dw. Reverse-engineer từ code + git history, tạo spec.md + tracking.md (v2 format, As-Built flavor)."
+argument-hint: "[feature-name]"
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - Write
+  - "Bash(git log *)"
+  - "Bash(git diff *)"
+  - "Bash(git show *)"
+  - "Bash(git blame *)"
+  - "Bash(git shortlog *)"
+  - "Bash(ls *)"
+---
+
+# dw-retroactive — Retroactive Documentation
+
+Feature: **$ARGUMENTS**
+
+> Reverse-engineer feature đã tồn tại từ code + git history. Tạo task docs v2 format (`spec.md` + `tracking.md`) với flavor As-Built — để AI và team có context đầy đủ khi làm task liên quan.
+
+---
+
+## Đọc Config
+
+Đọc `.dw/config/dw.config.yml`:
+- `paths.tasks` → output location (mặc định `.dw/tasks`)
+- `project.language` → ngôn ngữ docs (vi/en)
+
+## Kiểm tra đã có docs chưa
+
+Kiểm tra `{paths.tasks}/$ARGUMENTS/` đã tồn tại chưa:
+- Nếu có `spec.md` hoặc `tracking.md` → hỏi user: "Đã có task docs cho `$ARGUMENTS`. Overwrite hay skip?"
+- Nếu chưa → tiếp tục
+
+---
+
+## Bước 1: Tìm files liên quan
+
+Dùng tên `$ARGUMENTS` như keyword để tìm:
+
+```
+Glob: **/*$ARGUMENTS*
+Grep: "$ARGUMENTS" trong toàn codebase (case-insensitive)
+Grep: tên function/class/route liên quan (nếu có thể suy ra từ tên)
+```
+
+Nếu không tìm được → hỏi user cung cấp thêm keyword hoặc path.
+
+## Bước 2: Đọc và phân tích code
+
+Với mỗi file tìm được:
+
+1. **Đọc toàn bộ file** (hoặc phần liên quan)
+2. Xác định: vai trò trong feature, logic chính, I/O, side effects, error handling
+3. **Trace data flow**: input → xử lý → output
+4. **Dependencies**: upstream (gọi ai) / downstream (ai gọi)
+5. **Tests**: test files liên quan, coverage hiện tại
+
+## Bước 3: Phân tích git history
+
+```bash
+git log --oneline --follow -- [files-found]
+git shortlog -sn -- [files-found]
+git log --oneline --diff-filter=A -- [files-found]
+git show [first-commit] --stat
+```
+
+Xác định: thời điểm tạo, maintainer chính, breaking changes, tech debt (TODO/FIXME).
+
+## Bước 4: Áp dụng tư duy phản biện
+
+Từ framework `.dw/core/THINKING.md`:
+- **Giả định** trong code về input/state/environment
+- **Failure modes** + edge cases
+- **Tech debt** (TODO/FIXME/antipatterns)
+- **Security** (auth, validation, data exposure)
+
+---
+
+## Bước 5: Tạo task docs (v2 format, As-Built flavor)
+
+Tạo thư mục `{paths.tasks}/$ARGUMENTS/` và **2 files** theo template v2 tại `.dw/core/templates/v2/`.
+
+### 5a. spec.md (As-Built)
+
+Đọc template `.dw/core/templates/v2/spec.md`, điền:
+
+**Frontmatter:**
+- `task_id: $ARGUMENTS`
+- `created: [today]`
+- `status: Done` ← đã implement
+- `owner: [main author từ git shortlog]`
+- `depth: retroactive`
+- `related_adr: none`
+- `target_ship: [first-commit-date]`
+
+**Body sections** (lấp bằng findings retroactive):
+
+- **Intent**: 1-2 paragraphs mô tả feature làm gì (dựa trên code)
+- **Why Now**: "As-built documentation — feature pre-dw adoption" + lý do document hóa
+- **Scope → In Scope**: liệt kê component đã implement dưới dạng ST-1, ST-2... với:
+  - Concrete action = mô tả component đã implement
+  - Acceptance = how it was verified (tests / manual check)
+  - Effort = `as-built`
+- **Scope → Out of Scope**: những gì rõ ràng KHÔNG nằm trong feature (suy từ code boundaries)
+- **Risks & Mitigations**: tech debt, antipatterns, security concerns phát hiện
+- **Success Criteria**: current behavior được kiểm chứng bằng gì (tests, prod metrics nếu biết)
+- **Dependencies**: upstream modules/services + downstream consumers
+- **Known Unknowns**: câu hỏi cần human review (verbal decisions không có trong code)
+- **Acceptance**: đánh dấu `[x]` các items đã done (feature đang chạy prod)
+
+**Thêm note trên đầu Intent**:
+```markdown
+> ⚠ As-Built Documentation — Generated retroactively from code + git history.
+> Verbal context (Slack threads, meetings) có thể thiếu. Cần human review bổ sung.
+```
+
+Ghi vào `{paths.tasks}/$ARGUMENTS/spec.md`.
+
+### 5b. tracking.md (As-Built)
+
+Đọc template `.dw/core/templates/v2/tracking.md`, điền:
+
+**Frontmatter:**
+- `task_id: $ARGUMENTS`
+- `started: [first-commit-date từ git]`
+- `last_updated: [today]`
+- `status: Done`
+- `current_phase: Maintained`
+- `blockers: none`
+
+**Body sections:**
+
+- **Status Snapshot**: Phase `Done (pre-dw)` · Next milestone `— (maintained as-is)`
+- **Subtask Progress** table: map các component đã tìm ở Bước 2 thành ST-N với status ✅ Done, Date = commit date đầu tiên của component, Notes = commit SHA hoặc file path
+- **Changelog**: parse git log ra thành entries theo ngày. Format:
+  ```
+  ### YYYY-MM-DD — [commit subject]
+  **Actions taken:** [summary]
+  ```
+- **Handoff Notes**: cho next session/agent:
+  - **Read first:** `spec.md` (as-built) + key files từ bước 2
+  - **Current state:** Done, maintained
+  - **Don't do:** [stable contracts không nên thay đổi]
+  - **Watch out:** [tech debt + gotchas]
+- **Friction Journal**: để trống hoặc nhập tech debt đã ghi nhận từ Bước 4
+- **Agent Debate Log**: bỏ qua (không applicable cho retroactive)
+
+Ghi vào `{paths.tasks}/$ARGUMENTS/tracking.md`.
+
+### 5c. Cập nhật ACTIVE.md
+
+Chạy `dw active` (hoặc `writeActiveIndex`) để regenerate team index.
+
+---
+
+## Bước 6: Báo cáo kết quả
+
+```
+╔══════════════════════════════════════════════════════╗
+║  ✅ dw:retroactive complete: $ARGUMENTS
+╠══════════════════════════════════════════════════════╣
+║  Files khảo sát    : [N files]
+║  Git commits       : [N, từ [date] đến [date]]
+║  Maintainer chính  : [author]
+╠══════════════════════════════════════════════════════╣
+║  Docs đã tạo (v2 format):
+║    {paths.tasks}/$ARGUMENTS/spec.md      (As-Built)
+║    {paths.tasks}/$ARGUMENTS/tracking.md  (Done, maintained)
+╠══════════════════════════════════════════════════════╣
+║  Key findings:
+║  • [Finding 1]
+║  • [Finding 2]
+╠══════════════════════════════════════════════════════╣
+║  Tech debt / warnings:
+║  • [Warning nếu có]
+╠══════════════════════════════════════════════════════╣
+║  Tiếp theo:
+║  → Task liên quan:    /dw:research $ARGUMENTS
+║    (AI đọc spec.md làm foundation)
+║  → Human review:      điền Known Unknowns + Handoff Notes
+╚══════════════════════════════════════════════════════╝
+```
+
+---
+
+## Lưu ý
+
+- **As-built ≠ forward plan**: spec.md mô tả hiện trạng, không phải kế hoạch tương lai.
+- **Best-effort**: AI chỉ thấy code + git — context ẩn (verbal decisions, Slack threads) có thể thiếu. Human review là bắt buộc cho phần `Known Unknowns`.
+- **v2 format**: Chỉ tạo 2 files (`spec.md` + `tracking.md`). Không dùng lại v1 3-file format (`context + plan + progress`) nữa.
+- **Tools khác vẫn đọc được**: `dw active`, `session-init` hook, `/dw:dashboard` đều hỗ trợ v2 format song song với legacy v1.

package/.claude/skills/dw-review/SKILL.md

@@ -1,66 +1,66 @@
----
-name: dw-review
-description: "Review code thay đổi gần đây hoặc cả task. Kiểm tra correctness, security, conventions, test coverage. Tạo báo cáo phân loại Critical/Warning/Suggestion."
-argument-hint: "[task-name | branch | file]"
-context: fork
-agent: reviewer
-allowed-tools:
-  - Read
-  - Grep
-  - Glob
-  - "Bash(git diff *)"
-  - "Bash(git log *)"
-  - "Bash(git show *)"
----
-
-# Code Review
-
-Target: **$ARGUMENTS**
-
-## Đọc Config
-
-Đọc `.dw/config/dw.config.yml` → `paths.tasks`, `workflow.default_depth`.
-
-## Xác Định Scope
-
-- Nếu có argument = task-name: review tất cả commits liên quan đến task
-- Nếu có argument = branch: `git diff main...$ARGUMENTS`
-- Nếu không có argument: `git diff HEAD~1` (commit gần nhất)
-
-## Quy Trình
-
-### 1. Lấy diff
-```bash
-git diff [scope] --name-only   # danh sách files changed
-git diff [scope]                # nội dung thay đổi
-```
-
-### 2. Đọc files liên quan
-Đọc toàn bộ files đã changed để hiểu full context (không chỉ diff).
-
-### 3. Review theo reviewer agent
-
-Agent `reviewer` sẽ kiểm tra:
-- **Correctness**: Logic, edge cases, error handling
-- **Security**: Input validation, auth, data exposure
-- **Performance**: N+1, unnecessary calls, complexity
-- **Tests**: Coverage, test quality
-- **Conventions**: Naming, structure, code style (`.claude/rules/code-style.md`)
-
-### 4. Kiểm tra checklist cụ thể
-
-Nếu có plan file (`{paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md`):
-- Đối chiếu acceptance criteria từng subtask
-- Kiểm tra scope có vượt plan không
-
-### 5. Output
-
-Tạo báo cáo đầy đủ theo format của reviewer agent.
-
-## Sau Review
-
-- Nếu có Critical issues: "Cần fix trước khi merge"
-- Nếu chỉ có Warnings: "Khuyến khích fix, nhưng có thể proceed"
-- Nếu pass: "Approved — có thể chạy `/dw-commit`"
-
-Nếu team có TL: "Gợi ý gửi báo cáo này cho TL để final approve."
+---
+name: dw:review
+description: "Review code thay đổi gần đây hoặc cả task. Kiểm tra correctness, security, conventions, test coverage. Tạo báo cáo phân loại Critical/Warning/Suggestion."
+argument-hint: "[task-name | branch | file]"
+context: fork
+agent: reviewer
+allowed-tools:
+  - Read
+  - Grep
+  - Glob
+  - "Bash(git diff *)"
+  - "Bash(git log *)"
+  - "Bash(git show *)"
+---
+
+# Code Review
+
+Target: **$ARGUMENTS**
+
+## Đọc Config
+
+Đọc `.dw/config/dw.config.yml` → `paths.tasks`, `workflow.default_depth`.
+
+## Xác Định Scope
+
+- Nếu có argument = task-name: review tất cả commits liên quan đến task
+- Nếu có argument = branch: `git diff main...$ARGUMENTS`
+- Nếu không có argument: `git diff HEAD~1` (commit gần nhất)
+
+## Quy Trình
+
+### 1. Lấy diff
+```bash
+git diff [scope] --name-only   # danh sách files changed
+git diff [scope]                # nội dung thay đổi
+```
+
+### 2. Đọc files liên quan
+Đọc toàn bộ files đã changed để hiểu full context (không chỉ diff).
+
+### 3. Review theo reviewer agent
+
+Agent `reviewer` sẽ kiểm tra:
+- **Correctness**: Logic, edge cases, error handling
+- **Security**: Input validation, auth, data exposure
+- **Performance**: N+1, unnecessary calls, complexity
+- **Tests**: Coverage, test quality
+- **Conventions**: Naming, structure, code style (`.claude/rules/code-style.md`)
+
+### 4. Kiểm tra checklist cụ thể
+
+Nếu có plan file (`{paths.tasks}/$ARGUMENTS/$ARGUMENTS-plan.md`):
+- Đối chiếu acceptance criteria từng subtask
+- Kiểm tra scope có vượt plan không
+
+### 5. Output
+
+Tạo báo cáo đầy đủ theo format của reviewer agent.
+
+## Sau Review
+
+- Nếu có Critical issues: "Cần fix trước khi merge"
+- Nếu chỉ có Warnings: "Khuyến khích fix, nhưng có thể proceed"
+- Nếu pass: "Approved — có thể chạy `/dw:commit`"
+
+Nếu team có TL: "Gợi ý gửi báo cáo này cho TL để final approve."