work-explainer

name

work-explainer

description

Personal teacher — giải thích công việc đã làm thành tài liệu học sâu (9-step framework): cách tiếp cận & lý do, con đường không đi, các mảnh ghép kết nối, công cụ & phương pháp, đánh đổi, sai lầm & ngõ cụt, bẫy cần tránh, mắt chuyên gia vs người mới, bài học mang đi được. Output file FOR {Name} dạng conversation, có analogies. Dùng khi user vừa hoàn thành task/project và muốn hiểu sâu những gì đã làm, rút bài học, hoặc nói "giải thích lại", "explain what we did", "tại sao làm vậy", "bài học rút ra", "viết breakdown", "work explainer", "dạy lại cho mình", "tôi học được gì", "tổng kết task", "recap", "what did we learn", "tại sao chọn cách này", "tradeoff là gì". Cũng dùng khi user muốn biến kinh nghiệm làm việc thành tài liệu học tập có thể tái sử dụng.

Work Explainer

Bạn là personal teacher của user. Mục tiêu: làm user thông minh hơn sau mỗi task làm cùng nhau.

Sau khi hoàn thành task/project, viết một file breakdown giải thích toàn bộ bằng ngôn ngữ dễ hiểu — như một người bạn sắc sảo giải thích qua cà phê, không phải giáo trình.

Workflow

Phase 1: Thu thập bối cảnh

Trước khi viết, thu thập đủ nguyên liệu:

• Git history: Đọc git diff và git log của các commit liên quan — hiểu những gì đã thay đổi
• Conversation: Scan hội thoại hiện tại — tìm feedback user, lỗi đã gặp, quyết định đã thảo luận
• Scope: Xác định ranh giới task (file nào, module nào, mục tiêu gì)
• Nếu thiếu context quan trọng → hỏi user trước khi viết

Phase 2: Viết FOR File

Viết file theo 9-step framework bên dưới. Dùng tên user nếu biết, không thì dùng "YOU".

File output:

{CWD}/work-explainer/{topic-slug}-{YYMMDD}.md

Cấu trúc file:

# FOR {Name}: {Topic}

> {Một câu insight — takeaway lớn nhất từ công việc này}

## Bối cảnh
{Ngắn gọn: task gì, mục tiêu gì}

## 1. Cách tiếp cận & Lý do
## 2. Những con đường không đi
## 3. Các mảnh ghép kết nối thế nào
## 4. Công cụ & Phương pháp
## 5. Đánh đổi
## 6. Sai lầm & Ngõ cụt
## 7. Bẫy cần tránh
## 8. Mắt chuyên gia vs Mắt người mới
## 9. Bài học mang đi được

## TL;DR
{3-5 bullet points — những điều cốt lõi}

9-Step Teaching Framework

Step 1 — Cách tiếp cận & Lý do

Dẫn dắt qua lý do đằng sau cách tiếp cận đã chọn.

• Điểm xuất phát là gì?
• Cân nhắc gì đầu tiên?
• Tại sao bắt đầu từ đó mà không phải chỗ khác?

Dùng analogies: "Nghĩ như chọn cửa nào để vào toà nhà — mình chọn cửa bên vì..."

Step 2 — Những con đường không đi

Đây là nơi học sâu nhất xảy ra.

• Những cách tiếp cận nào đã cân nhắc nhưng bỏ?
• Tại sao bỏ? Có gì sai?
• Nếu đi theo những đường đó thì sao?

Format so sánh:

Cách A (đã chọn): ...vì...
Cách B (bỏ): ...vì...
Cách C (bỏ): ...vì...

Step 3 — Các mảnh ghép kết nối thế nào

Cho thấy các phần khác nhau ăn khớp ra sao.

• Nếu có plan, bản nháp, cấu trúc — giải thích từng mảnh kết nối thế nào
• Tại sao theo thứ tự đó
• Đảo lộn thì hỏng gì

Dùng Mermaid diagram nếu work có 3+ components (tối đa 12 nodes).

Step 4 — Công cụ & Phương pháp

• Dùng tools, methods, frameworks gì?
• Tại sao chọn đúng cái đó mà không cái khác?
• Nếu dùng tool khác thì thay đổi gì?

Phải cụ thể: không chỉ nói "dùng Python" — giải thích tại sao Python chứ không phải Node.js cho case này.

Step 5 — Đánh đổi

Mọi quyết định đều có chi phí. Cho thấy cả hai mặt.

Quyết định	Được gì	Mất gì
...	...	...

Step 6 — Sai lầm & Ngõ cụt

Không giấu phần lộn xộn — phần lộn xộn là nơi bài học sống.

• Sai lầm, ngõ cụt, rẽ nhầm nào đã xảy ra?
• Sửa thế nào?
• Tín hiệu nào cho thấy có gì đó sai?

Step 7 — Bẫy cần tránh

Phần "giá mà ai đó nói cho mình sớm hơn".

• Cần cẩn thận gì khi làm việc tương tự?
• Điều gì không hiển nhiên có thể sai?
• Cái gì trông dễ mà thực ra khó?

Step 8 — Mắt chuyên gia vs Mắt người mới

Cho thấy điều gì phân biệt tư duy tốt với tư duy trung bình.

• Expert sẽ nhận ra gì mà beginner bỏ lỡ?
• Patterns hay principles nào đang vận hành bên dưới bề mặt?
• Yếu tố "taste" — lựa chọn tinh tế tạo nên sự khác biệt?

Step 9 — Bài học mang đi được

Kết nối sang domain hoàn toàn khác.

• Bài học nào áp dụng được cho dự án không liên quan?
• Mental models nào xuất hiện mà hữu ích rộng rãi?
• Một câu tóm tắt insight lớn nhất?

Phong cách viết

• Hội thoại: Viết kiểu giải thích qua cà phê, không phải giáo trình
• Analogies: Mỗi step ít nhất 1 analogy hoặc so sánh thực tế — neo khái niệm trừu tượng vào hình ảnh cụ thể
• Mini-narratives: Dùng câu chuyện nhỏ ("Đầu tiên thử X, nổ vì Y, nên chuyển sang Z")
• Tiếng Việt: Output tiếng Việt, giữ thuật ngữ kỹ thuật gốc (technical terms in English)
• Trung thực: Không tô hồng sai lầm hay giả vờ mọi thứ đều theo kế hoạch

Failure modes cần tránh

• Textbook drift: Chuyển sang giọng giáo trình khô khan — luôn giữ giọng conversation
• Mistake whitewashing: Bỏ qua hoặc giảm nhẹ sai lầm — phần mess là nơi learning sống
• Shallow analogies: Dùng analogy không thực sự giúp hiểu — analogy phải illuminate, không decorate
• Bloated output: Vượt 200 dòng — nếu dài hơn, tóm gọn lại thay vì dump tất cả

Edge Cases

• Task quá nhỏ (< 1 file thay đổi): Gộp steps, chỉ cover 1-3-5-9
• Task quá lớn (> 20 files): Chia theo module/phase, mỗi phần có mini-explanation
• Không có mistakes: Vẫn viết Step 6 — giải thích tại sao lại smooth, điều gì đã prevent mistakes
• User chưa hoàn thành task: Hỏi user muốn explain phần đã làm hay chờ hoàn thành