SDD Board

VS Code extension for the Spec-Driven Development workflow. Version hiện tại: 1.3.0.

Two panels in one extension:

📋 Review Board — visual UI để review findings do AI sinh ra từ /refine-prd, /review-context, /review-tech-docs
📊 Living Documentation — dashboard traceability toàn project, đọc từ .trace-mirror/ hoặc .trace/

Installation

code --install-extension EducaCorp.sdd-board

Hoặc VS Code → Ctrl+Shift+P → "Extensions: Install from Marketplace" → search SDD Board.

VS Code tự động cập nhật khi có version mới.

Panel 1 — Review Board

Cách dùng

Bước 1 — Chạy một review command trong Claude Code

/refine-prd          specs/prd/payment/create-invoice.md
/review-context      specs/prd/payment/create-invoice.md
/review-context      specs/bdd/payment/PAY-UC01.feature
/review-tech-docs    tech-docs/payment/PAY-UC01-tech-design.md

Claude phân tích và ghi file vào .agent/review/:

Command	Findings file
`/refine-prd`	`{prd-slug}-findings.yaml`
`/review-context` (PRD)	`{prd-slug}-review-context-findings.yaml`
`/review-context` (BDD)	`{uc-id}-{platform}-review-bdd-findings.yaml`
`/review-tech-docs`	`{TICKET-ID}-tech-review-findings.yaml`
`/qc-analyze`	`{TICKET-ID}-qa-findings.yaml` — read-only, xem QC findings

Extension quét mọi thư mục .agent/review/ trong workspace — kể cả trong git submodule — nên umbrella repo cũng thấy findings của từng service.

Bước 2 — Mở Review Panel

Sidebar (khuyến nghị): Click icon trên Activity Bar → danh sách findings files → click file. Mỗi dòng hiện {pending} pending / {total}, xong hết thì đổi thành ✅ done (n)
Right-click: Right-click vào file *-findings.yaml trong Explorer → "Open Review Board"
Command Palette: Ctrl+Shift+P → "SDD Board: Open Review Board" — nhiều file thì hiện QuickPick để chọn

VS Code tự hiện thông báo "Mở ngay?" khi file findings vừa được tạo.

Bước 3 — Review từng finding

Mỗi finding hiển thị:

Severity: nhãn màu CRITICAL / MAJOR / MINOR
📍 Section — bấm vào để mở tài liệu nguồn ở cột bên và nhảy tới đúng vị trí. Bấm vào phần trích dẫn cũng vậy
Badge: ⚡ auto-fix (AI có thể tự sửa) / 👤 human (cần quyết định của người)
ID: check_id (P1, B2, T3) hoặc lens (QA, DEV, SA, PO) — lens chỉ hiện ở tab All; /qc-analyze thêm gap_ref trỏ về hàng trong DOC_GAP.md
⚠️ Nếu chốt phương án này — resolution_edge_cases của /refine-prd: edge case / side-effect mà chính suggestion này đẻ ra. Advisory, PO đọc trước khi Accept
Issue / Suggestion

Danh sách sắp xếp pending → deferred → đã xử lý, trong mỗi nhóm là critical → major → minor.

Bấm để xử lý:

Nút	Kết quả
✓ Accept	Chấp nhận finding
✎ Modify	Chấp nhận có chỉnh sửa — nhập note vào modal; note được ghi luôn vào `suggestion` để `--resume` apply đúng nguyên văn
⏸ Defer	Để sau — không chặn `--resume`
✗ Reject	Từ chối — nhập lý do vào modal
💬 Cần bàn	`needs_discussion` — chưa ngã ngũ. `--resume` bỏ qua finding này (kèm cảnh báo) tới khi bạn chốt, nên nó không tính là đã review
↩ Change	Hoàn tác về pending

Finding status: applied (đã được --resume / --fix ghi vào tài liệu nguồn) hiện badge 🔒 và không đổi được nữa — đảo ngược nó ở đây sẽ khiến file findings mâu thuẫn với nội dung đã nằm trong PRD.

Lọc nhanh bằng Severity / Status dropdown ở toolbar trên, hoặc ô Search (issue / suggestion / section).

Khi mọi finding đã có quyết định (accepted / modified / rejected / deferred / applied — needs_discussion không tính), extension ghi .agent/review/{slug}-review-log.yaml (reviewed_at, reviewer, source_file, summary theo từng status, danh sách decisions) và hiện thông báo kèm nút Open Report.

