Tạo retrospective dựa trên bằng chứng với ak:retro

Dùng ak:retro để biến một giai đoạn repository history đã xác định thành engineering retrospective có căn cứ. Skill thu thập Git evidence, hiển thị công thức cho derived indicator, kiểm tra plan file gần đây và lưu recommendation gắn với dữ liệu quan sát được thay vì narrative được tạo ra.

Chọn ak:retro cho bằng chứng lịch sử

Dùng ak:retro khi

• Bạn cần sprint, monthly hoặc quarterly engineering review.
• Bạn muốn commit cadence, file hotspot, change volume hoặc test-change proxy.
• Bạn cần comparison với giai đoạn trước hoặc breakdown theo author.
• Bạn muốn plan-checkbox evidence cùng repository activity.

Chọn workflow khác khi

• Bạn cần live project status thay vì historical review. Dùng ak:project-management.
• Bạn cần chẩn đoán vì sao một thay đổi cụ thể thất bại. Dùng ak:debug.
• Bạn cần kết luận về productivity, quality hoặc individual performance mà Git activity không hỗ trợ. Hãy thêm product và team evidence phù hợp trước.
• Bạn muốn workflow đổi source code, commit, push hoặc deploy.

Chuẩn bị nguồn bằng chứng

• Hoàn thành Làm quen và xác nhận Engineer Kit đã được cài cho đúng runtime cùng scope bạn đang dùng.
• Mở Git repository có history bạn muốn phân tích.
• Chọn timeframe được hỗ trợ và xác nhận time boundary cục bộ của repository.
• Bảo đảm git và Python khả dụng cho metrics collector đi kèm.
• Chỉ làm gh khả dụng và authenticated nếu muốn optional issue data.
• Review privacy của tên author trước khi yêu cầu output --team.

Chọn timeframe và report shape

Với sprint, Skill hỏi start date khi không thể suy ra từ Git tag. Date pair rõ ràng phù hợp hơn khi calendar boundary quan trọng.

Kiểm soát editorial visual trong HTML

HTML report mặc định thêm một editorial visual layer. Trước khi render, Skill đọc:

ak config prefs resolve --json | jq '.prefs.visual'

Preference key đã resolve dùng camelCase, nên diagram_design xuất hiện dưới dạng diagramDesign. Khi được bật, .prefs.visual.diagramDesign.enabled hoặc .prefs.visual.antv.enabled có thể chọn các cách trình bày sau:

• Timeline của commit và pull request dùng diagram-design Timeline hoặc AntV Infographic timeline-*.
• Plan completion dùng AntV Infographic CircularProgress.
• File hotspot dùng SVG bar được viết thủ công hoặc diagram-design Bar khi report đã có editorial diagram.
• Team velocity dùng Chart.js radar hiện có hoặc diagram-design Radar.

Panel AntV được bật tải từ jsDelivr khi report được mở. Dùng --no-antv khi lần chạy phải tránh dependency CDN đó, --no-diagram-design để tắt treatment này hoặc --no-editorial-visuals để tắt toàn bộ visual layer bổ sung. Output --format md mặc định không đổi.

/ak:retro 2026-07-15:2026-07-28 --compare --team --format md

/ak:retro 2026-07-15:2026-07-28 --compare --team --format md

$ak:retro 2026-07-15:2026-07-28 --compare --team --format md

Hiểu điều gì xảy ra trong một lần chạy

