pk-capture

name

pk-capture

description

Ghi nhanh 1 mẩu rời (ý tưởng, bài học, task) vào inbox. Tự phân loại execution hay knowledge. Dùng khi user nói 'ghi lại', 'note', 'nhớ cái này', 'lưu bài học', 'thêm vào inbox', 'ghi chú', hoặc bất kỳ lúc nào cần bắt một mẩu thông tin nhanh mà chưa cần xử lý ngay. Mode auto: tự chạy khi mạch việc hoàn tất theo quy tắc AGENTS.md, ghi không hỏi. KHÔNG dùng khi cần quét cả phiên làm việc (dùng pk-reflect) hoặc đúc kết cả inbox (dùng pk-distill).

PK Capture: Ghi nhanh vào inbox thống nhất

Chạy inline. Phân loại type + domain, ghi inbox/. CHỈ ghi inbox/, raw/ và append log/. KHÔNG ghi thẳng vào actions, knowledge, skills, workflows.

Ensure snapshot (bắt buộc, đầu flow)

1. Precondition: .cockpit/ tồn tại. Thiếu → route pk-init (mode new), KHÔNG nạp gì thêm, dừng.
2. 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.
3. Ngoại lệ mode auto: dùng snapshot rút gọn theo ../pk-shared/references/snapshot-contract.md (mục "Snapshot rút gọn (CHỈ pk-capture mode auto)") — nạp delta tối thiểu, KHÔNG đặt marker SNAPSHOT_LOADED. Chỉ mode auto; các mode khác giữ full.

Tiêu chí phân loại

Phần tiêu chí domain trích từ ../pk-shared/references/schemas.md. Khi lệch, schemas.md thắng.

Type

Type	Tín hiệu	Domain
action	Động từ hành động, có output	execution
blocker	"không thể", "đang chờ", "bị kẹt"	execution
resource	Tool/tài liệu mới	hỏi user
thought	Ý tưởng mở, chưa rõ scope	hỏi user
decision	"quyết định", "chọn X thay Y"	knowledge
pattern	Cách giải quyết lặp lại	knowledge
troubleshooting	"lỗi", "fix", "root cause"	knowledge
concept	Thuật ngữ, định nghĩa	knowledge
lesson	"bài học", "rút kinh nghiệm", kỳ vọng lệch thực tế	knowledge
candidate-skill	Thao tác cụ thể, tái dùng	knowledge
candidate-workflow	Chuỗi bước, quy trình	knowledge

Domain tự động

• action, blocker → domain=execution
• decision, pattern, concept, troubleshooting, lesson, candidate-skill, candidate-workflow → domain=knowledge
• resource, thought → hỏi user

domain=both

Tiêu chí phát hiện (canonical: ../pk-shared/references/schemas.md, mục "domain=both"): item là domain=both khi CÓ ĐỒNG THỜI (a) động từ hành động có output (tính execution) VÀ (b) tri thức tái dùng được (tính knowledge). Thiếu một trong hai thì chọn domain duy nhất phù hợp, không tách.

Khi xác nhận domain=both: tách ngay thành 2 items riêng biệt, link qua related_inbox. Item execution focus action/status. Item knowledge focus nội dung tri thức.

Hợp đồng 2 chiều: ghi related_inbox ở CẢ HAI item (item A điền tên file của item B, item B điền tên file của item A). Không để 1 chiều.

Chế độ capture

1. Từ cuộc trao đổi (mặc định)

Quét conversation history. Tìm khoảnh khắc có tín hiệu knowhow hoặc action item.

2. Từ nguồn ngoài

User cung cấp file/link. Đọc, áp dụng cùng tiêu chí. Nguồn lớn (>500 dòng hoặc >= 3 file): xem references/batch-ingest.md.

3. Từ phiên reflect

pk-reflect bàn giao xong gọi flow này từ Bước 2 (trình candidates), với captured_from: reflect-light hoặc reflect-deep (xem Handoff Protocol trong ../pk-shared/references/cross-call-rules.md).

4. Auto (ambient)

