ethanreedlabs/sulde/writing-task-md

协调端写 task md 完整规则

真值来源:协调端项目 CLAUDE.md §给终端写指令规则迁出的 skill。所有更新进本 skill,不进 CLAUDE.md。

占位符约定:<docs-hub> = 文档/设计真值中心目录;<frontend> = 任一前端工程(Android/iOS/Web…);design-truth = 设计真值(.pen/Figma 等导出的视觉真值,即 pen-truth 概念的通用名)。

§0 写 task md 前必跑 6 步审单(强制)

有界连续执行约定

实施/返修派单按源码 spec/task-authoring.md 的连续执行约定编写：一次冻结目标、 范围、旧基线/候选身份、预计影响、验收矩阵、证据落点、预算和真正停止线。 允许同一执行端在授权范围内连续完成夹具修复、最小源码修复和验证，不把每个测试 拆成需用户回复“下一步”的任务。只读、仅测试等明确限制仍有效；旧任务的阶段停止线 必须先由协调端按授权修订，不能让 Dev 自行越过。

故障注入修复按“有效正常对照 → 同一测试验证旧缺陷/候选修复 → 实际入口 → 受影响模块” 推进；小改定向、中改按影响、重构全量，纯文档不强加注入。前置失败先修夹具，不称产品缺陷。 同一失败两次无新证据，改诊断方法而非机械重跑；预算耗尽或确实缺权限/外部条件才交还。 任务内进展持续通报，但普通失败/阶段通过不构成人工确认门。

完成后集中独立复核冻结范围、一次汇总相关阻断项；不承诺一次审查必通过。 新发现默认单独登记，只有推翻本次结果或安全边界才申请调整范围。 本约定优先于下文把相邻发现自动扩入范围或每次验证失败立即另派任务的旧表述； 不增加 Hook 门禁、不转移授权、不跳过必要安全验证。

写任何 task md 前必跑 6 步(缺一不写,防协调端凭印象 / 单维度数据源 / 凭印象不查技术真值 / 忘记派发过的任务复发):

Step 0 强制铁律

• SessionStart hook 已自动注入 <docs-hub>/.ai-workspace/baseline/latest.md — 不再 grep 也能看到真值
• 派 audit subagent 前,subagent prompt 必含 Step 0 模板:

`` Step 0(强制):Read <PROJECT_ROOT>/<docs-hub>/.ai-workspace/baseline/latest.md`

• ls <frontend>/.ai-workspace/handoff/archive/{近 14 天}*.md(对每个 frontend)
• git -C <frontend> log --oneline --since=14d

回报"这个领域近 14 天已做了什么"摘要,再做 audit。 ```

• 协调端凭看代码下结论"已 wire / 未 wire"前必 git log 验证当前 commit 是不是协调端自己 task md 跑出来的

判定线:6 步任一缺 = task md 不合格,Dev 跑出来回归 = 协调端责任。 Gate1 判定线:fix / bug 类 task md,若 Layer1 知识库存在同类 bug 却未引"前车之鉴"段 = 不合格(修前必查回路断裂)。

§0.5 起草前 baseline 实证(强制 — 防协调端凭印象起草 master fix)

关联反模式:<docs-hub>/ADR/coordinator-impression-based-dispatch.md

设计动机:§0 6 步审单侧重"看哪些文件",§0.5 baseline侧重"verify 字面引用真实性"(防 stale Read + 凭印象 + scope 扩散 + scaffold 与 design-truth cross verify 缺失)。

两段不替代:§0 后必跑 §0.5,任一缺 → hook check_task_md_baseline.py 直接拒 Write(段标必含 §起草前 baseline 实证)。

§0.5.1 引用真实性 baseline(必跑 + 引用 grep 输出 / 行号)

每写 task md 前必跑以下步骤,产物贴入 task md frontmatter 下方"§起草前 baseline 实证"段(无段 = 不合格)。Step 1-5 为常规起草必跑;Step 6-20 为按触发条件追加(触发即必跑)。

§0.5.7 Step 14 review skill 清单(同一问题 2 次修不好场景)

最高效组合:

1. audit subagent(实证真因 + 多端代码 + 真值源 PRD/API/design-truth)— 必跑
2. grill-me(stress-test 真因 / 找最小改动)— 可选,当前宿主可用且任务收益足够时由 Agent 跑
3. verification-before-completion(Dev 完工 handoff 来时三联实证)— Dev 完工后跑

Step 14 强制铁律(违一即不合格):

• ❌ 同一问题 2 次修不好,第 3 次直接起 task md 不 invoke review = 拒生成
• ❌ review report 凭印象 / 不实证(必 file:line + design-truth/PRD/API quote)
• ❌ 跳过 review 直接派 Dev(因"积分浪费"假象)— 实际没 review 直接派的浪费远大于 review 工时
• ✅ review 后才决定:① 起新 task md(基于 report)② hold 等真值补齐 ③ user 决策(产品级)

§0.5.2 task md frontmatter 下方强制段(模板)

---
-assignee: ...
-branch: ...
-capability_tier: ...
---
 
# {任务标题}
 
## §起草前 baseline 实证(协调端必填 — §0.5 强制)
 
### Step 1:近 14 天 commit
-git log --since=14d 每个受影响 frontend commit:
  -{frontend-name}:
    -{hash} {msg}(本 task scope:⭐ / 旁证)
    -...
 
### Step 2:UserIntent / Action / API 真名 grep
-`grep -rn "<keyword>" <frontend>/<source dir>`:
  -{file}:{line} `{actual symbol}`(verify literal name vs intent name)
  -...
 
### Step 3:reverse symbol 反向搜索
-`git log -S "<symbol>"`:命中 {hash} {msg}
-来源判定:{Dev 自发实施 / 设计稿真值 / 协调端补充 / 用户决策}
 
### Step 4:Scaffold 既定实践 sweep
-`query-scaffold.sh --triggers {keyword}`:命中 scaffold X({file:line})
-同款 host 既定实践 grep:命中 N 处(列 file:line)
 
### Step 5:Scaffold 数值 vs design-truth 数值 cross verify
| 字段 | scaffold 实际 | design-truth 真值 | 一致? |
|---|---|---|:-:|
| {field} | {scaffold value} | {design-truth value} | ✅ / ❌ |
| ... | ... | ... | ... |
 
**冲突项处理**:
-design-truth 优先级 > scaffold → scaffold 偏 → 必改 scaffold(架构 task)/ 必标 task md "数据源冲突段"
-design-truth 缺数据 → 信 scaffold + 标 "design-truth 缺失,handoff 协调端补"