Extension không ghi status ở cấp file. Vòng đời pending_review → applied | partially_applied thuộc về --resume/--fix của framework; Board chỉ ghi trạng thái từng finding.

Bước 4 — Apply

Bấm "⚡ Apply to PRD" ở thanh dưới. Extension mở terminal Apply Findings và tự chọn lệnh đúng theo review_type trong findings file:

Workflow	Terminal command
`refine-prd`	`claude "/refine-prd {source-file} --resume"`
`review-context` (prd / bdd)	`claude "/review-context --resume {source-file}"`
`review-tech-docs`	`claude "/review-tech-docs --resume {tech-doc}"`
`qc-analyze`	nút bị khoá — xem dưới

Còn finding needs_discussion thì extension cảnh báo trước khi mở terminal: --resume sẽ bỏ qua chúng.

QC findings (`/qc-analyze`) — read-only

/qc-analyze ghi {TICKET-ID}-qa-findings.yaml bằng đúng schema của /refine-prd (mọi finding lens: QA), nên Board mở và review bình thường. Nhưng nút Apply bị khoá kèm banner giải thích: gap của trạm này phát hiện sau khi BDD đã approved và tech-doc (kèm hợp đồng test-id) đã chốt — code có thể đang được sinh từ chúng ở luồng song song, sổ kết quả kiểm thử neo vào scenario của BDD đó. Tự sửa PRD lúc này là sửa sau lưng cả dây chuyền.

Đường đúng: /report-bug (spec-defect thật) hoặc /propose-scenario (thiếu độ phủ).

Nút ↻ cạnh mỗi lens tab chạy lại toàn bộ review trong terminal Re-run Review (/refine-prd … --full, /review-context … --full, /review-tech-docs …, /qc-analyze {TICKET-ID} {platform}). Framework fan-out cả bộ lăng kính trong một lượt rồi hội tụ ở orchestrator, nên không re-run riêng một lăng kính được.

Quick-fix path (không qua Review Board)

Dành cho dev muốn apply nhanh tất cả auto_fixable findings:

/review-context --fix specs/bdd/payment/PAY-UC01.feature

AI apply ngay, bỏ qua Review Board, chỉ để lại các finding cần quyết định của người.

Settings

Setting	Mặc định	Ý nghĩa
`sddBoard.reviewer`	`reviewer`	Tên người review, ghi vào `{slug}-review-log.yaml`. Đọc lúc runtime — đổi xong là lần ghi report tiếp theo dùng ngay, không phải cài lại / build lại extension
`sddBoard.clarifyPrompt`	(prompt no-tech)	⚠️ Hiện không có tác dụng — nút 💬 Giải thích đã bị tắt từ bản 1.1.0. Setting còn khai báo để giữ giá trị team đã cấu hình, chờ tính năng bật lại

Thứ tự ưu tiên: Workspace (.vscode/settings.json trong repo project) > User > default. File mẫu copy được: sample/.vscode/settings.json.

Tính năng

Tính năng	Mô tả
Multi-command	Hỗ trợ findings từ `/refine-prd`, `/review-context`, `/review-tech-docs`, `/qc-analyze`
Lens tabs	All / QA / DEV / SA / PO (refine-prd — 4 lăng kính) hoặc PRD / BDD / TECH (review-context / review-tech-docs, theo prefix của check_id). Lens rỗng thì không hiện tab; file `/qc-analyze` chỉ có tab QA
Edge-case advisory	`resolution_edge_cases` hiện ngay trên card và trong modal Modify — PO thấy hệ luỵ trước khi Accept
Jump to source	Bấm 📍 section hoặc câu trích dẫn → mở file nguồn cạnh panel, nhảy tới dòng: khớp `quote` → heading `uc_id` → heading `section` → đầu file
auto_fixable badge	`⚡ auto-fix` / `👤 human` trên mỗi finding
check_id label	P1, B2, T3 hiển thị khi dùng review-context / review-tech-docs
Progress bar	Thanh tiến độ % đã review
Filter + Search	Severity, Status dropdown + tìm kiếm toàn văn qua issue / suggestion / section
Smart Apply	Tự chọn `--resume` command đúng theo loại findings file
Lossless round-trip	Ghi trạng thái ngay lên file YAML gốc, giữ nguyên mọi field khác (`prd_version`, `applied_to_version`, `sign_off`, `domain`…) — những field điều khiển logic full-vs-delta và sign-off gate của lần chạy command sau
Auto-detect	Tự tìm findings files trong mọi `.agent/review/`, kể cả submodule
File watcher	Tự refresh sidebar khi findings file được tạo / sửa / xoá