• Kích hoạt: từ quy tắc ambient trong AGENTS.md block (### Tự capture khi mạch việc hoàn tất) khi một mạch việc đáng kể vừa xong và đã verify — hoặc harness route tương đương ("capture auto"). Đây là entry point ngoài, không phải cross-call (xem ../pk-shared/references/cross-call-rules.md, mục "Ambient entry").
• Ensure snapshot: dùng snapshot rút gọn (canonical: ../pk-shared/references/snapshot-contract.md, mục "Snapshot rút gọn (CHỈ pk-capture mode auto)"). KHÔNG chép, trỏ về.
• Nguồn quét: CHỈ mạch việc vừa hoàn tất (không quét cả conversation — khác mode 1).
• Không hỏi: ghi thẳng theo tiêu chí bắt-thừa rồi báo lại 1 dòng (inbox là vùng đệm — user sửa/xoá được; distill là cổng lọc). Flow riêng bên dưới ("Flow mode auto").

Flow

Bước 1: Quét nguồn

Đọc nguồn, lọc phần có tín hiệu.

Bước 2: Trình danh sách candidates

Mỗi item: emoji + type + domain + tóm tắt 1-2 câu.

1. 📋 [execution] action: Viết test cho module auth
2. 🔧 [knowledge] pattern: Retry với exponential backoff + jitter
3. 🎓 [knowledge] lesson: Estimate thiếu buffer kiểm thử

Bước 3: User duyệt

Giữ / sửa / bỏ. Cho phép thay type, domain, thêm item bỏ sót.

Bước 4: Ghi vào inbox

1. Ghi raw vào raw/YYYY-MM-DD-slug.md (nguyên văn nguồn, immutable)
2. Tạo inbox/YYYY-MM-DD-HHmm-slug.md theo schema (../pk-shared/references/schemas.md)
3. Set source_file: raw/YYYY-MM-DD-slug.md

Khi không có objective: related_kr và related_action để null, domain mặc định = knowledge.

Bước 5: Ghi log

Append log/YYYY-MM-DD.md:

---
timestamp: YYYY-MM-DDTHH:mm
type: knowledge-activity
source_skill: pk-capture
---
Capture N items (E execution, K knowledge) từ [nguồn]

Bước 6: Xác nhận

Báo user. Gợi ý:

• domain=execution: "Xử lý khi track tiếp."
• domain=knowledge: "Chạy pk-distill để đúc kết."

Flow mode auto (delta so với Flow chuẩn)

Chỉ nêu điểm khác; phần không nêu giữ nguyên như Flow chuẩn.

• Bước 1 (quét): quét CHỈ mạch việc vừa xong (không quét cả conversation), theo tiêu chí bắt-thừa. Tiêu chí canonical: mục "Tự capture khi mạch việc hoàn tất" trong AGENTS.md block format (../pk-shared/references/schemas.md) — một nguồn, KHÔNG chép: "2 tuần sau gặp lại tình huống tương tự, item này có tiết kiệm thời gian hoặc tránh lặp lỗi không?" → phân vân thì GHI; chỉ bỏ qua việc vặt một lần / tra lại được ngay.
• Bước 2–3 (trình candidates + user duyệt): SKIP. Ghi thẳng.
• Bước 4–5 (ghi inbox + raw + log): giữ nguyên schema. domain=both tách 2 chiều như thường. Auto-link related_kr / related_action từ snapshot rút gọn (KR IDs từ objective.md, action đang mở từ actions/).
• Bước 6 (báo lại): đúng 1 dòng — Đã ghi N item vào inbox: [type: title, ...]. Nếu inbox vượt ngưỡng nhắc (canonical: ../pk-shared/references/schemas.md, mục "Ngưỡng nhắc xử lý") → thêm 1 dòng đề xuất distill/track (user gật mới chạy).

Quy tắc cứng

1. Capture CHỈ ghi inbox/, raw/ và append log/. KHÔNG ghi actions, knowledge, skills, workflows.
2. Luôn trình candidates cho user duyệt trước ghi, TRỪ mode auto: ghi thẳng theo tiêu chí rồi báo lại (inbox là vùng đệm — user sửa/xoá được, distill là cổng lọc).
3. Luôn lưu raw (cả khi nguồn là hội thoại).
4. domain=both tách ngay thành 2 items, link qua related_inbox 2 chiều (cả 2 item đều điền field này).
5. Khi không có objective, domain mặc định = knowledge.