Định hình hướng triển khai với ak:brainstorm

Dùng ak:brainstorm để biến yêu cầu chưa rõ về product, code, documentation hoặc maintenance thành delivery contract cùng hướng được đề xuất. Skill tách outcome mong muốn khỏi bằng chứng hiện tại, chỉ so sánh lựa chọn có ý nghĩa và dừng trước implementation.

Chọn ak:brainstorm khi hướng đi cần được làm rõ

Dùng ak:brainstorm khi

• Yêu cầu nhiều bước còn thiếu outcome, constraint, non-goal hoặc acceptance criterion rõ ràng.
• Có nhiều hơn một hướng kỹ thuật hoặc product khả thi cần so sánh.
• Một bug đã được chẩn đoán vẫn còn lựa chọn quan trọng về kiến trúc hoặc cách sửa.
• Bạn muốn recommendation dựa trên bằng chứng trước planning hoặc implementation.

Chọn workflow khác khi

• Contract và hướng đi đã được duyệt. Dùng ak:plan để tạo implementation plan hoặc ak:cook để thực thi công việc đã duyệt.
• Bạn cần câu trả lời kỹ thuật trực tiếp thay vì quyết định delivery. Dùng workflow tư vấn hoặc hỏi đáp.
• Bạn cần bản đồ codebase có giới hạn. Dùng ak:scout.
• Bạn mới chỉ có triệu chứng lỗi. Hãy chẩn đoán root cause trước khi chọn cách sửa; brainstorming không thay thế debugging.

Chuẩn bị project và runtime

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

• Hoàn thành Làm quen và xác nhận Engineer Kit đã được cài cho đúng runtime cùng scope.
• Nêu vấn đề, người dùng hoặc hệ thống bị ảnh hưởng, constraint đã biết và quyết định đã chốt.
• Mở project liên quan khi tính khả thi phụ thuộc code, test, documentation hoặc design guideline của project.
• Xác định lần chạy có được tạo brief cục bộ hoặc dùng advisory supervision hay không.

Xem Runtime adapter để hiểu khác biệt giữa các target.

Chạy Skill

/ak:brainstorm "Choose how to add offline draft recovery to the editor. Preserve current storage formats, avoid a new service, and define observable recovery behavior."

/ak:brainstorm "Choose how to add offline draft recovery to the editor. Preserve current storage formats, avoid a new service, and define observable recovery behavior."

$ak:brainstorm "Choose how to add offline draft recovery to the editor. Preserve current storage formats, avoid a new service, and define observable recovery behavior."

Topic hoặc problem là input mặc định. Các tùy chọn hiện có thay đổi output, cách xử lý scope, verification, supervision hoặc cách trình bày visual:

Với --report, Skill dùng plans/{plan-dir}/reports/ khi có plan đang active, nếu không thì dùng plans/reports/, trừ khi runtime inject đường dẫn Report:. Report gồm bốn trường contract, các lựa chọn đã so sánh, recommendation và câu hỏi chưa giải quyết; --report --html ghi cả hai artifact.

Với --advice, Skill luôn dùng supervisor one-shot kongming. Model routing phụ thuộc host: session Claude Code subscription dùng Fable 5, Codex dùng gpt-6-astra với low reasoning effort và Cursor dùng claude-fable-5-high. Host single-model khác dùng session model mạnh nhất hiện có và báo giới hạn same-model đó.

Khi topic liên quan UI hoặc UX, --html gồm mockup giao diện có chú thích và sơ đồ delivery flow. Với phần so sánh approach, Skill đọc ak config prefs resolve --json và ưu tiên diagram-design Quadrant khi .prefs.visual.diagramDesign.enabled; với KPI-shaped tile, Skill ưu tiên AntV Infographic CandyCardLite hoặc CompactCard khi .prefs.visual.antv.enabled. Nếu không có image generation đầy đủ, Skill có thể dùng HTML, CSS hoặc SVG cục bộ và báo giới hạn đó.

Khi chọn --ultra, Skill giữ phần candidate ở chế độ read-only, yêu cầu năm candidate dùng được với một lần re-dispatch có giới hạn nếu cần, anonymize các candidate trước khi scoring và ghi một ranking appendix ngắn. Skill hard-stop khi không thể dispatch song song các candidate read-only. Nếu runtime không thể route model tier nhưng có thể dispatch song song, Skill báo đây là lần chạy same-tier best-of-5. Chế độ này lấy cảm hứng từ LLM-as-a-Verifier nhưng không tuyên bố dùng logprob hoặc tournament mechanic.

Khi chọn --yagni, Skill chuyển nguyên flag này cho các Skill downstream và công việc được giao. Nếu không có flag, handoff không tự đưa scope-cutting vào.

Chọn tham gia route HTML AK Render

--ak-render ngầm bật --html và compile brief brainstorm.html từ Page Spec. Thay vì viết tay trang HTML, Skill ghi brainstorm.page.yaml cạnh brief rồi compile bằng compiler được ghim npx -y @bestagentkits/render@0.2.0, yêu cầu Node 20.11 trở lên. Project có thư mục .ak-render/ chứa theme preset của AK Render sẽ tự chọn route này, không có cách tắt cho từng lần chạy.

