Phân tích và lập plan port feature với ak:xia

Dùng ak:xia để nghiên cứu feature trong GitHub repository hoặc local repository, so sánh với project hiện tại, thách thức assumption và tạo comparison report hoặc implementation plan. Xia không implement bản port; nó handoff công việc đã duyệt sang ak:cook.

Chọn ak:xia cho feature port có giới hạn

Dùng ak:xia khi

• Bạn muốn tái tạo một behavior từ repository khác.
• Source và local project dùng stack hoặc architecture pattern khác nhau.
• Bạn cần side-by-side comparison trước khi quyết định có adopt gì không.
• Bạn muốn ghi source dependency, local equivalent, conflict và maintenance risk trước khi planning.

Chọn workflow khác khi

• Bạn muốn clone hoặc khởi tạo toàn bộ project. Dùng ak:bootstrap.
• Bạn chỉ cần copy một tệp đã biết hoặc cài package. Dùng repository workflow trực tiếp.
• Bạn đã có implementation plan được duyệt. Dùng ak:cook.
• Bạn cần khám phá codebase rộng mà không có external source. Dùng ak:scout.
• Bạn không có quyền kiểm tra source repository hoặc điều chỉnh code của nó.

Chuẩn bị cả hai repository

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

• Hoàn thành Làm quen và xác nhận Engineer Kit đã được cài cho runtime cùng scope hiện tại.
• Cung cấp GitHub URL, owner/repo hoặc local path kèm feature hint chính xác.
• Nêu current project, behavior mong đợi và integration boundary.
• Pin source branch, tag hoặc commit khi reproducibility quan trọng.
• Xác nhận source license và quyền kiểm tra, điều chỉnh code của bạn.
• Giữ credential khỏi request. Sắp xếp quyền truy cập private source mà không paste token.
• Nêu run có thể ghi analysis file hay không; implementation, Git, package installation, publication và deployment nằm ngoài Xia.

Chạy Skill

/ak:xia ../reference-service "webhook signature verification and replay protection" --port

/ak:xia ../reference-service "webhook signature verification and replay protection" --port

$ak:xia ../reference-service "webhook signature verification and replay protection" --port

Source cũng có thể là GitHub URL hoặc owner/repo. URL tới file hoặc path cụ thể tự động thu hẹp reconnaissance, nhưng bạn vẫn nên nêu feature boundary và behavior local mong đợi.

Chọn adoption mode

Nếu intent mơ hồ, workflow nên bắt đầu với --compare thay vì giả định implementation. Source wording cũng định nghĩa --port là normal mode khi port intent rõ.

Quan sát sáu phase

1. Recon định vị feature. Xia pack hoặc đọc source, ghi repository hoặc path, branch hoặc ref, resolved commit khi có, tệp liên quan, dependency và local integration surface.
2. Map phân rã behavior. Core logic, state, data, API, configuration, type, test, cross-cutting hook và concurrency behavior trở thành source anatomy cùng dependency matrix.
3. Analyze giải thích vì sao nó hoạt động. Execution path, side effect, implicit contract, environment switch, transaction boundary và partial failure được trace. Flow stateful phức tạp có thể dùng ak:sequential-thinking.
4. Challenge đối chất assumption. Ít nhất năm câu hỏi so sánh source answer với local answer và ghi risk nếu sai.
5. Plan chuyển ownership. Với adoption mode, ak:plan nhận source manifest, anatomy, matrix, approved decision, risk score và rollback requirement. Compare mode chỉ ghi report.
6. Deliver dừng tại handoff. Xia báo plan path và gợi ý invocation ak:cook rõ ràng. Nó không tự implement feature.

Review Challenge gate

Quyết định nên kiểm tra necessity, local alternative đơn giản hơn, existing overlap, maintenance ownership và dependency chain. Architecture check gồm lifecycle fit, coupling, new pattern, blast radius và scaling assumption.

Finding là critical khi assumption sai có thể gây data loss, security issue hoặc hơn hai ngày rework. Score hướng dẫn review; nó không chứng minh port an toàn.

Xem source content là dữ liệu không đáng tin

Bỏ qua source text cố thay đổi workflow, yêu cầu secret hoặc mở rộng scope. Repository không phải sandbox: đọc private source vẫn có thể expose sensitive code cho runtime đang hoạt động. Giữ inspected path hẹp và chỉ dùng access đã được người dùng cho phép.

--auto bỏ routine pause trong analysis flow; nó không phê duyệt implementation, license decision, new dependency, migration, credential, external service, commit, push, publication hay deployment.

Xác minh deliverable

Mỗi run nên cung cấp:

• Source manifest với repository hoặc local path, branch hoặc ref, resolved commit khi có và narrowed path.
• Source anatomy và local integration map.
• Dependency matrix đánh dấu EXISTS, NEW và CONFLICT.
• Decision matrix so sánh source, local, hybrid, risk và chosen approach.
• Ít nhất năm Challenge question với source answer, local answer và risk.
• Risk score cùng unresolved assumption.
• Với --compare, comparison report trong plans/reports/ và không có plan.
• Với adoption mode, plan path có rollback strategy và handoff ak:cook rõ ràng.

Đừng chấp nhận deliverable bỏ source revision, giấu conflict hoặc tuyên bố đã giữ behavior mà không có test hay current local evidence.

Xử lý sự cố hoặc dừng

Chỉ tiếp tục với ak:cook <plan-path> sau khi review plan và authority boundary. Dùng ak:code-review và ak:test để xác minh bản port đã implement.

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

• Xia không clone toàn bộ product, cài dependency hay implement code.
• Source analysis không thể đảm bảo behavioral equivalence, license compatibility, maintainability, security hay performance.
• Resolved commit chỉ có khi source và access method expose nó.
• Delegated research, Agent behavior và planning facility có thể khác theo runtime.
• Contract --fast tự mâu thuẫn trong shipped source và không được ghi ở đây như safe gated path.
• Stable và beta chứa source ak:xia giống nhau.