メニュー
PTX-EMU 项目经验沉淀 — 跨模块状态翻译、递归锁、分 Phase commit、基线 worktree、qualifier 类型判断等具体失败模式与可复用 checklist。来自 2026-06 barrier module 迁移 + 2026-07 cute_rmsnorm float 类型判断实战
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
SOC 職業分類に基づく
ADR 合规检查 — 开发完成后对照 ADR 检查清单验证实现是否符合架构决策
Implement tasks from an OpenSpec change. Use when the user wants to start implementing, continue implementation, or work through tasks.
Archive a completed change in the experimental workflow. Use when the user wants to finalize and archive a change after implementation is complete.
Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
PTX-EMU 专用调试技能 - 自动化调试配置选择和场景化调试方法
三模式 PTX 测试生成框架 — 从任意 CUDA 程序自动生成 PTX/IR/执行三种测试模式
| name | ptx-lessons-learned |
| description | PTX-EMU 项目经验沉淀 — 跨模块状态翻译、递归锁、分 Phase commit、基线 worktree、qualifier 类型判断等具体失败模式与可复用 checklist。来自 2026-06 barrier module 迁移 + 2026-07 cute_rmsnorm float 类型判断实战 |
| when_to_use | PTX-EMU 项目中遇到以下场景时强制使用： 实施新功能/重构前： - "迁移/重构现有函数"、"API 切换"、"重写 handler" - 涉及 ThreadContext / WarpState / Barrier / SIMT 栈的状态修改 - 涉及互斥量、锁、并发原语 - 涉及多 Phase 推进（OpenSpec change 实施） - 涉及类型系统修改（qualifier 解析、is_float/is_signed 判断） 调试失败时： - "测试在断言 N+1 处挂起" → 递归锁死锁 - "集成测试 is_blocked 失败" → 跨模块状态翻译缺失 - "测试套件整体超时" → 用 per-test timeout 定位 - "Phase N 通过但 Phase N+1 失败" → 分 Phase commit 纪律 - "E2E 测试输出非确定性但单元测试通过" → qualifier.back() 类型判断 bug 实施完成后： - 提交前必查：checklist D（AGENTS.md 同步、ADR 追加、commit message 列出 fix 编号） |
| skills_required | [] |
来源: 2026-06-18 commit
f033312(integrate-barrier-module-cta-warp) 实战 完整文档:docs/dev-process/lessons-learned.md互补文档:docs/dev-process/debugging-strategy.md（问题分类与快速验证）、.opencode/skills/ptx-barrier-mechanism/（领域知识）
任务是什么？
├─ 迁移/重构函数 → 查"Checklist A: 函数迁移"
├─ 重大重构前 → 查"Checklist B: 重构前"
├─ 写注释 → 查"Checklist C: 写注释"
├─ Commit 前 → 查"Checklist D: Commit 前"
└─ 调试失败 → 查"失败模式速查表"
问题模式: 迁移函数时漏掉看似冗余的 set_state(BAR_SYNC)，因为下一模块的 sync_to_warp_state() 才把它翻译为 is_blocked = true。没有这行，调度器死循环。
关键经验：
set_state 看似冗余（next_pc 已设），但它是另一模块的 API 契约诊断命令：
# 找出所有 set_state 调用点
grep -rn "set_state(" src/ptxsim/ include/ptxsim/ | grep -v "test"
# 找出所有读取 state 的位置
grep -rn "state == BAR_SYNC\|get_state()\|is_at_barrier" src/ptxsim/
# 比对：每个 set_state 应该有对应的翻译规则
修复模板（详见 debugging-strategy.md §"跨模块状态翻译检查"）：
} else {
// Mark thread as waiting at <event> so the executor (<file>:<line>)
// recognizes <STATE> and skips re-execution. Without this,
// sync_to_warp_state() keeps is_<field>=false and the scheduler
// spins on the instruction. (Mirrors legacy <old-code> at <file>:<line>.)
context->set_state(<STATE>);
context->set_next_pc(context->get_pc());
}
问题模式: arrive() 持 mutex_ 后调用 is_complete()，后者再次 lock_guard(mutex_)。std::mutex 不可重入 → 死锁。
关键经验：
诊断命令：
grep -n "lock_guard\|unique_lock" <file> # 列出所有锁点
grep -B2 "lock_guard" src/ | grep -A1 "lock_guard" # 找出嵌套锁
修复模式：
// 方案 A：拆分两个版本
class Foo {
bool is_complete_unsafe() const; // 假设已持锁
bool is_complete() const { // public 持锁
std::lock_guard lock(mutex_);
return is_complete_unsafe();
}
};
// 方案 B：内联（最小改动）
bool arrive() {
std::lock_guard lock(mutex_);
arrived_threads_.insert(thread);
bool complete = arrived_threads_.size() >= expected_threads_; // 直接比较
}
关键经验：
判定"Phase 完成"的标准：
关键经验：
实测验证: worktree 里 nvcc + CUDA 编译完全正常（实测 baseline worktree 中 e2e_barrier_warp_sync PASS 0.53s）。env.sh 是路径无关的（NVCC_PATH=$(which nvcc)），不依赖固定路径。
标准操作：
# Step 1: 建立 baseline（全量 build 预算 15-20 分钟）
git worktree add .worktrees/baseline-check <baseline-commit>
cd .worktrees/baseline-check
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc) # 必须全量！否则部分 target 找不到
# Step 2: 验证 baseline 通过
cd build && ctest -L <label> --output-on-failure
# Step 3: 对比 main
cd <main-build> && ctest -L <label> --output-on-failure
# Step 4: 清理（实施完成且验证通过后）
git worktree remove .worktrees/baseline-check
⚠️ 三个常见陷阱:
.git 但 build 独立（同一时刻不能在两个 worktree 切到同一分支）时间预算:
问题模式: TypeUtils::is_float_type() 只检查 qualifiers.back()。PTX 解析器生成的 qualifier 列表中 Q_F32 不在末尾（如 {Q_U32, Q_S32}），导致 mul.f32 等所有 float 指令被当作整数处理 → 64 位整数乘积写入 32 位浮点寄存器 → 非确定性垃圾输出。
关键经验：
qualifiers.back() 是脆弱的类型判断 — 最后一个元素可能是数据类型、内存空间或修饰符{Q_F32}，PTX 解析器生成的是多元素列表诊断命令：
# handler 入口注入临时代码确认 is_float 标志
# 在 executeOperation 中打印 qualifiers 列表
grep -rn "is_float_type" src/ptxsim/ # 列出所有受影响 handler
grep -rn "qualifiers.back()\|\\.back()" src/ # 检查其他脆弱的 back() 使用
修复模板：
// BEFORE (buggy): 只检查最后一个
bool is_float_type(const auto &qualifiers) {
return !qualifiers.empty() &&
(qualifiers.back() == Q_F32 || qualifiers.back() == Q_F64);
}
// AFTER (correct): 遍历所有 qualifier
bool is_float_type(const auto &qualifiers) {
for (const auto &q : qualifiers) {
if (q == Q_F32 || q == Q_F64 || q == Q_F16 || q == Q_BF16)
return true;
}
return false;
}
问题模式: 实施 OpenSpec change 时，工作区修改了 openspec/changes/<name>/{design.md,tasks.md,spec.md} 反映实施调整，但这些 artifacts 修改从未 git add — 仅源码 + commit message 描述了改动。fast-forward merge 后，OpenSpec 状态与代码不一致，需 commit reconstruct 补救。
触发场景: cleanup-deprecated-barrier-apis (2026-06-20) — 3 个实施 commits (8a5573d/7914764/6ec8efd) 合并时未追踪 artifacts；12 天后 (barrier-migration-amendment 2026-07-02) 基于 untracked reconstructed artifacts 误判 4 条 P0-A 为 active debt。
关键经验：
git add openspec/changes/<name>/ + commit "docs(openspec): design adjustments" (artifacts FIRST)git status + git log -- <path> 验证fix-*/refactor-* change + Ref: archive/<date>-<name>/，不要 amend 已归档 change诊断命令：
# 验证 change 是否已归档
git log --all --oneline -- "openspec/changes/<change-name>/"
# 应包含 archive commit（如 ded4f96 chore(openspec): archive ...）
# 验证 artifacts 是否 tracked（实施后必须）
git ls-files openspec/changes/<change-name>/
# 不应为空
# 审计前自检
git status openspec/changes/ # 未提交修改警告
真实案例:
barrier-migration-amendment (2026-07-02) — 试图 amend 已于 2026-06-20 归档的 cleanup-deprecated-barrier-apis.opencode/notes/debt-audit-2026-07-02.md §1.1 P0-A1~A4 误标为 active debt — 实际已通过 commits 8a5573d/7914764/6ec8efd 解决修复模板：
# 1. 删除 obsolete untracked dirs
rm -rf openspec/changes/<obsolete-amendment>/ openspec/changes/<already-archived-as-reconstructed>/
# 2. 更新 debt audit 标记为 RESOLVED
# docs/audits/<audit>.md §1.1 添加"状态"列 + 引用 commits
# 3. 沉淀 lesson
# docs/dev-process/lessons-learned.md 添加新条目（按现象/教训/检查工具/真实案例结构）
# .opencode/skills/ptx-lessons-learned/SKILL.md 添加 §核心经验 + Checklists E/F/G
真实案例: fix-cvt-strategy-actual-split（commits e8db807/f3ef891/43edf55，2026-07-05）原 6-Phase 计划基于错误前提：
fc3c352/9837d44/d6123e0）.worktrees/fix-pre-p0-baseline 可复用 → 实证：worktree 目录为空select_strategy() 返回 unique_ptr → 实证：返回 const ConversionStrategy&关键经验：
git log -- <file> + grep <api> + wc -l <file>，禁止用"存在/未存在"推断状态docs/dev-process/lessons-learned.md §20fix-* change + Ref: archive/<date>-<name>/（与 §6 互补）诊断命令：
# 1. 验证 proposal 引用的 API 真实存在
grep -rn "<symbol>" src/ include/ tests/
# 2. 验证 oracle 测试数量真实
ctest -N -L "<label>" 2>&1 | tail -5
# 3. 验证提到的工作目录/路径/工具真存在
ls <worktree-path> 2>/dev/null
test -f <path> && echo exists || echo missing
# 4. 列出 baseline 文件的关键状态
wc -l <file>
git log --oneline -10 -- <file>
git log --all --oneline -- "<change-dir>"
修复模板：
问题模式: 实施 feat-*/implement-* change 并归档后，根 README.md 仍描述 stale 状态（如 "WMMA 是 stub"）。新开发者读根 README 找方向，错误描述会立即误导。
关键经验：
stub / TODO / FIXME / 硬编码百分比 应为空）诊断命令：
# Archive commit 前必跑
grep -n "stub\|TODO\|FIXME\|不实现\|未完成" README.md
grep -nE "[0-9]+%|第[一二三]" README.md # 硬编码数字
grep -n "进行中\|完成" README.md # 状态描述
修复模板：
# 新建 sync-* change（不 amend 已归档 change）
git checkout -b docs/sync-readme-after-<feature>
# 4 Phase: artifacts → 修订 → 3 README Fix #1-#3 → 归档
# 详见 docs/dev-process/lessons-learned.md §21 完整案例
真实案例:
sync-readme-after-tcgen05（commits 8427829/80271cd/91aeef2/4b8cb6b/746d083/cee527f，2026-07-05）问题模式: 在 src/grammar/ptxLexer.g4 新增 TOKEN : 'bare_string' 时，如果 bare_string 字符串只含 [a-zA-Z_0-9$]（即匹配 ID : [a-zA-Z_$][a-zA-Z_0-9$]*），ANTLR4 lexer 平局规则（first-defined-wins）会让 TOKEN 抢占 ID。所有以 bare_string 为寄存器名/变量名的 PTX 全部解析失败。
关键经验：
.foo（带点前缀）就用点前缀；能用 lexer mode 隔离就用 lexer mode；能不定义新 token 就不定义cp bench/cute/*.ptx tests/ptx/regression_*.ptx 跑 ./tests/ptx/test_all_ptx.sh诊断命令：
# 1. 列出所有 bare string lexer tokens
grep -nE "^\w+\s*:\s*'[a-zA-Z]" src/grammar/ptxLexer.g4
# 2. 对每个 bare token，验证字符串模式与 ID 规则冲突
grep -A1 "^[A-Z_]\+\s*$" src/grammar/ptxLexer.g4 | grep -E ":\s*'[a-zA-Z_][a-zA-Z_0-9_]*'"
# 3. lexer 修改后用真实 kernel PTX 验证
cp bench/cute/cute_rmsnorm.ptx tests/ptx/regression_cute_rmsnorm_f16_register.ptx
bash ./tests/ptx/test_all_ptx.sh
真实案例:
commit ad808e3（fix(grammar): resolve tcgen05 LL() prediction conflict）引入 TCGEN_F16 : 'f16' + TCGEN_BF16 : 'bf16' 抢占 ID → 5 ctest 失败（cute_rmsnorm/simpleGEMM 等）+ 7 tcgen05 fixture LL() 失败55e216a）：5 行 lexer/parser diff — 删除 bare tokens + parser tcgen05Qual 加 ID fallback + tcgen05Dtype 用 dot-prefixed F16/BF16e92f1c1）：tests/ptx/regression_cute_rmsnorm_f16_register.ptx（含 8 个 %f1N 寄存器名）→ 47/47 PASS问题模式: tcgen05_fragment_mma_f16(Tmem&) helper 假设调用方保证 single-warp 执行。FlashAttention 多 warp 协作时 c_slot = 64 + lane_id 让 warp 0 和 warp 1 都写 slot 64 → 数据竞争。
关键经验：
[SINGLE-WARP ASSUMPTION]SMContext(1 warp, 32, 1 cta) 是 single-warp 测试，多 warp 必须独立测试诊断命令：
grep -rn "single-warp\|one warp at a time\|sequential execution" src/ include/
真实案例: fix-tcgen05-mma-accumulator-and-f32-storage Oracle 2026-07-11 审计 C4 BLOCKER
问题模式: TcQueue::wait() 先 push 到 pending_waiters_ 再检查 counter，导致 commit→wait 序列后 pending_count() 返回 1（waiter 仍在 list 中）。
关键经验：
pending_count() == 0 断言暴露此问题诊断命令：
grep -n "wait\|pending_waiters_" src/ptxsim/async/tc_queue.cpp
真实案例: fix-tcgen05-mma-accumulator-and-f32-storage Phase 1 B2 test 暴露
问题模式: Helper 改 c_frag 为 float 后 readback 站点未同步迁移，f32 bits 被当 f16 bits 读 → 垃圾值（silent corruption）。
关键经验：
grep "c_buf[idx * 2]" tests/ 是 readback 残留快速检测Catch::Approx 默认 epsilon 对 storage format 错误不敏感诊断命令：
grep -rn "f16_to_f32\|c_buf\[idx \* 2\]" tests/integration/tcgen05/
grep -n "f32_to_f16" src/ptxsim/instructions/tcgen05_helpers.cpp
真实案例: fix-tcgen05-mma-accumulator-and-f32-storage Phase 2 readback 漏改
问题模式: extractQualifiersFromContext 只映射 terminal token 到 Qualifier enum，IMMEDIATE 节点被 tokenToQualifier 返回 Q_UNKNOWN 后静默丢弃。instr.cta_group 永远 defaults to 1。
关键经验：
诊断命令：
grep -n "Q_UNKNOWN" src/ptx_parser/ptx_visitor.cpp
grep -rn "extractQualifiersFromContext" src/
真实案例: fix-tcgen05-mma-accumulator-and-f32-storage Oracle 2026-07-11 审计 C3 BLOCKER
问题模式: step_b_set_blocked_cycles 注释承诺 "All three nullptr = use existing InstructionLatencyTable only"，但实现中 nullptr 路径fallthrough 到 getLatency() + set_blocked_cycles_for_active()--这是 exe_once() 历史上从未有过的行为（blocked_cycles 设置此前仅 LdHandler 路径）。注释承诺 no-op，实现未兑现。
关键经验：
is_tensor_core_instruction 等 helper 一致）诊断命令：
# 1. 查找所有 "byte-identical" / "no-op" 契约注释
grep -rn "byte-identical\|no-op\|nullptr = " src/ptxsim/ include/ptxsim/
# 2. 对每个 no-op 契约，验证是否有测试锁定
grep -rn "no-op\|byte-identical" tests/
# 3. 验证 file-local 函数可测试性（匿名命名空间 = 不可直接测试）
grep -B2 "namespace {" src/ptxsim/core/*.cpp
修复模板：
// BEFORE (buggy): 注释承诺 no-op，但 nullptr 路径 fallthrough
inline void step_b(IPipeline* p, ITc* tc, Warp* w, const Stmt& s) {
// nullptr = byte-identical fallback <-- 注释承诺
uint32_t latency = 0;
if (p) { /* ... */ }
if (latency == 0 && tc) { /* ... */ }
if (latency == 0) latency = getLatency(s); // <-- nullptr 时也执行！
if (latency > 0) w->set_blocked_cycles(latency);
}
// AFTER (fixed): 显式 early return + 测试锁定
inline void step_b(IPipeline* p, ITc* tc, Warp* w, const Stmt& s) {
if (!p && !tc) return; // both nullptr = no-op (TESTED)
// ... priority chain ...
}
// + 4 个单元测试覆盖 4 条分支（both nullptr / pipeline / tc / fallback）
真实案例:
commit 367fd6a5 (feat) 引入 step_b_set_blocked_cycles，声称 "0 regression"commit 5b292a91 (fix) 修复回归：unit_simt_integration 2 个断言失败（pc_groups_after == 1 got 0, threads[0].pc == 1 got 0）tests/unit/sm/test_step_b_set_blocked_cycles.cpp 4 个 case 直接锁定 4 条分支□ 列出 baseline 函数中所有的 set_* / commit_* / force_* 调用
□ 列出所有 mutex_ / lock_guard / unique_lock 使用
□ 对每个 set_*，grep 其值的下游消费者
□ 对每个锁点，确认"持锁方法调用的所有其他方法"也持同一锁，或重写为无锁版本
□ 比对行级 diff（不只比对主要逻辑）
□ 对所有 GenericPipelineHandler 子类，验证 is_float/is_signed 遍历全部 qualifier 而非只看 back()
□ 比较 helper 输出 dtype 与所有 readback 模式（f16 storage → f16 readback；f32 storage → memcpy readback）
□ 检查 helper body 内部是否残留旧 dtype 转换（f32_to_f16 / f16_to_f32）
□ 建立基线 worktree
□ 列出本 change 的所有 Phase，决定 commit 粒度
□ 决定哪些 Phase 需要基线对比（涉及 invariant 的一定要）
□ 准备 revert 策略：每个 Phase 独立 commit，失败立即 revert
□ 实施前 grep "f16\|f32" 在 helper 和所有 readback 站点，记录迁移清单
□ 这条注释能否让 3 个月后的陌生人避免犯同样的错？
□ 是 → 写
□ 否 → 不写
□ 例外：警告"不要做 X"必须写
□ 跑过 baseline worktree 对比
□ AGENTS.md 是否需要同步
□ ADR 是否需要追加
□ OpenSpec tasks.md 是否需要更新
□ commit message 列出独立的 fix 编号
□ 所有 OpenSpec artifacts (design.md / tasks.md / spec.md / proposal.md) 已 git-tracked
- 验证：git ls-files openspec/changes/<name>/ 不应为空
□ commit message 列出独立 fix 编号（如 Fix #1, Fix #2）
□ 每个 commit 独立可 revert（git revert HEAD 后编译通过）
□ 实施 commits 合并后立即 git-tracked artifacts（避免 working tree 遗漏）
□ 归档前 grep 验证 artifacts 与代码一致（无过期 task 编号）
□ 审计前 git log --since=<audit-date-1> -- <path> 验证所有引用 change 的实施状态
- 验证：git log --all --oneline -- openspec/changes/<change-name>/ 不应仅含 archive commit
□ 引用 commit hash 而非文件路径
- 示例："P0-A1 RESOLVED by commit 8a5573d" 而非 "P0-A1 当前 design.md 已修复"
□ 区分 "active debt"（影响实施）vs "stale debt"（已解决但审计未更新）
□ 每次审计标注 "基于 HEAD <hash>" 而非 "当前状态"
□ 审计撰写时若 working tree 与 git HEAD 不一致，必须明确标注：
- "基于 working tree 状态，可能与 HEAD 不一致"
□ Proposed: 未实施，artifacts 可修改
□ Accepted: 已批准实施，artifacts 可修改但需说明理由
□ Active: 实施中，artifacts 可修改（带 progress 标记）
□ Archived: 终态，artifacts 不可修改
- 若需修补 → 新建 fix-* / refactor-* change
- 引用方式：Ref: archive/<date>-<change-name>/
- 禁止 amend 已归档 change（违反 OpenSpec 生命周期）
□ 实施 OpenSpec change 前：调用 Metis - Plan Consultant 子代理
- 提供 4 个 artifacts 路径 + 真实文件路径/行号引用要求
- 要求输出：Hidden Intentions / Ambiguities / AI Failure Points / Missing Context
- 要求给出 GO / ⚠️ CONDITIONAL / ❌ NO-GO 决策
□ Metis 输出 ⚠️ CONDITIONAL 时：5 项 MUST-RESOLVE 全部完成才能 apply
□ 验证 proposal 的关键假设（实证）：
- wc -l 验证声称的"X 行"真实存在
- git log 验证 archive 中的"已实施 commits"真存在
- grep 验证引用的 API 真存在（0 matches = 假设错误）
- ctest -N 验证 oracle 数量（如 94 → 14 是常见偏差）
- ls 验证 worktree/路径真存在（空目录 ≠ "可复用现有"）
□ 区分"已实施但未清理" vs "未实施"（4 类表象对照 §20）
□ "重大功能交付" = 代码 + 单元测试 + e2e + 根 README 同步（4 项缺一不可）
□ 实施阶段：根 README.md "状态" / "已知限制" 章节随代码同步更新（不延后到 archive）
□ Archive commit 前 grep 验证：
- grep -n "stub\|TODO\|FIXME" README.md 应为空（或有明确 TODO + 修复 plan）
- grep -n "进行中\|完成" README.md 应与 docs/README.md Phase 表格一致
- grep -nE "[0-9]+%|硬编码" README.md 应替换为自动统计链接
□ 任何 feat-*/implement-* change 归档前必跑本 checklist
□ 新 sync-* / fix-* change 处理已归档案例：通过 Ref 链接 + 不 amend（per Checklist G）
□ postmortem 沉淀：追加 lessons-learned.md §N（本 checklist 是 §21 模板）
□ 4 个 artifacts 范围数字对齐（proposal/design/tasks/spec 同一债务项的对象列表一致）
- 示例：D-5 删除范围 = 3 个活跃 + 1 个已禁用副本（4 个）必须 4 个 artifact 同时出现
□ design Decision 路径示例与 spec Scenario 路径描述一致
- design 写 "archive/<name>.design.md"（与子目录并列）→ spec 写"同级创建" → 一致 ✓
- design 写 "archive/<name>/design.md"（在子目录内）→ spec 写"git hash 不变" → 冲突 ❌
□ design Decision 操作与 spec Scenario 操作描述一致
- design 写"添加 README.md 段落" → spec 写"任何文件 git hash 不变" → 冲突 ❌
- design 写"禁止修改归档" → spec 写"git hash 不变" → 一致 ✓
□ tasks 验证命令路径 = design 路径示例
- tasks Phase 2.6 写 `test -f $d/design.md` 但 design 写 `$d.design.md` → 不一致 ❌
□ tasks 中"验证归档未变"任务存在（git status openspec/changes/archive/<name>/）
□ 范围模糊时优先严格约束（"完全不修改归档" > "修改归档 README"）
□ 审查产物登记到 `.opencode/notes/<name>-review-report.md`（≥30 commits 影响范围）
□ 沉淀到 lessons-learned.md §23（§23 是本 checklist 的真实案例模板）
□ Retroactive artifact 合成：≥3 共享模板 → 1 个 subagent（共享上下文 + 模板一致性）
- 反例：N 个并行 subagent 各自维护模板 + commit hash 验证重复 N 次
□ Inline edit 策略：每个 ERRATA 项 1 个 edit，保留原文不变 + inline 注释
- 每个 edit 前 Read 验证精确字符串 → Edit 仅追加 `[勘误 ...]` → 不修改原文
- 验证：diff <(git show HEAD~1:file | grep -v '勘误') <(git show HEAD:file | grep -v '勘误')
□ git rm + .gitignore 盲区：tracked 删除后 untracked 子目录残留
- 流程：git rm -r <dir>/（删 tracked）→ find <dir> -type d 检查残留 → rm -rf <untracked-subdir>
- 替代：git clean -fdn <dir>/（dry-run）→ git clean -fd <dir>/（不可逆，慎用）
□ 修改前：
□ 列出 lexer 中所有 bare string tokens：grep -nE "^\w+\s*:\s*'[a-zA-Z]" src/grammar/ptxLexer.g4
□ 验证每个 bare token 字符串不与 ID 规则冲突（不能只含 [a-zA-Z_0-9$]）
□ 如有冲突，必选其一：点前缀 / lexer mode / 删除冗余 token
□ 修改后必跑 TDD 流程（per ptx-grammar-modification skill）：
□ RED：建立 baseline（git bisect / 5 个 ctest 失败列表）
□ 复制 bench/cute/*.ptx → tests/ptx/regression_*.ptx 真实 kernel guard
□ GREEN：实施 lexer/parser 修改 + cmake --build build --target GenerateParser
□ REFACTOR：./tests/ptx/test_all_ptx.sh 47/47 + ctest 全绿
□ Commit 顺序：fix(grammar) → test(ptx) regression guard → docs(dev-process) lesson
□ Commit message 引用 ad808e3（引入回归 commit）+ ADR-0016（架构依据）+ §25（lesson）
| 症状 | 最可能原因 | 诊断命令 |
|---|---|---|
| 集成测试断言 N+1 处挂起 | 递归锁死锁 | grep -n "lock_guard|unique_lock" <file> |
CHECK(!is_blocked) 类似断言失败 | 跨模块状态翻译缺失 | grep "set_state.*BAR_SYNC" src/ 对比 grep "state == BAR_SYNC" src/ |
| 调度器在 barrier 指令处死循环 | set_state(BAR_SYNC) 漏掉 | grep "set_state" src/ptxsim/instructions/barrier.cpp |
| 分歧场景一半 lanes 卡住 | 屏障释放逻辑覆盖了已释放 lanes | 检查 set_active_mask 是否 OR 而非 overwrite |
| Phase N 通过但 Phase N+1 失败 | 跨 Phase invariant 冲突 | 用基线 worktree 隔离每个 Phase |
git revert 后 git status 异常 | stash/pop 改变了 staged 状态 | git status 验证 + 必要时 git reset |
| 注释"看似冗余" | 跨模块间接状态翻译 | 查"经验 1"，看是否需要保留 |
ctest -L <label> 整体超时 | 某个测试死锁 | 切到 single-test + per-test timeout |
| E2E 测试输出非确定性（每次不同值），但 handler 单元测试通过 | is_float_type() 只看 qualifiers.back()，Q_F32 不在末尾时被误判为整数 | handler 入口加 printf: is_float 标志；grep "is_float_type" src/ptxsim/ 列出受影响 handler |
| OpenSpec 4 个 artifacts 单独看 OK 但 apply 后行为不一致 | proposal/design/spec/tasks 间存在内部冲突（范围数字 / 路径策略 / 操作语义） | 运行 Checklist J：4 个 artifacts 同债务项范围对齐 + design Decision 路径 vs spec Scenario 路径一致 + tasks 验证命令 = design 路径示例 |
| Retroactive artifact 模板不一致 / commit hash 漏掉 | 5 个并行 subagent 各自维护模板 + commit 验证重复 | N≥3 共享模板 → 1 个 writing subagent 一次性合成（共享上下文 + 模板一致性自然保证） |
| Inline 标记后原文被意外修改 / ERRATA 合并破坏快照 | Edit 操作未用 Read 验证精确字符串 | 每个 Edit 前 Read 验证目标段落精确内容 → Edit 仅追加 inline → diff grep -v '勘误' 验证原文未变 |
git rm -r 后 untracked 子目录残留文件系统上 | .gitignore 规则使子目录 untracked，git rm 不处理 | git rm -r <dir>/ 后 find <dir> -type d 检查残留 → rm -rf <untracked-subdir>；或 dry-run git clean -fdn 后 git clean -fd |
ANTLR 解析错误：mismatched input 'f16' expecting ID | lexer 中 bare string token（如 TCGEN_F16 : 'f16'）抢占 ID 规则 | grep -nE "^\w+\s*:\s*'[a-zA-Z]" src/grammar/ptxLexer.g4 列出 bare tokens；用点前缀（.f16）或 lexer mode 隔离 |
| 声称 "X/X PASS" 但 ctest 失败（如 5 个 cute_rmsnorm/simpleGEMM 等） | grammar 修改未用真实 kernel PTX 验证（"自证"测试漏掉真实场景） | 修改后必跑 ./tests/ptx/test_all_ptx.sh + 复制 bench/cute/*.ptx 到 tests/ptx/regression_*.ptx |
| Kleene star 预测冲突 + 寄存器解析失败同时发生 | lexer 错位 — bare token 抢占 ID rule 同时影响 qualifier 与 register 解析 | 优先检查 lexer 是否有 bare token；删除/加前缀一次性解决多类问题 |
多线程单元测试 th.join() 后 REQUIRE 未触发 | deadlock 时 join() 永久阻塞；elapsed 测量 post-join，bug 实际是 60s 软超时而非 30s 检测 | std::async(std::launch::async, ...) + future.wait_for(30s) 返回 future_status::timeout 时主动 REQUIRE(false, "deadlock") |
TmemAllocator read-only methods (is_allocated_start/is_allocated/active_allocation_count/total_allocated_slots) 声称 "safe under concurrent erase" 但实际是 UB | std::map::find 与 std::bitset::test 在并发 erase/set 下 UB（C++17 只保证迭代器不失效，不保证并发安全） | 所有 public methods 一致加 lock_guard(mu_)；或用 static_assert 强制设计时一致性 |
Tcgen05OpKind::MMA_WS dispatch branch 写好但真实 PTX 永远不进 | grammar 把 .ws 当作 Q_TCGEN_WS qualifier 在 MMA sub-op 上（不是独立 MMA_WS sub-op），所以真实 PTX 始终 op_kind=MMA + qualifiers={Q_TCGEN_WS, ...} | 写新 dispatch 前 grep grammar（ptxInstructions.g4:tcgen05SubOp）确认 sub-op 真存在；否则在 handler 内部做 qualifier scan + 路由 |
Spec/Design 用了 .warpspecialized::1 词汇但 grammar 实际只有 .ws（裸 token） | PTX spec 用了修饰符语法（.warpspecialized::N）vs grammar 简化为裸 token（.ws），两者词汇脱节 | **设计阶段必跑 `grep -nE "warpspecialized |
Tcgen05Instr 便捷字段（cta_group/dtype/num_regs/has_block_scale）全是默认值 | visitor visitTcgen05Inst 只填 op_kind/qualifiers/operands/instructionText，这些字段从不被赋值 | handler 检查前 grep -n "Tcgen05Instr" include/ptx_ir/statement_context.h + grep visitor 验证 visitor 是否真的提取这些字段；否则改用 instr.qualifiers 扫描对应 qualifier token（如 Q_TCGEN_CTA_GROUP/Q_F16） |
| mma 累加后 C slot 是 1× 而不是 2× golden | helper sum=0 从不读取 c_slot | grep "sum = 0|sum=0" src/ptxsim/instructions/tcgen05_helpers.cpp |
tc_queue().pending_count() == 0 在 commit→wait 后失败 | wait() push 顺序问题 | grep -n "pending_waiters_.push" src/ptxsim/async/tc_queue.cpp |
| Helper 改 f32 storage 后 readback 返回 garbage | readback 仍是 f16 pattern | grep "f16_to_f32|c_buf\[idx \* 2\]" tests/ |
instr.cta_group 永远是 default 1 | visitor 不提取 IMMEDIATE | grep "extractQualifiersFromContext" src/ |
| OpenSpec 阶段 | 使用此 skill 的方式 |
|---|---|
openspec-propose（设计阶段） | 强制调用本 skill 的 "Checklist A" 验证函数迁移完整性 |
openspec-apply-change（实施阶段） | 强制调用本 skill 的 "Checklist D" 提交前验证 |
openspec-archive-change（归档阶段） | 自动 prompt 询问"是否生成 postmortem"，引用 ADR 追加段落 |
adr-compliance-check（合规检查） | 自动 cross-check 本 skill 的失败模式速查表 |
新经验的加入流程:
- 在实施中发现 bug 模式
- 修复后，写入本 skill +
lessons-learned.md+ 相关 ADR postmortem- 同步更新相关 skill（如
ptx-barrier-mechanism涉及屏障问题时）- 在
skills/README.md更新调用关系图
本 skill 与
lessons-learned.md的关系:
- 本 skill: agent 主动加载，提供快速决策树 + checklist + 速查表
- lessons-learned.md: 完整文档（具体案例、代码片段、长篇解释）
- 互补关系: 加载 skill 后能快速判断"我遇到了哪类问题"，再 deep-dive 到 lessons-learned.md 看完整案例
docs/dev-process/lessons-learned.md（16 章节，~600 行）docs/dev-process/debugging-strategy.md（含"跨模块状态翻译检查"章节）docs/adr/0008-barrier-semantics.md §2026-06-18 Postmortemdocs/superpowers/plans/2026-06-18-integrate-barrier-module-cta-warp-fix.md.opencode/skills/ptx-barrier-mechanism/、.opencode/skills/ptx-instruction-pipeline/.opencode/skills/state-modification-audit/（与本 skill 经验 1 配套使用）.opencode/skills/regression-bisect/（与本 skill 经验 3-4 配套使用）