• Route HTML viết tay vẫn là mặc định. AK Render vẫn là opt-in vì phép so sánh có đo lường với route mặc định chưa vượt quality gate.
• Trang giữ đủ các section bắt buộc như route mặc định.
• Các switch editorial visual chỉ áp dụng cho route mặc định.
• Trang đã compile mở qua file:// với zero network request. Lần chạy npx đầu tiên tải package đã ghim từ npm registry; các lần sau dùng cache.
• Để sửa trang, hãy sửa spec rồi compile lại. Không vá HTML đã compile.
• Diagram panel được compile qua page wrapper của ak:diagram, wrapper này nhúng SVG thật.
• Nếu thiếu Node, npx hoặc không tải được package, hoặc spec vẫn không hợp lệ sau ba lần sửa, Skill dùng route mặc định và nêu lý do trong report.

Mô tả quyết định rõ ràng

Input hữu ích nêu:

• Outcome: trạng thái người dùng hoặc hệ thống bạn muốn đạt được.
• Constraints: giới hạn compatibility, an toàn, thời gian, công nghệ hoặc ownership.
• Non-goals: công việc gần kề mà quyết định không được mở rộng sang.
• Acceptance criteria: bằng chứng quan sát được để chứng minh hướng đi thành công.
• Known evidence: behavior hiện tại, quyết định trước đây, hướng đã thất bại hoặc vùng repository nên kiểm tra.

Với ví dụ draft recovery, hãy nêu editor state nào phải được giữ, khi nào recovery xuất hiện, format hiện có nào phải tiếp tục đọc được và không được thêm network service. Skill khi đó có thể so sánh lựa chọn có giới hạn thay vì tự tạo một nền tảng synchronization rộng hơn.

Hiểu điều gì xảy ra trong một lần chạy

1. Skill định hình contract. Skill ghi nhận outcome, constraint, non-goal và acceptance criteria, đồng thời dùng lại contract đã duyệt nếu có.
2. Skill kiểm tra mức độ tương xứng. Yêu cầu cụ thể chỉ nhận phần xác nhận ngắn. Skill chỉ hỏi khi quyết định còn thiếu làm thay đổi đáng kể kết quả, ranh giới an toàn hoặc public contract.
3. Skill kiểm tra bằng chứng liên quan. Skill đọc tập source, test, documentation, plan hoặc live state nhỏ nhất cần thiết trước khi khẳng định một hướng khả thi. Skill xử lý bất định mà bằng chứng này có thể giải quyết và chỉ đánh dấu điều vẫn không thể biết tại thời điểm ra quyết định.
4. Skill đưa lỗi qua chẩn đoán. Với bug, Skill ghi lại trạng thái thất bại và root cause trước khi so sánh cách sửa bám theo nguyên nhân.
5. Skill so sánh các hướng khả thi. Skill đưa ra tối đa ba lựa chọn có ý nghĩa cùng trade-off, khoảng trống bằng chứng, load-bearing assumption và điều kiện thất bại đầu tiên. Skill so sánh worst plausible case, rồi đề xuất hướng nhỏ nhất đáp ứng contract. Nếu assumption quan trọng chưa thể xử lý, recommendation ưu tiên lựa chọn có chi phí từ bỏ thấp nhất.
6. Skill chuẩn bị handoff. Skill chuyển contract đã duyệt, hướng đã chọn, bằng chứng và rủi ro chưa xử lý sang planning, implementation hoặc bug-fix workflow.

Giữ quyền phê duyệt và an toàn ở bạn

Bạn quyết định có chấp nhận recommendation và bất đồng quan trọng đã được giải quyết hay chưa. Advisory supervision không nắm quyền này. Skill không nên đọc tệp riêng tư không liên quan, khẳng định behavior hiện tại chỉ từ ý định hoặc tạo thêm component và migration để design trông đầy đủ.

Brief HTML cục bộ là file effect rõ ràng. Brief không cần network asset và phải mở trực tiếp được từ disk. Mọi commit, push, pull request, publication, deployment, sử dụng credential hoặc dịch vụ tính phí ở downstream đều cần quyền riêng trong workflow thực hiện hành động đó.

Xác minh kết quả

Một lần chạy hoàn tất nên cung cấp:

• Outcome, constraint, non-goal và acceptance criteria đã được chấp nhận.
• Bằng chứng đã xác nhận cùng khoảng trống hoặc bất định được ghi rõ.
• Tối đa ba hướng khả thi khi thực sự có lựa chọn.
• Load-bearing assumption, điều kiện thất bại đầu tiên và worst plausible case của từng hướng.
• Hướng được đề xuất với lý do, trade-off có ý nghĩa và switching cost khi assumption quan trọng vẫn chưa xử lý.
• Handoff target như ak:plan, ak:cook hoặc bug workflow đã chẩn đoán.
• Rủi ro hoặc câu hỏi chưa giải quyết được liệt kê cuối cùng.
• Khi được yêu cầu, brief brainstorm.html self-contained chứa cùng decision record và phần giải thích trực quan bắt buộc.

Lần chạy hoàn tất khi bạn có thể giải thích điều sẽ được cung cấp, điều ngoài scope, vì sao hướng đã chọn phù hợp bằng chứng và check quan sát nào chứng minh thành công. Đây không phải bằng chứng solution đã được implementation.

Xử lý sự cố hoặc tiếp tục

Sau khi chấp nhận hướng đi, tiếp tục với ak:plan để có implementation plan bền vững hoặc ak:cook để thực thi đã duyệt. Dùng Tổng quan Engineer Kit để so sánh workflow gần đó.

Biết các giới hạn hiện tại

• Skill chỉ có thể kiểm tra project state, tool và credential có trong session.
• Skill có thể xác lập decision contract, không thể chứng minh tính khả thi của implementation vượt quá bằng chứng thực sự đã kiểm tra.
• Cách gọi Cursor bằng slash là bằng chứng do người dùng xác minh, không chứng minh runtime parity đầy đủ.