Prompt file imported from wollfoo/ncs-gpu (
.windsurf/workflows/reproducibility-runbook.md). Copyright stays with the author.
Reproducibility Runbook
Goal: Ensure all results are reproducible by controlling environment, seeds, versions, and the command trail.
References:
rules/global-rules.md(Required outputs; evidence-first)rules/environment-profile.md(Windows/PowerShell; bounded outputs; restricted network; set Cwd, no inlinecd)rules/tool-calling-override.md(sequential-only, one tool per step; no tool+reply same step)rules/tool-preambles.md(Goal/Plan/Progress/Summary for each tool call)rules/reasoning-effort.md(điều chỉnh độ sâu lập luận – depth control)rules/context-gathering.md,rules/context-understanding.md(early-stop, low tool budget, citefile:line)rules/persistence.md(không bàn giao sớm – do not hand back early)rules/memory_tool_usage_guide.md(search trước store; data safety; redaction)rules/swe-bench.md(thorough verification, edge-case coverage)
Preconditions
- Objectives, scope, success/stop criteria rõ ràng.
- Environment: OS/shell (Windows/PowerShell), working directory (Cwd), network policy (restricted), output cap.
- Data/resources/licenses sẵn sàng; quyền truy cập hợp lệ.
- Seeds xác định và nhất quán trên toàn pipeline.
- Tool budget: ≤ 2 calls cho tác vụ nhỏ; escalate khi cần (theo
reasoning-effort.md). - Rủi ro/safety: phân loại safe vs unsafe (theo
environment-profile.md); chuẩn bị rollback. - Observability: kế hoạch log/traces; chỉ số xác nhận (hash, size, metrics).
When to use
- Trước khi chạy chuỗi lệnh phức tạp cần tái lập 100%.
- Trước/Sau khi áp patch hoặc thay đổi rủi ro cao.
- Trước khi công bố kết quả hoặc chuyển giao giữa môi trường.
Procedure
- Preamble
- Restate goal + outline sequential plan (tuân thủ
tool-preambles.md).
- Restate goal + outline sequential plan (tuân thủ
- Environment Baseline
- Ghi nhận OS, shell, Cwd, policy mạng, giới hạn output.
- Ví dụ (PowerShell):
Get-Location $PSVersionTable.PSVersion Get-ChildItem Env: | Select-Object -First 10
- Versions & Tools
- Ghi phiên bản công cụ quan trọng (bounded output). Ví dụ (nếu có):
git --version,node --version.
- Ghi phiên bản công cụ quan trọng (bounded output). Ví dụ (nếu có):
- Seeds & Determinism
- Chọn SEED cố định; bật cờ deterministic (nếu có); ghi rõ nơi set seed trong pipeline.
- Dependency Pinning
- Khoá phiên bản/lockfile; lưu manifest phiên bản; tránh cài đặt mạng nếu chưa được duyệt.
- Data & Inputs
- Liệt kê input và checksum (SHA256) để đảm bảo không đổi.
Get-FileHash -Algorithm SHA256 .\path\to\input.ext
- Liệt kê input và checksum (SHA256) để đảm bảo không đổi.
- Command Log
- Ghi tuần tự lệnh + tham số + Cwd cho mỗi bước; đảm bảo replayable, bounded outputs.
- Artifact Registry
- Liệt kê output (đường dẫn, kích thước, checksum nếu cần) để kiểm chứng không drift.
- Multi-run Verification
- Chạy lại ≥2 lần cùng SEED; kỳ vọng kết quả bitwise-identical hoặc trong ngưỡng chấp nhận.
- Cross-env Drift Check (tuỳ chọn)
- Nếu khả thi, kiểm tra trên môi trường khác; ghi nhận khác biệt (nếu có).
- Final Verification
- Replay toàn bộ command log; so khớp checksum/metrics với lần đầu.
- Archival
- Lưu runbook, logs, seeds, manifest, registry để truy vết dài hạn.
Constraints
- Sequential-only: một tool call mỗi bước; không tool+reply trong cùng step (
tool-calling-override.md). - Bounded outputs: giới hạn số dòng/ký tự; trích dẫn
file:linekhi tham chiếu repo. - Environment: set Cwd thay cho
cd; tránh network/state mutation nếu chưa có phê duyệt (environment-profile.md). - Windows/PowerShell: chú ý quoting; không dùng lệnh gây side-effect khi auto-run.
Success metrics
- Log lệnh có thể replay end-to-end; kết quả trùng (checksum/metrics) qua các lần chạy.
- Environment summary đầy đủ; seeds/lockfile/manifest được ghi nhận.
- Không dùng network/stateful commands nếu chưa được duyệt; tuân thủ tool budget.
- Có trích dẫn
file:linekhi viện dẫn nội dung repo.
Stop criteria
- Tất cả tiêu chí Success đạt và xác minh chéo qua multi-run.
- Hoặc bị chặn bởi yêu cầu network/ngoài phạm vi cần phê duyệt.
Anti-patterns
- Thiếu seed/lockfile; log không tuần tự; output không bounded; không có checksum.
- Dùng
cdinline; gọi nhiều tool song song; chạy cài đặt mạng không phê duyệt. - Hướng dẫn mơ hồ, không thể tái lập; thiếu trích dẫn bằng chứng.
Examples
- Good: Ghi seed, pin deps, hash input/output, replay thành công 2 lần cùng kết quả.
- Bad: Chạy mỗi lần ra kết quả khác nhau, không seed, không lưu manifest.
Templates
- Run header: mục tiêu, seed, Cwd, versions (tóm tắt), policy mạng, tool budget.
- Step template: Mô tả → Lệnh (nếu có) → Kỳ vọng → Log/Hash → Ghi chú drift.
Quick Checklist
- Goal/Plan rõ ràng; [ ] Seeds cố định; [ ] Deps pinned; [ ] Hash inputs/outputs
- Command log tuần tự (bounded); [ ] Không network nếu chưa duyệt; [ ] Cite
file:line - Multi-run verification; [ ] Lưu registry + manifest + report
Deliverables
- Environment summary (key versions), seeds, and dependencies.
- Ordered command log that can be replayed.
- Artifact list and confirmation of successful reproducibility.
