| name | pk-track |
| description | Xử lý inbox execution và cập nhật KR current (tiến độ thực tế). Light: ghi nhận tiến độ KR/action hàng ngày. Deep: review sâu với root cause analysis. Dùng khi user nói 'cập nhật tiến độ', 'xong task X', 'review sâu', 'tại sao chậm', hoặc cần xử lý inbox execution. KHÔNG dùng khi xử lý inbox knowledge (dùng pk-distill) hoặc sửa KR target/mục tiêu/cấu trúc kế hoạch (dùng pk-init hoặc pk-plan). |
PK Track: Track + Review + Inbox Execution
Ensure snapshot (bắt buộc, đầu flow)
- Precondition:
.cockpit/ tồn tại. Thiếu → route pk-init (mode new), KHÔNG nạp gì thêm, dừng.
- Idempotent qua marker: phiên CHƯA có marker
SNAPSHOT_LOADED → tự nạp full theo Snapshot Contract
(../pk-shared/references/snapshot-contract.md) rồi đặt marker SNAPSHOT_LOADED. Đã có marker (vd
harness Phase 1 đã đặt) → skip, không đọc lại.
Ghi progress fields, log, archive. KHÔNG sửa cấu trúc (delegate sang pk-init/pk-plan).
Modes
| Mode | Trigger | Mô tả |
|---|
light | Daily tracking | Cập nhật KR/action progress |
deep | Review sâu, at-risk | Root cause + đề xuất điều chỉnh |
inbox-only | Xử lý inbox execution | Chỉ inbox domain=execution |
SOT quyền ghi
| File | Fields |
|---|
| objective.md | KR.current, KI.current |
| plan.md | counters, last_track_date, last_review_date, re-render Roadmap (view dẫn xuất, sau khi ghi actions/) |
| actions/*.md | status, completed_date, ## Output/Deliverable |
| log/*.md | Append entries |
| inbox/*.md (domain=execution) | Status transition |
| archive/actions/ | Move done actions |
| archive/inbox/ | Move items processed/discarded |
Subset của ../pk-shared/references/sot-ownership.md.
KHÔNG được sửa: Objective text, KR target, action title/due_date/deps. Đề xuất → delegate pk-init/pk-plan (pre-confirmed).
Nguyên tắc
- Dashboard TRƯỚC khi hỏi update.
- Confirm trước ghi. <= 2 field → 1 dòng, >= 3 → bảng.
- Metrics:
../pk-shared/references/metrics.md (canonical).
- Append-only log.
- Cuối flow đề xuất next action.
Flow: mode light
Phase 1: Snapshot + Dashboard
Dùng pk-analyze (focus: track) → thu analysis.
Phase 2: Tương tác update
Hỏi user: KR.current? Action status?
Phase 3: Confirm
Bảng thay đổi. Trước khi trình bảng confirm, áp Quality Gate (../pk-shared/references/quality-gate.md) cho input số liệu KR/KI current từ user (3 câu nội bộ: đủ cụ thể, giả định ẩn, mâu thuẫn). User confirm.
Phase 4: Ghi
- Đọc body action hiện tại trước khi ghi
## Output/Deliverable (bất biến canonical: ../pk-shared/references/snapshot-contract.md, mục "Bất biến đọc body trước khi ghi body"). Snapshot chỉ có frontmatter; không đọc body trước = rủi ro ghi đè.
- Cập nhật KR/KI current trong objective.md. Ghi xong, bản
objective.md nạp qua khối @ của AGENTS.md hết hiệu lực — skill chạy sau (vd pk-analyze tính lại metrics) phải đọc lại từ disk. Luật canonical: ../pk-shared/references/snapshot-contract.md, mục "Dedup 6 file khối @".
- Cập nhật action status trong actions/*.md
- Tính KR Status auto-compute (metrics.md)
- Archive done actions (schemas.md archive rules)
- Cập nhật plan.md counters + last_track_date
- Re-render Roadmap
Phase 5: Xử lý inbox execution (nếu có)
Đọc inbox domain=execution, status=pending. Trình đề xuất, user duyệt rồi mới thực hiện. Mỗi item:
| Inbox type | Xử lý |
|---|
action | Delegate pk-plan pre_confirmed (user đã duyệt trong flow track; theo Delegate Protocol tại ../pk-shared/references/cross-call-rules.md) |
blocker | Tự ghi (sửa action.status = blocked) |
resource | Hỏi user: link vào action notes hoặc đổi domain=knowledge |
thought | Hỏi user: chuyển thành action, đổi domain, hoặc discard |
resource đổi domain=knowledge: chỉ set field domain: knowledge ngay trong file, giữ nguyên file trong inbox/. KHÔNG set status: processed, KHÔNG move sang archive. pk-distill sẽ tự nhặt item này khi quét inbox/ domain=knowledge, status=pending.
Item có related_inbox (cặp domain=both): khi xử lý item execution, đọc related_inbox để biết item cặp (domain=knowledge). Thông báo cho user biết item cặp cần được pk-distill xử lý nốt, tránh bỏ rơi nửa cặp.
Set status: processed hoặc discarded. Move item sang archive/inbox/ (TRỪ item resource vừa đổi sang domain=knowledge: không move, không set processed).
Phase 6: Log + Tóm tắt
Append log. Đề xuất next action. Gợi ý rút bài học (pk-reflect) nếu flow có thực chất VÀ chạy standalone. Khi chạy qua pk-harness thì bỏ qua, harness Phase 3 đảm nhiệm.
Flow: mode deep
Phase 1: Deep analysis
pk-analyze deep: đọc toàn bộ + log + root cause (>= 3 "tại sao?").
Phase 2: Trình bày + đề xuất
Root cause mỗi issue + đề xuất điều chỉnh (cấu trúc + progress).
Phase 3: All-changes confirm
Gom proposals → trình user duyệt batch.
Phase 4: Ghi progress
Cập nhật KR/action (giống light Phase 4). Ngoài ra, deep ghi thêm last_review_date vào plan.md (light chỉ ghi last_track_date, không ghi last_review_date).
Phase 5: Delegate thay đổi cấu trúc
Với mỗi thay đổi cấu trúc đã confirm, gọi pk-init/pk-plan với pre_confirmed: true (../pk-shared/references/cross-call-rules.md delegate protocol).
Phase 6: Phát hiện tri thức mới
Deep review phát hiện pattern/lesson → gọi pk-capture (cross-call lớp 2 → lớp 3) tạo inbox domain=knowledge. pk-track KHÔNG tự ghi vào knowledge (giữ SOT).
Phase 7: Log review
Ghi log type=review.
Flow: mode inbox-only
- Đọc inbox
domain=execution, status=pending
- Cảnh báo items > 30 ngày
- Gợi ý xử lý per item
- User quyết định
- Xử lý (blocker tự ghi; action và thought đã duyệt thành action: delegate pk-plan pre_confirmed; resource: hỏi user)
- Move item đã xử lý sang
archive/inbox/
- Báo cáo
Tích hợp: Track → Consult
Khi phát hiện action có skill/workflow liên quan (từ notes hoặc keyword match):
- Gọi pk-consult mode run (cross-call lớp 2 → lớp 3)
- Kết quả quay về cập nhật action status/output
Quy tắc cứng
- KHÔNG sửa cấu trúc action (title, due_date, deps). Delegate.
- KHÔNG ghi vào knowledge/skills/workflows. Gọi pk-capture nếu phát hiện tri thức.
- Confirm trước mọi ghi.
- Archive rules theo
../pk-shared/references/schemas.md.
- Verify sequence trước khi gán số thứ tự. Khi gặp counter/sequence nghiệp vụ mà pk-track ghi qua KR/KI current (buổi coaching, sprint, version), kiểm tra gap giữa records hiện có. Nếu có khoảng trống (ví dụ: B3 → B5 thiếu B4), hỏi user xác nhận trước khi gán số tiếp. (Verify sequence cho action ID là việc của pk-plan, nơi sinh AXXX.)