Panel 2 — Living Documentation

Dashboard traceability health của toàn project, đọc từ .trace-mirror/, .living-docs/ hoặc .trace/.

Cách mở

Ctrl+Shift+P → "SDD Board: Open Living Documentation"
Sidebar: Activity Bar → SDD Board → view Living Docs → nút Open Dashboard
Right-click một file .tsv trong Explorer → "SDD Board: Open Living Documentation"

Dashboard

13 ô thống kê, tính trên toàn bộ scenario rows đọc được:

Ô	Nội dung
PRDs	tổng số PRD · n approved
Use Cases	tổng số UC · n approved / n draft
Scenarios	tổng SC trong scope (đã loại ORPHANED) · số SC theo platform (`web 12 · app 8`)
Code Coverage	% SC có `implemented_by` — xanh ≥ 90%, cam ≥ 70%, đỏ dưới đó
Test Coverage	% SC có test
Drift	SC có `status = DRIFT`
Untracked	SC chưa có code
Gap	SC có code nhưng thiếu test
Orphaned	🔴 code còn, spec đã xoá — không nằm trong mẫu số Scenarios
Tech Docs	số file `-tech-design.md` trong các thư mục `tech-docs/`
QC Pass	QC pass · n fail / skip / not run
Dev Self-Check	`dev_selftest` pass · n fail / not run
Waiting	SC đang chờ dev + chờ PO (`qc_owner`)

Cảnh báo audit

Ngay dưới các ô thống kê, panel hiện các cờ mà /validate-traces ghi vào trace-report.json (summary.*_count + issues.*). Dòng đầu là cổng tạo PR: đỏ khi còn cờ 🔴, xanh khi sạch, kèm thời điểm audit. Nếu biên bản chỉ phủ một domain / PRD / UC (scope.kind ≠ all), panel ghi rõ chưa phải audit đầy đủ.

Mức	Cờ	Ý nghĩa
🔴 chặn PR	`ORPHANED` · `TRACE_ORPHAN` · `SEAM_UNWIRED` · `STUB_UNRESOLVED`	Code đang hỏng theo kiểu build xanh, test xanh vẫn không lộ ra. Mặc định mở sẵn
🟠 cần xử lý	`LEDGER_BEHIND_CODE` · `PRD_UNTRACKED_EDIT` · `PRD_DRIFT` · `BDD_DRIFT` · `TECHDOC_DRIFT` · `FE_TECHDOC_DRIFT` · `TECHDOC_STALE_VS_BDD` · `DESIGNSPEC_DRIFT` · `DESIGNSPEC_STALE_VS_BDD` · `SERVICE_UNROUTED`	Code/tài liệu chưa theo kịp spec — không chặn PR, nhưng xử lý trước khi coi tính năng là xong. `LEDGER_BEHIND_CODE` nên xử lý đầu tiên: chưa xử lý thì số UNTRACKED/GAP chưa phải số thật
ⓘ không phải lỗi	`PRD_STALE_REF` · `TECHDOC_STALE_REF` · `SEAM_PENDING` · `STUB_PENDING`	Nhãn version cũ, hoặc đang chờ UC sở hữu được gen

Bấm vào một cờ để xem từng mục kèm lệnh xử lý (fix) do framework ghi. DRIFT / GAP / UNTRACKED không lặp lại ở đây vì bảng per-scenario đã hiện từng dòng. Khi chỉ đọc được TSV thô (chưa có trace-report.json), panel nhắc chạy /validate-traces — cờ audit được tính lúc audit, không nằm trong sổ TSV.

Drill down: PRD → Use Case → bảng per-scenario

SC	Platform	Title	Spec	Gen	Code	Tests	QC	Waiting	Status
PAY-UC01-SC1	app	Happy path	1.2	1.2	✓	1 class	—	—	✅ OK
PAY-UC01-SC1	web	Happy path	1.2	1.2	✓	2 class	✅ pass	—	✅ OK
PAY-UC01-SC2	web	Refund	1.3	1.2	✓	1 class	🔴 fail	dev	⚠️ DRIFT

Hover Code để xem file implement, hover Waiting để xem qc_blocked_by.

Platform — sc_id chỉ độc nhất trong (UC × platform): mỗi platform đánh SC từ 1, nên PAY-UC01-SC1 của web và của app là hai scenario khác nhau. Panel đọc platform từ trace-report.json hoặc từ tên sổ {UC-ID}-{platform}.tsv, xếp các SC cùng platform liền nhau. Report sinh trước khi framework thêm field này hiện —.

