Biến quyết định thành tài liệu bền vững với ak:interview-docs

Dùng ak:interview-docs khi knowledge, taste và quyết định rõ ràng của người dùng cần trở thành tài liệu project bền vững. Skill thực hiện guided interview và patch document đang phát triển sau mỗi câu trả lời thay vì tự nghĩ ra quan điểm, suy ra từ code hoặc chờ đến cuối mới lưu công việc.

Chọn ak:interview-docs cho quyết định do người dùng tạo

Dùng ak:interview-docs khi

• Bạn muốn diễn đạt project vision hoặc hướng README bằng lời của chính mình.
• Bạn đã đưa ra architectural decision và muốn một ADR ngắn, có thể review.
• Bạn muốn phát triển principle, strategy, review hoặc framework qua quy trình hỏi đáp tập trung.
• Bạn muốn mỗi câu trả lời được lưu trước khi interview tiếp tục để tiến độ có thể phục hồi và dễ kiểm tra.

Chọn workflow khác khi

• Bạn muốn assistant đề xuất option hoặc giúp quyết định. Dùng ak:brainstorm, rồi quay lại sau khi bạn chọn.
• Documentation cần được suy ra từ repository behavior, API hoặc source code. Dùng ak:docs.
• Bạn đã có document hoàn chỉnh và chỉ cần edit, translate hoặc format. Dùng documentation hoặc artifact workflow phù hợp.
• Bạn muốn list chưa có thứ tự tự động thành priority, phase hay roadmap. Skill này phải hỏi trước khi gán thứ tự.

Chuẩn bị interview boundary

Trước khi bắt đầu:

• Hoàn tất Onboarding, rồi xác nhận Engineer Kit được cài cho runtime và scope hiện tại.
• Chọn vision interview rộng hoặc một structured document. Nếu request phù hợp cả hai, hãy chờ một câu hỏi ngắn để chọn mode.
• Cung cấp project root và, với structured-document mode, target path hoặc topic chính xác. Giữ nguyên thay đổi không liên quan trong document gần đó.
• Quyết định output thuộc README.md, ADR ngắn đánh số hay named document. Nêu quy tắc format và location riêng của repository.
• Loại secret, credential, private personal data và nội dung không nên trở thành lịch sử project bền vững.

Input được khai báo là <vision | document-path | topic>. Đây là intent hint, không phải parser cố định. Hãy nêu mode, target, audience, scope và topic bạn không muốn interview đề cập.

Chạy interview với target cụ thể

/ak:interview-docs ./docs/product-principles.md "Interview me to capture five product principles in my wording. Ask one open question at a time, patch each accepted answer before continuing, do not rank the principles unless I explicitly decide an order, and stop when I say done."

/ak:interview-docs ./docs/product-principles.md "Interview me to capture five product principles in my wording. Ask one open question at a time, patch each accepted answer before continuing, do not rank the principles unless I explicitly decide an order, and stop when I say done."

$ak:interview-docs ./docs/product-principles.md "Interview me to capture five product principles in my wording. Ask one open question at a time, patch each accepted answer before continuing, do not rank the principles unless I explicitly decide an order, and stop when I say done."

Request tốt xác định suy nghĩ của ai đang được ghi lại, target document, intended reader, mức chi tiết mong muốn, section được bảo vệ, có được tạo file mới hay không và phrase kết thúc interview.

Chọn interview mode

Vision mode giữ README tập trung vào vision. Mỗi ADR ngắn và chứa Status, Context, Decision cùng Consequences; nó chỉ ghi quyết định bạn đã đưa ra rõ ràng. Structured-document mode làm việc trên một document như principle, strategy, review hoặc framework và giữ wording cùng edit về sau của bạn.

Quan sát các giai đoạn interview

1. Skill đọc context hiện có. Vision mode đọc README và ADR directory. Structured-document mode đọc target và doc gần đó.
2. Skill xác nhận mode và target. Chỉ request mơ hồ quan trọng mới cần câu hỏi chọn mode trước.
3. Skill tạo structure an toàn nhỏ nhất. Structured document còn thiếu nhận một minimal skeleton đúng một lần; content hiện có được giữ thay vì thay toàn bộ.
4. Skill hỏi theo nhịp đã chọn. Vision mode dùng batch năm câu đa dạng theo mặc định. Structured-document mode hỏi chính xác một câu focused, open-ended.
5. Bạn trả lời hoặc sửa premise. Câu trả lời của bạn cung cấp substance cho document. List chưa có thứ tự vẫn không có thứ tự trừ khi bạn duyệt rank, sequence hoặc priority.
6. Skill đọc lại và patch ngay. Skill áp dụng câu trả lời vào document bị ảnh hưởng trước khi xử lý câu tiếp theo.
7. Loop tiếp tục đến khi bạn kết thúc. Báo cáo cuối xác định file, decision đã ghi, section còn mở và nội dung bị loại trừ có chủ đích.

Giữ authorship và approval ở người dùng

• Không ghi secret, credential, access token, private personal data hay sensitive operational detail vào doc bền vững.
• Giữ user wording và manual edit về sau. Patch section liên quan; không thay toàn bộ document hiện có hay thêm speculative section.
• Hỏi trước khi biến list thành ordered sequence, priority, score, timeline hoặc recommendation.
• Giữ fact, opinion, hypothesis và decision có thể phân biệt. Ghi lại uncertainty khi người dùng thể hiện điều đó.
• Không commit, push, publish hay distribute document trừ khi workflow được cấp quyền riêng thực hiện.

Xác minh document và evidence

Kết quả interview đầy đủ nên gồm:

• Target file chính xác đã tạo hoặc patch và section bị ảnh hưởng bởi từng câu trả lời được chấp nhận.
• README chỉ tập trung project vision, hoặc ADR đánh số với Status, Context, Decision cùng Consequences cho quyết định người dùng thực sự đưa ra.
• Với structured document, structure tối thiểu mạch lạc có claim và language truy ngược về interview thay vì suy luận source code.
• Item chưa có thứ tự được giữ nguyên trừ khi có approval sắp xếp rõ ràng.
• Open question, section deferred, contradiction và user correction vẫn cần xử lý.
• Final diff review cho thấy content hiện có và công việc không liên quan được giữ nguyên.

Hai release stable và beta được ghim chứa cùng Skill file. Bundle không có template, script hay automated test cho interview loop; chất lượng output phụ thuộc câu trả lời của người dùng, document hiện có cùng khả năng pause, đọc lại và patch đáng tin cậy của runtime.

Khắc phục sự cố và hiểu giới hạn

Dùng ak:brainstorm trước interview khi bạn cần option, hoặc ak:docs khi chính repository là source of truth.