Cấu trúc file artifact

Bốn section sau xuất hiện ở hầu hết artifact, với tiêu đề biến thể theo skill (## Design Mode, ## Implementation Mode, ## Ship Mode). Ngoại lệ đáng nhớ: 01-requirement.md không có Self-Check và User Decision Options; session.md chỉ có Mode. Hiểu một lần rồi khỏi phải đọc lại ở dưới.

## Mode

Mức độ sâu mà skill chạy ở bước này (mỗi skill có tập mode riêng). Tick một ô. Nó cho bước sau biết artifact này được làm kỹ tới đâu — một design mini không nên được tin như một design phased.

## Self-Check

Checklist tự soát của chính skill, chống các lỗi đặc trưng của AI: option bịa, giả định cũ, TBD, âm thầm mở rộng scope. Tick nghĩa là skill khẳng định đã kiểm — người review vẫn có quyền không tin.

## User Decision Options

Các lựa chọn cụ thể trình cho người dùng ở cuối bước, có Recommended: đứng đầu và Decision impact: nói rõ chọn khác thì hệ quả gì. Người dùng chọn một option = phê duyệt đúng option đó, không phải phê duyệt cả workflow.

## Next Step Recommendation

Phiếu handoff: Recommended next skill, Reason, Requires user approval: yes/no, Gate status, và Fallback if unclear: h4-workflow. Đây là cách một artifact gọi thẳng bước kế tiếp mà không cần quay về entrypoint.

Sổ trạng thái của cả phiên — file mà h4-workflow đọc đầu tiên khi resume hoặc khi cần phục hồi một phiên không rõ trạng thái. Nếu file này sai, mọi routing sau đó sai theo.

## Task

Một dòng tên task, đủ để nhận ra phiên này giữa nhiều thư mục khác.

## Created

Ngày mở phiên. Dùng để phát hiện artifact đã cũ (stale) khi resume sau nhiều ngày.

## Source Request

Nguyên văn yêu cầu ban đầu của người dùng. Giữ nguyên để về sau còn đối chiếu xem scope có bị trôi không.

## Mode

quick / standard / hard / review-only — lộ trình đang chạy. Quyết định bước nào được bỏ và gate nào bị khóa cứng.

## Status

draft / in-progress / blocked / ready-to-ship / completed — trạng thái tổng của phiên, khác với trạng thái của từng artifact.

## Current Step

Đang đứng ở skill nào. Đây là điểm neo để resume đúng chỗ thay vì làm lại từ đầu.

## Completed Steps

Checklist 7 skill bước. Tick = bước đó đã chạy và để lại artifact.

## Skipped Steps

Bước bị bỏ có chủ ý. Bỏ bước là hợp lệ, nhưng bỏ mà không ghi ở đây thì không.

## Next Recommended Action

Hành động kế tiếp mà workflow đề xuất, để phiên có thể tiếp tục bởi người/agent khác.

## Reason

Lý do cho mode và cho các bước bị bỏ. Đây là chỗ chịu trách nhiệm cho mọi quyết định rút ngắn quy trình.

## Scope Boundary

Ranh giới scope ở mức phiên. Dùng để chặn scope creep khi task chạy dài qua nhiều bước.

## Artifact State

Bảng trạng thái từng file (missing / draft / ready / approved / needs-changes / shipped / blocked). Cho người/agent resume nhìn nhanh hiện trạng mà không mở từng file. session-health không đọc bảng này — nó tự kiểm nhất quán từ artifact thật trên đĩa và các section khác của session.md (Mode, Current Step, Blockers, Skipped Steps).

## Blockers

Những gì đang chặn tiến trình. Rỗng thì ghi None, không để trống.

## Notes

Ghi chú tự do không thuộc section nào — quyết định miệng, context ngoài repo, cảnh báo cho người tiếp nhận.

Chốt bài toán trước khi bàn giải pháp. Mục tiêu của cả file: sau khi đọc, hai người khác nhau phải hiểu giống nhau về "thế nào là xong". Ở mode quick có thể là artifact mini.

## Original Request

Nguyên văn yêu cầu, không diễn giải lại. Để về sau phân biệt được "user yêu cầu" và "agent suy ra".

## Problem Statement

Vấn đề thật đằng sau yêu cầu, viết theo góc nhìn nghiệp vụ. Đây là chỗ phát hiện yêu cầu đã bị gói sẵn thành giải pháp.

## Task Type

bug / feature / refactor / performance / incident / review. Loại task ảnh hưởng trực tiếp tới mode và tới việc có cần grill hay không.

## Expected Output

Người dùng mong nhận được gì cuối cùng: code chạy, một MR, một báo cáo review, hay một kết luận.

## Acceptance Criteria

Điều kiện kiểm chứng được để gọi là xong. Phải quan sát được — Verification Plan ở bước design sẽ ánh xạ vào đúng những dòng này.

## Scope In

Những gì chắc chắn làm trong task này.

## Scope Out

Những gì chắc chắn không làm, dù có vẻ liên quan. Section này là vũ khí chính chống scope creep ở các bước sau.

## Constraints

Ràng buộc theo trục: Tech, Business, Backward compatibility, Security/privacy, Deadline. Đây là thứ loại bỏ option trước khi brainstorm mất thời gian với nó.

## Touchpoints

Điểm chạm kỹ thuật dự kiến: Modules, APIs, Database, Integrations. Là bản nháp đầu tiên của bảng file bị ảnh hưởng ở design.

## Context Checked

Đã đọc thật những gì: artifact workflow, code/docs, bằng chứng người dùng cung cấp — và Unknown cho phần chưa xác minh. Phân định rõ "đã kiểm" với "đang đoán".

## Known Context

Kiến thức nền đã xác minh, cần cho bước sau nhưng không nằm trong code (quy tắc nghiệp vụ, quyết định cũ).

## Open Questions

Câu hỏi còn treo. Nếu có câu hỏi chặn ở đây, artifact không thể là Ready for design.

## Readiness

Ready for brainstorm / Ready for design / Need more information — cửa ra của bước này.

## Recommended Workflow

Mode, Path (lộ trình skill dự kiến), và User decision needed. Đây là đề xuất lộ trình đầu tiên, sẽ được ghi lại vào session.md.

So sánh các hướng đi thật trước khi cam kết thiết kế. Bỏ được khi hướng đi hiển nhiên — nhưng phải ghi lý do trong session.md.

## Context

Tóm tắt bài toán ở mức vừa đủ để đọc file này độc lập, không phải mở lại 01-requirement.md.

## Context Sources

Nguồn context: clarify artifact, code/docs, pattern có sẵn, và Unknown. Option dựa trên nguồn nào cũng truy được về đây.

## Mode

quick / standard / hard — brainstorm sâu tới đâu.

## Assumptions To Challenge

Các giả định đang được mặc nhiên tin, viết ra để cố tình đặt dấu hỏi. Giả định không được viết ra là giả định không ai kiểm được.

## Scope Assessment

Bounded task: yes/no, các workflow/module HIS độc lập bị liên quan, và Decomposition needed. Nếu task không bounded, việc đúng là tách task chứ không phải thiết kế to hơn.

## Options

Ba hướng: A — Minimal, B — Safer, C — Broader. Mỗi option có Idea, Scope fit, Pros/Cons, Complexity, Risk, HIS stakeholder/workflow impact, Verification effort, Rollback, và Second-order effects (hệ quả bậc hai — cái vỡ ở chỗ khác chứ không ở chỗ bạn sửa).

## Comparison

Bảng đối chiếu A/B/C theo 9 tiêu chí. Ép việc so sánh phải đồng trục, thay vì mỗi option được mô tả bằng ngôn ngữ có lợi cho nó.

## Recommended Direction

Hướng được chọn kèm Rationale, Conditions (điều kiện để lựa chọn này còn đúng), Deferred work, Next step.

## Decision

Direction selected / Needs user decision / Return to clarify — cửa ra của bước này.

## Deferred / Out Of Scope Ideas

Ý tưởng tốt nhưng không làm lần này. Ghi ở đây để không bị lặng lẽ nhồi vào design.

## Decision Needed

Nói rõ đang cần người dùng quyết cái gì, khi Decision là Needs user decision.

Bản thiết kế thi hành được — và là artifact giữ hard gate quan trọng nhất của toàn workflow. Tiêu chuẩn: đọc xong là code được, không phải suy diễn thêm.

## Chosen Approach

Cách làm đã chọn, viết ngắn. Nếu có 02-brainstorm.md thì đây là option đã được quyết.

## Design Mode

mini (thay đổi nhỏ) / standard / phased (chia phase, dùng cho thay đổi lớn hoặc rủi ro cao).

## Scope In / ## Scope Out

Scope ở mức thiết kế, hẹp hơn scope ở requirement. Review sẽ đối chiếu diff thật với đúng hai section này.

## Scope Challenge

Ba câu hỏi ép thu nhỏ thay đổi: có code/pattern nào tái dùng được không, minimum change set là gì, và complexity check — thiết kế có phức tạp quá so với bài toán không.

## Assumptions / Unknowns

Giả định và ẩn số còn lại. Ẩn số phải được đánh dấu và có bước discovery đứng trước, không được để implement tự đoán.

## Files / Modules Likely Affected

Bảng Area / File-Module / Change Type / Ownership. Change Type gồm cả discover cho phần chưa biết. Đây là hợp đồng file ownership: implement sửa ngoài bảng này là vi phạm và review sẽ bắt.

## Data / Workflow Impact

Dữ liệu vào/đổi/ra, workflow HIS bị ảnh hưởng, và ràng buộc thứ tự/phụ thuộc. Đây là section quyết định task có cần h4-grill hay không.

## UI Layout

Chỉ thêm khi chạm màn hình FE. Gồm screen/route, phân vùng theo thứ tự trên xuống (action bar → form lọc → table → drawer), component OneHealth UI cho từng vùng, màn hình tương tự dùng làm tham chiếu, hành vi phải giữ nguyên (validation, phím, pagination, quyền), và trạng thái mockup. Đây là contract của UI, không phải file mockup.

## Implementation Steps

Các bước đánh số, mỗi bước là một thay đổi kiểm chứng được. 05-implement.md sẽ báo cáo lại theo đúng số bước này.

## Verification Plan

Kế hoạch kiểm chứng theo tầng: Build/typecheck, Unit test, Integration test, Manual smoke, Regression check. Viết trước khi code, nên không thể co lại cho vừa với thứ đã làm được.

## Rollback / Mitigation Plan

Nếu lên production mà sai thì lùi bằng cách nào. Với HIS, thay đổi không có đường lùi là thay đổi phải thiết kế lại.

## Risks To Watch

Rủi ro đã biết cần theo dõi trong lúc implement và review.

## Definition Of Done

Năm điều kiện hoàn thành ở mức task: code theo design, verification xong hoặc rủi ro được chấp nhận, review xong, không lẫn file bí mật, commit/MR đã chuẩn bị nếu cần.

## Approval

Section gate. Approved for implementation / Pending approval / Blocked, cộng Approved by, Approval source (explicit user approval hay not approved) và Approval notes. Agent không được tự tick thay người dùng.

Artifact kèm theo của bước design, chỉ tạo khi design tạo mới hoặc thay đổi màn hình FE. Một file HTML tự chứa (Tailwind qua CDN, mô phỏng visual Ant Design / OneHealth UI) để người dùng duyệt layout bằng mắt trước khi ai đó viết component thật. Nhiều màn hình nằm trong cùng một file dưới dạng section, không tách file.

Vai trò

Phương tiện duyệt bằng mắt, không phải nguồn chân lý. Nó tồn tại để người dùng phát hiện layout sai trước khi tốn công implement.

Khi lệch với design

Section UI Layout trong 03-design.md thắng — sửa mockup theo design đã duyệt. Trừ khi người dùng duyệt chính thay đổi trên mockup; khi đó cập nhật design ngược lại.

Stress-test thiết kế trước khi viết code: đặt câu hỏi khó theo từng trục rủi ro rồi cho verdict. Bắt buộc khi có tín hiệu dữ liệu / auth / permission / integration / báo cáo / production.

## Design Under Test

Đang grill phiên bản design nào. Grill một design đã bị sửa sau đó là grill vô nghĩa.

## Mode

light (soát nhanh) / full (đủ trục) / his-risk (tập trung vào rủi ro đặc thù bệnh viện).

## Assumptions Challenged

Các giả định của design đã bị đem ra chất vấn, và kết quả chất vấn.

## Decision Gaps

Câu hỏi đang chặn, câu trả lời được đề xuất, và Decision impact if different — nếu thực tế trả lời khác thì thiết kế đổi tới đâu.

## Design Steps Stress-Tested

Bảng Design Step / Assumption / Risk Found / Required Change. Ép grill đi theo từng bước implement cụ thể, không phán chung chung về cả thiết kế.

## Hard Questions

Bảy trục, mỗi trục một cặp Risk + Mitigation: Business Logic, Data Integrity, Security/Auth/Permission, Performance, Integration, Rollback / Operations, Testing / Verification. Nêu rủi ro mà không có mitigation là chưa xong việc.

## Pressure Scenarios

Bảng Scenario / Trigger / Expected Safe Behavior / Design Gap. Tình huống xấu cụ thể (mất mạng giữa giao dịch, hai người sửa cùng lúc, dữ liệu cũ thiếu field) và hệ thống nên xử sự thế nào.

## HIS-Specific Checklist

11 ô buộc phải xét: dữ liệu/riêng tư bệnh nhân, chăm sóc lâm sàng và dịch vụ lâm sàng, luồng bệnh nhân–nội/ngoại trú–điều dưỡng–dược–giường/khoa, tài chính–bảo hiểm–hóa đơn–thanh toán, ký số và hiệu lực văn bản đã ký, auth/session/permission/role, báo cáo–thống kê, integration ngoài, quản trị–lưu trữ–master data–audit trail, migration/rollback, vận hành bệnh viện và khả năng quan sát production. Tick = "đã xét", không phải "có ảnh hưởng".

## Risk Register

Bảng Risk / Severity / Likelihood / Trigger-Impact / Mitigation / Status với status open / mitigated / accepted. Rủi ro accepted là quyết định có chủ ý được ghi lại, không phải rủi ro bị bỏ quên.

## Verdict

GO (implement sau khi design được duyệt) / CAUTION (phải cập nhật design với mitigation) / STOP (sửa design hoặc đổi hướng) / NEED INFO (cần làm rõ trước khi implement).

## Required Design Changes Before Implementation

Danh sách thay đổi design bắt buộc. Rỗng thì ghi None.

## Required Design Changes Status

Applied/accepted in 03-design.md hay Still pending. Đây là chốt ngăn việc grill tìm ra rủi ro rồi vẫn implement theo design cũ.

## Consistency Check Against 03-design.md

Section nào của design phải đổi, mâu thuẫn nào còn lại, và Ready after grill: yes/no.

Nhật ký thi công. Mục đích duy nhất: để người review không phải đoán — đã sửa gì, chạy gì, lệch ở đâu.

## Design Reference

Trỏ về 03-design.md. Neo mọi thứ dưới đây vào một thiết kế đã được duyệt.

## Implementation Mode

default / continue (tiếp tục việc dở) / fix-review (chỉ sửa finding từ review) / no-test (không chạy test — phải có lý do và sẽ hiện ra ở review).

## Implementation Summary

Tóm tắt những gì đã làm, mức độ đủ để hiểu diff mà chưa cần mở diff.

## Files Changed

Bảng File-Module / Planned? / Purpose / Notes. Cột Planned? là điểm mấu chốt: mọi dòng no đều là file nằm ngoài design và phải giải thích được.

## Preflight Checks

Bốn điều kiện kiểm trước khi chạm code: design đã duyệt, finding của grill đã áp dụng/chấp nhận, review fix nằm trong scope (nếu --fix-review), và thay đổi cũ không liên quan trong working tree được giữ nguyên.

## Steps Executed

Bảng Design Step / File-Module / Description / Status với status done / pending / blocked. Ánh xạ 1–1 về Implementation Steps của design, nên thiếu bước là thấy ngay.

## Deviations From Design

Chỗ code khác thiết kế và vì sao. Lệch là chuyện bình thường; lệch không khai mới là vấn đề.

## Issues Encountered

Vấn đề gặp trong lúc làm, kể cả đã tự xử lý — thường là đầu vào cho task sau.

## Self-Review Before Handoff

Năm ô tự soát: khớp scope design, không vi phạm file ownership, không đổi public contract/workflow state ngoài kế hoạch, đã kiểm các đường dẫn HIS nhạy cảm, và side effect đã biết thì hoặc sửa trong scope hoặc log thành blocker.

## Verification Performed

Bảng Check / Command-Method / Result / Evidence-Risk với result pass / fail / not-run. Bắt buộc ghi lệnh thật đã chạy — not-run là câu trả lời hợp lệ, còn nói pass mà không có bằng chứng thì không.

## Remaining Work

Việc còn nợ. Rỗng thì ghi None, để phân biệt "đã hết việc" với "chưa ai điền".

## Ready For Review

Yes / No / Blocked — cửa ra sang h4-review. Script implementation-lint đọc section này.

Review có bằng chứng: đối chiếu với design đã duyệt, phân tầng findings, kiểm verification / secret / scope, rồi mới cho phép ship.

## Review Target

Mode, Source (diff, commit, MR, patch), Files/areas. Review không nêu rõ đang review cái gì là review không kiểm chứng được — và review-lint bắt trường hợp này.

## Review Inputs

Những gì đã đọc để review: 01-requirement.md, 03-design.md, 05-implement.md, và diff/status hiện tại.

## Plan Compliance

Bảng Requirement-Step / Status / Evidence với status PASS / MISSING / EXTRA / UNKNOWN. MISSING = design có mà code không có; EXTRA = code có mà design không có. Cột Evidence là bắt buộc, đây là phần "có bằng chứng" của review.

## Edge Case / Dependency Check

File/vùng đã đổi, các caller/workflow phụ thuộc đã kiểm, và Unmapped critical paths — đường đi quan trọng chưa soát được. Khai ra vùng mù thay vì im lặng.

## Stack Style Review

BE/FE có bị chạm không, style tương ứng đã kiểm chưa, finding từ các utility skill đã gộp vào chưa, và Style verification gaps.

## Summary

Kết luận ngắn dạng văn xuôi, đọc trước khi vào findings.

## Findings

Bốn tầng: Critical (chặn ship) → Major (phải sửa) → Minor (nên sửa) → Suggestions (tùy chọn). Critical/Major bắt buộc có Evidence, Impact, và Required route (h4-implement / h4-design / h4-requirement) — tức nói rõ phải quay về bước nào để sửa.

## Scope Check

Bốn ô: khớp design đã duyệt, không refactor ngoài lề, không có file bị đổi ngoài dự kiến, deviation đã được ghi/duyệt.

## Verification Check

Sáu ô kiểm bằng chứng: build/typecheck, test liên quan, file đã đổi được map với check tương ứng, manual smoke, edge case, và bug/repro gốc đã xác minh lại nếu là task bug. Cho phép "rủi ro được chấp nhận" nhưng phải nói ra.

## Secret/Sensitive Check

Bốn ô: không credential, không lộ dữ liệu production/bệnh nhân, không lẫn config máy cá nhân, không log nhạy cảm. Với HIS đây là kiểm bắt buộc, không phải hình thức.

## Verdict

Section gate. Approved for ship / Approved with minor notes → mở gate ship. Needs changes / Blocked → chặn ship.

## Required Fixes Before Ship

Danh sách phải sửa trước khi ship, thường ánh xạ từ Critical/Major. Rỗng thì ghi None.

## Handoff Recommendation

Đề xuất bàn giao: ship, sửa rồi review lại, hay quay về design.

Artifact terminal: tổng kết, checklist trước khi ship, commit message và mô tả MR đề xuất, cùng bản ghi phê duyệt git của người dùng.

## Ship Mode

handoff (chỉ giao lại, không chạm git) / commit / mr / dry-run (chuẩn bị đầy đủ nhưng không thực thi).

## Final Summary

Tóm tắt cuối cùng của cả task — thường là nội dung sẽ được tái dùng cho commit message và mô tả MR.

## Review Status

Trỏ về 06-review.md, ghi lại Verdict và Blocking findings. Đây là chỗ gate ship được kiểm: verdict không cho phép thì dừng tại đây.

## Files Changed

Bảng File / Purpose / Include?. Cột Include? quyết định file nào thực sự vào commit.

## Final File Set

Included, Excluded/unrelated, và Reason for exclusions. Ép việc loại file phải có lý do, thay vì git add . rồi hy vọng.

## Verification Summary

Tổng hợp bằng chứng kiểm chứng ở dạng có thể dán vào MR cho người review đọc.

## Accepted Risks / Follow-Ups

Rủi ro ship kèm có chủ ý và việc cần làm tiếp. Rỗng thì ghi None.

## Secret / Sensitive Check

Kiểm lần cuối trước khi dữ liệu ra khỏi máy: credential/token/password, dữ liệu production–bệnh nhân, config cá nhân, log/debug dump. Đây là kiểm cuối cùng còn kịp chặn.

## Git Consent / Operation

Section gate. Requested operation, User approval source (bằng chứng người dùng đã đồng ý), Executed action, Result. Không có approval source thì không có thao tác git — kể cả khi mọi checklist khác đã xanh.

## Suggested Commit Message

Commit message theo chuẩn HIS4: JIRA-ID | type(scope): mô tả kèm bullet chi tiết, và JIRA ID: known/unknown khi không suy ra được từ tên branch.

## Merge Request Draft

Bản nháp MR gồm Title, Description, Testing, Risk / Rollback — viết sẵn để người duyệt MR không phải đi tìm context.

## Pre-Ship Checklist

Tám ô cuối: review passed, không có dữ liệu nhạy cảm, không lẫn file ngoài lề, verification đã ghi hoặc rủi ro được chấp nhận, commit message sẵn, mô tả MR sẵn, người dùng đã duyệt thao tác git, và kết quả git đã được ghi lại nếu đã thực thi.

## Final Status

Handoff ready / Ready to commit / Ready to create MR / Shipped / Blocked.

## Completion / Recovery Route

Thay cho Next Step Recommendation, vì đây là artifact terminal: completed, await explicit git approval, hay quay về h4-review / h4-implement.