1. Skill resolve date. Skill chuyển timeframe thành SINCE cùng UNTIL; comparison mode còn tạo preceding window có độ dài bằng nhau.
2. Skill chụp một Git snapshot cho mỗi kỳ. scripts/collect-git-metrics.py đi kèm đọc một history snapshot có giới hạn giữa các ISO timestamp tường minh, gồm cả timezone, và trả về JSON. Tổng số, activity day, author, commit-subject type, file hotspot, line change và test-file change đều lấy từ snapshot đó. Git command thất bại là evidence không khả dụng, không phải activity bằng 0.
3. Skill tính derived indicator. Report hiển thị công thức commit frequency, active-day ratio, test-to-code change ratio cùng churn thay vì đưa ra opaque score.
4. Skill kiểm tra optional issue evidence. Khi gh khả dụng, Skill có thể đếm issue opened và closed trong kỳ, tách riêng khỏi plan completion; nếu không, issue metric giữ N/A.
5. Skill kiểm tra plan được chạm trong kỳ. Skill dùng changed path của snapshot dưới plan root để tìm tracked plan, rồi đọc trạng thái checkbox hiện tại. Trạng thái checklist hiện tại được báo cáo tách khỏi evidence hoàn tất trong lịch sử, và thời gian sửa tệp không được coi là Git history.
6. Skill ghi report. Markdown vào plans/reports/retro-{YYMMDD}-{slug}.md; HTML dùng cùng tên với .html và inline CSS. Panel AntV được bật vẫn giữ dependency jsDelivr đã mô tả ở trên.
7. Skill giải thích finding. Kết quả gồm hai đến bốn factual highlight cùng ba đến năm recommendation dựa trên metric được nêu.

Report được yêu cầu giữ dưới 200 dòng; nếu evidence cần nhiều hơn, Skill có thể chia thành nhiều report file.

Diễn giải indicator thận trọng

• Report giữ provenance của collector: revision HEAD đã pin, cờ shallow-history, ISO bound tường minh, cùng policy về date, diff và path. Git lọc theo committer date, và activity day giữ offset của từng committer timestamp thay vì một reporting timezone chung.
• Shallow clone có thể thiếu activity. Binary change không có LOC dạng số và được đếm riêng khỏi line total.
• Commit count, LOC và author activity là tín hiệu mô tả, không phải năng suất cá nhân hay chất lượng code.
• Test-to-code ratio đo changed filename khớp test pattern, không đo test coverage hoặc test quality.
• Conventional-commit distribution chỉ có ý nghĩa khi subject theo convention đó.
• Churn dùng (added + removed) / max(net, 1); negative hoặc near-zero net change có thể làm value khó diễn giải.
• Author grouping dùng tên Git author và có thể tách một người thành nhiều identity hoặc expose personal data trong report.
• Issue data cần command gh authenticated và có thể tạo read-only network request tới GitHub. Nếu unavailable, ghi N/A thay vì hỏi secret hay tạo số.

Giữ effect và approval có giới hạn

• Source file vẫn read-only, nhưng workflow ghi retrospective artifact dưới plans/reports/.
• Shell cùng Git process chạy local và có thể scan lượng history lớn; repository lớn hoặc period dài có thể lâu hơn default bảy ngày.
• HTML output dùng inline CSS. Khi panel AntV được bật, việc mở report có thể fetch runtime đã pin từ jsDelivr; dùng visual opt-out ở trên khi dependency network đó không chấp nhận được.
• Skill không nêu paid provider. Mọi GitHub access kế thừa account, permission cùng service term hiện có của user.
• Commit, push, issue mutation, publication, sharing cùng deployment cần approval riêng.

Xác minh kết quả

Một lần chạy hoàn tất nên cung cấp:

• Exact period date, generation date, repository identity cùng active-author count.
• Raw velocity và code-health value với công thức cho derived metric.
• Optional delta chỉ khi chọn --compare.
• Optional author row chỉ khi chọn --team.
• Hotspot cùng plan evidence trace được tới repository path và checkbox.
• N/A ở mọi nơi required source unavailable.
• Saved artifact path cùng recommendation trích actual finding.

Chạy lại một hoặc hai underlying Git count để spot check, kiểm tra report diff và xác nhận source file không đổi trước khi share retrospective.

Xử lý sự cố hoặc tiếp tục

Biết các giới hạn hiện tại

• Report không gồm product outcome, review quality, incident data, deployment frequency hoặc uncommitted work trừ khi bạn cung cấp evidence riêng.
• Plan evidence phản ánh trạng thái checklist hiện tại của plan được chạm trong kỳ, không phải bản ghi lịch sử về thời điểm mỗi task hoàn tất.
• Editorial visual chỉ áp dụng cho --format html; --format md vẫn không đổi.