Status badges:

✅ OK — spec ver = gen ver, code + tests tồn tại
⚠️ DRIFT — spec ver ≠ gen ver (scenario đã sửa, code chưa update)
🔴 GAP — code tồn tại nhưng chưa có tests
UNTRACKED — chưa có code implement
🔴 ORPHANED — code còn nhưng scenario đã bị xoá khỏi .feature. Cờ chặn PR; không tính vào mẫu số Scenarios (nó không còn là scope) nên có ô thống kê riêng. Xử lý: xoá code + test, hoặc đưa scenario trở lại

Tính năng:

Filter theo PRD status (All / Approved / Draft / Other)
Search theo UC/SC ID, title hoặc platform
Filter theo status (OK / DRIFT / GAP / UNTRACKED) — ORPHANED vẫn hiện ở "All statuses"
Live reload khi .trace/, .trace-mirror/ hoặc .living-docs/ thay đổi

Data source — thứ tự ưu tiên

#	Nguồn	Khi nào
1	`.trace-mirror/trace-report.json`	Framework ≥ 0.4.3. Mirror sinh từ report đã gộp nên phủ mọi service → dùng một mình nó
2	`.living-docs/trace-report.json`	Umbrella + `spec_source`, mở thẳng spec repo — report đã gộp, dùng một mình nó
3	`.trace/trace-report.json`	Sổ gốc mount trong workspace này, hoặc mirror của bản < 0.4.3. Merge nhiều store, bỏ qua report trùng nội dung
4	`.trace/{domain}/{prd-slug}/{UC-ID}-{platform}.tsv`, rồi `.trace-mirror/{UC-ID}-{platform}.tsv`	Chưa có report — parse TSV thô (bỏ qua `_seams.tsv`). Mirror giữa hai lần `/sync` chỉ có TSV vừa copy, nên vẫn được đọc; SC đã thấy (theo `{sc_id, platform}`) không cộng lần hai

Quét đệ quy tới độ sâu 8, bỏ qua node_modules, .git, out, dist, build, target, vendor… nên tìm được cả store nằm trong submodule. Hai cột mới của framework 0.4.3 — service (đội/submodule sở hữu SC) và design_spec_version (chỉ FE/App) — được đọc từ cả JSON lẫn TSV; TSV cũ thiếu cột thì về —.

Dữ liệu được ghi bởi /generate-bdd, /generate-code, /dev-gen-test; cập nhật bởi /validate-traces.

Vì sao đọc CẢ HAI tên. SDD Framework ≥ 0.4.3 tách sổ gốc khỏi bản sao:

Path Vai trò Git

.trace/ authoritative — .tsv + trace-history.jsonl, không regenerate được phải commit

.trace-mirror/ bản sao để panel chạy được ở workspace không chứa sổ gốc gitignore

Trước 0.4.3 cả hai cùng tên .trace — chính va chạm đó là lý do framework đổi tên (một luật gitignore viết theo tên có thể xoá sạch sổ gốc). Panel đọc cả hai nên chạy đúng với mọi phiên bản framework, không cần phát hành đồng bộ.

Mirror thắng tuyệt đối khi có mặt — nếu đọc thêm cả sổ mà nó mirror thì mọi scenario bị đếm hai lần, làm phồng tổng số, mẫu số coverage, và mọi con số drift/gap. Với workspace < 0.4.3 (cả hai cùng tên) panel khử trùng bằng cách so nội dung report.

Yêu cầu

VS Code 1.85.0 trở lên
Plugin @educa-corp/sdd-framework đã cài trong Claude Code (npx @educa-corp/sdd-framework --init)
Living Documentation cần một .trace-mirror/, .living-docs/ hoặc .trace/ trong workspace; Review Board cần .agent/review/*-findings.yaml

Uninstall

code --uninstall-extension EducaCorp.sdd-board

Liên quan

@educa-corp/sdd-framework — Claude Code plugin chứa toàn bộ workflow commands

SDD Board

Educa Corp

SDD Board

Installation

Panel 1 — Review Board

Cách dùng

QC findings (/qc-analyze) — read-only

Quick-fix path (không qua Review Board)

Settings

Tính năng

Panel 2 — Living Documentation

Cách mở

Dashboard

Cảnh báo audit

Data source — thứ tự ưu tiên

Yêu cầu

Uninstall

Liên quan

QC findings (`/qc-analyze`) — read-only