knowhow-init

Knowhow Init

Tổng quan

Knowhow System là nghi thức tích luỹ tri thức có cấu trúc cho một kho (AI viết, người duyệt) qua 3 lớp:

Lớp	Vai trò
Raw	Nguồn thô, immutable. Agent đọc nhưng không sửa.
Wiki	Tri thức có cấu trúc, liên kết chéo.
Skills & Workflows	Kiến thức thực thi, tái sử dụng.

Phân biệt Skill và Workflow (bản rút gọn, định nghĩa chuẩn nằm trong references/schema-template.md mục "Phân biệt Skill và Workflow" mà Bước 3 sinh vào SCHEMA.md):

• Skill = thao tác khép kín, làm-theo-được, tái dùng cho task tương tự (được phép gắn domain).
• Workflow = chuỗi bước, gắn domain, gọi nhiều skill. Thay đổi khi đổi domain.

Flow khởi tạo

Bước 1: Thu thập thông tin

Hỏi user 3 câu:

1. Tên kho tri thức (dùng cho SCHEMA.md và log)
2. Mô tả lĩnh vực (1-2 câu, giải thích kho phục vụ việc gì)
3. Kho có làm việc theo dự án/khách hàng/chiến dịch không? (có/không). Nếu CÓ: seed thêm page type project (trang thực thể làm điểm neo cho tri thức cùng dự án, xem Bước 3 và 4). Nếu KHÔNG hoặc không chắc: bỏ qua, schema evolution sẽ thêm sau khi đủ tín hiệu.

Nếu user cung cấp sẵn trong prompt, không cần hỏi lại.

Bước 2: Tạo cấu trúc thư mục

Tạo toàn bộ cây thư mục .knowhow/ tại root workspace:

.knowhow/
├── SCHEMA.md
├── schema-signals.md
├── raw/
├── inbox/
├── archive/
├── wiki/
│   ├── index.md
│   └── log.md
├── skills/
│   └── registry.md
└── workflows/
    └── registry.md

Chạy lệnh tạo thư mục:

mkdir -p .knowhow/{raw,inbox,archive/inbox,wiki,skills,workflows}

Bước 3: Sinh SCHEMA.md

Đọc file references/schema-template.md trong thư mục skill này.

Thay thế:

• {{PROJECT_NAME}} → tên kho user cung cấp
• {{PROJECT_DESCRIPTION}} → mô tả domain user cung cấp
• {{DATE}} → ngày hiện tại (YYYY-MM-DD), dùng cho entry Changelog đầu tiên trong SCHEMA

Nếu câu 3 = CÓ (kho theo dự án): thêm dòng sau vào cuối bảng "Page Types" trong SCHEMA vừa sinh:

| project | wiki/project-<slug>.md | Trang thực thể dự án: mục tiêu, kết quả, neo tri thức cùng dự án |

Ghi kết quả vào .knowhow/SCHEMA.md.

Bước 4: Sinh các file nội dung

wiki/index.md:

# Wiki Index

## Decision

## Pattern

## Concept

## Troubleshooting

## Lesson

Nếu câu 3 = CÓ, thêm heading ## Project vào cuối index.

wiki/log.md (thay YYYY-MM-DD bằng ngày hiện tại, {{PROJECT_NAME}} bằng tên kho):

# Activity Log

## [YYYY-MM-DD] init | Khởi tạo .knowhow/ cho kho {{PROJECT_NAME}}

skills/registry.md (header phải khớp page-formats mục 6.1, gồm cột Khi nào dùng để knowhow-run match task sang skill):

# Skill Registry

| Skill | Mô tả | Khi nào dùng | Version | Tags | Cập nhật |
|-------|--------|--------------|---------|------|----------|

workflows/registry.md (header phải khớp page-formats mục 6.2, gồm cột Khi nào dùng + Tags để knowhow-run match task sang workflow):

# Workflow Registry

| Workflow | Mô tả | Khi nào dùng | Skills dùng | Version | Tags | Cập nhật |
|----------|--------|--------------|-------------|---------|------|----------|

schema-signals.md (top-level, cạnh SCHEMA.md, là sổ tích luỹ tín hiệu tiến hoá, tạo rỗng chỉ có header):

# Schema Signals

Sổ tích luỹ tín hiệu "khuôn không vừa". Append-only, parse được.
distill và query ghi vào "Đang chờ xử lý". lint `schema-review` đọc, áp ngưỡng, rồi cắt tín hiệu đã dùng sang "Đã xử lý".

Format mỗi dòng:
`- [YYYY-MM-DD] <nguồn> | <loại> | <chi tiết ngắn> | related: <slug-hoặc-tag>`

- nguồn ∈ distill | query | run
- loại ∈ no-fit-type | adhoc-section | query-miss | promote-candidate
- promote-candidate: tín hiệu "một wiki pattern/troubleshooting page đang bị dùng lặp để LÀM THEO", ứng viên nâng thành skill/workflow. query/run phát; `related` trỏ slug page nguồn. Tổng hợp promote-candidate là việc của `knowhow-distill` (KHÔNG phải schema-review); schema-review BỎ QUA các dòng promote-candidate.
- lint scan (type-bloat, tag-cluster) KHÔNG ghi vào sổ này, tính live khi schema-review chạy.

## Đang chờ xử lý

## Đã xử lý

Bước 5: Thêm hướng dẫn vào agent config

Chỉ ghi vào AGENTS.md tại root workspace. Các config khác (CLAUDE.md, GEMINI.md) user tự xử lý.

Nội dung thêm nằm trong references/agent-config-snippet.md, đã bọc sẵn trong cặp marker:

<!-- knowhow:start -->
...
<!-- knowhow:end -->

Snippet dùng cú pháp @ để agent tự nạp 4 file bản đồ vào context đầu phiên.

Idempotent (3 nhánh) — re-init phải thay thế nội dung trong marker để luôn đồng bộ phiên bản snippet mới nhất:

SNIPPET=references/agent-config-snippet.md
CONFIG=AGENTS.md

if [ ! -f "$CONFIG" ]; then
  # 1. Chưa có file → tạo mới + ghi block
  cp "$SNIPPET" "$CONFIG"
elif grep -q "knowhow:start" "$CONFIG"; then
  # 2. Đã có marker → thay thế toàn bộ vùng giữa start/end bằng snippet mới
  awk '
    /<!-- knowhow:start -->/ {while((getline line < "'"$SNIPPET"'")>0) print line; close("'"$SNIPPET"'"); skip=1; next}
    /<!-- knowhow:end -->/ {skip=0; next}
    !skip
  ' "$CONFIG" > "$CONFIG.tmp" && mv "$CONFIG.tmp" "$CONFIG"
else
  # 3. Có file, chưa marker → append block
  printf '\n' >> "$CONFIG"
  cat "$SNIPPET" >> "$CONFIG"
fi

Bước 6: Ghi log hoàn tất

Xác nhận với user:

• Liệt kê các file đã tạo
• Nhắc user đọc .knowhow/SCHEMA.md để hiểu quy tắc vận hành
• Gợi ý bước tiếp theo: capture knowhow đầu tiên vào inbox/