@house365/comate 0.2.10 → 0.4.0

package/skills/comate/scripts/comate.sh

@@ -17,6 +17,12 @@
 #   sources <name> check                     — drift check tracked source files
 #   sources <name> list                      — print the source manifest
 #   sources find <file>                      — reverse lookup: changes citing a file
+#   gate    <prd> review                     — create/refresh gate.yaml next to the PRD, pin hash
+#   gate    <prd> set <field> <value>        — write score | blocking_open | gate_status | …
+#   gate    <prd> pass [--tbd]               — mark passed (needs blocking_open=0 + report)
+#   gate    <prd> spawned <change>           — record a change fanned out from this PRD
+#   gate    <prd> status [--json]            — print gate status (computes stale on hash drift)
+#   gate    <prd> check                      — precondition guard before spawning a change
 #   archive <name> [--dry-run]               — sync delta specs + annotate + move + mark archived
 #   status  [path]                           — list active changes + next command
 #   doctor                                   — prerequisite self-check
@@ -66,6 +72,12 @@ Usage: comate.sh <command> ...
   sources <name> check
   sources <name> list
   sources find <file>
+  gate    <prd> review                      create/refresh gate.yaml next to PRD, pin hash
+  gate    <prd> set <field> <value>         score | blocking_open | gate_status | …
+  gate    <prd> pass [--tbd]                mark passed (needs blocking_open=0 + report)
+  gate    <prd> spawned <change>            record a change fanned out from this PRD
+  gate    <prd> status [--json]
+  gate    <prd> check                       precondition guard before spawning a change
   archive <name> [--dry-run]
   status  [path]
   doctor
@@ -1332,6 +1344,184 @@ sources_find() {
   return 0
 }
 
+# =====================================================================
+# gate — phase 0: PRD quality gate + split precondition
+# =====================================================================
+
+# require_prd <prd> — ensure the PRD path is a real, non-empty file; echo it.
+require_prd() {
+  local prd="$1"
+  [ -n "$prd" ] || die "$COMATE_USAGE" "ERROR: PRD path required"
+  case "$prd" in *..*) die "$COMATE_USAGE" "ERROR: PRD path cannot contain '..': $prd" ;; esac
+  [ -f "$prd" ] || die "$COMATE_CORRUPT" "ERROR: PRD not found: $prd"
+  file_nonempty "$prd" || die "$COMATE_CORRUPT" "ERROR: PRD is empty: $prd"
+  echo "$prd"
+}
+
+# gate <prd> review — create or refresh gate.yaml next to the PRD and pin the
+# current PRD hash. Existing passed gates are re-opened to `reviewing` only when
+# the PRD changed (hash drift); otherwise the review report path is (re)emitted
+# so the skill knows where to write its human-readable audit. The skill does the
+# semantic scoring and writes score/blocking_open/gate_status via `gate set`.
+gate_review() {
+  local prd; prd=$(require_prd "$1")
+  local gate report cur_hash
+  gate=$(gate_path_for "$prd")
+  report=$(gate_report_for "$prd")
+  cur_hash=$(hash_file "$prd")
+
+  if [ ! -f "$gate" ]; then
+    cat > "$gate" <<EOF
+# comate PRD gate — flat key:value only, no nesting
+schema_version: $GATE_SCHEMA_VERSION
+prd_path: $prd
+prd_hash: $cur_hash
+gate_status: reviewing
+score: null
+blocking_open: null
+review_report: $report
+spawned_changes: null
+gated_at: null
+created_at: $(today)
+EOF
+    log_pass "[GATE] created $gate (status=reviewing)"
+  else
+    local old_hash old_status
+    old_hash=$(yaml_get "$gate" prd_hash)
+    old_status=$(yaml_get "$gate" gate_status)
+    gate_yaml_set "$gate" prd_path "$prd"
+    gate_yaml_set "$gate" review_report "$report"
+    if [ "$old_hash" != "$cur_hash" ]; then
+      gate_yaml_set "$gate" prd_hash "$cur_hash"
+      gate_yaml_set "$gate" gate_status reviewing
+      log_warn "[GATE] PRD changed since last review — status reset to reviewing (was $old_status)"
+    else
+      log_info "[GATE] $gate (status=$old_status, unchanged PRD)"
+    fi
+  fi
+  echo "review_report: $report"
+}
+
+# gate <prd> set <field> <value> — write a gate field (score/blocking_open/
+# gate_status/…) with the same validation as gate_yaml_set.
+gate_set() {
+  local prd; prd=$(require_prd "$1")
+  local field="${2:-}" value="${3:-}"
+  [ -n "$field" ] || die "$COMATE_USAGE" "Usage: comate.sh gate <prd> set <field> <value>"
+  local gate; gate=$(gate_path_for "$prd")
+  [ -f "$gate" ] || die "$COMATE_CORRUPT" "ERROR: gate not found (run 'gate review' first): $gate"
+  gate_yaml_set "$gate" "$field" "$value"
+  log_pass "[GATE] set $field=$value"
+}
+
+# gate <prd> pass [--tbd] — flip to passed/passed-with-tbd. Hard precondition:
+# blocking_open must be 0 (no open blocking issues). Re-pins prd_hash so a later
+# edit invalidates the pass. --tbd records that the user authorised proceeding
+# with unresolved TBDs (spawned changes must carry ⚠ markers).
+gate_pass() {
+  local prd; prd=$(require_prd "$1")
+  local tbd=0
+  [ "${2:-}" = "--tbd" ] && tbd=1
+  local gate; gate=$(gate_path_for "$prd")
+  [ -f "$gate" ] || die "$COMATE_CORRUPT" "ERROR: gate not found (run 'gate review' first): $gate"
+
+  local blocking; blocking=$(yaml_get "$gate" blocking_open)
+  if [ "$blocking" != "0" ]; then
+    die "$COMATE_BLOCK" "BLOCK: blocking_open='$blocking' — resolve all blocking issues (set blocking_open 0) before passing the gate"
+  fi
+  local report; report=$(yaml_get "$gate" review_report)
+  if [ -z "$report" ] || [ "$report" = "null" ] || ! file_nonempty "$report"; then
+    die "$COMATE_BLOCK" "BLOCK: review report missing or empty ($report) — the gate report is mandatory"
+  fi
+
+  gate_yaml_set "$gate" prd_hash "$(hash_file "$prd")"
+  if [ "$tbd" -eq 1 ]; then
+    gate_yaml_set "$gate" gate_status passed-with-tbd
+  else
+    gate_yaml_set "$gate" gate_status passed
+  fi
+  gate_yaml_set "$gate" gated_at "$(today)"
+  log_pass "[GATE] $(yaml_get "$gate" gate_status) — changes may now be spawned from $prd"
+}
+
+# gate <prd> spawned <change> — append a change name to spawned_changes
+# (comma-joined), recording which changes this PRD fanned out into.
+gate_spawned() {
+  local prd; prd=$(require_prd "$1")
+  local change="${2:-}"
+  validate_change_name "$change"
+  local gate; gate=$(gate_path_for "$prd")
+  [ -f "$gate" ] || die "$COMATE_CORRUPT" "ERROR: gate not found: $gate"
+  local cur; cur=$(yaml_get "$gate" spawned_changes)
+  case ",$cur," in
+    *",$change,"*) log_info "[GATE] $change already recorded" ; return 0 ;;
+  esac
+  if [ -z "$cur" ] || [ "$cur" = "null" ]; then
+    gate_yaml_set "$gate" spawned_changes "$change"
+  else
+    gate_yaml_set "$gate" spawned_changes "$cur,$change"
+  fi
+  log_pass "[GATE] recorded spawned change: $change"
+}
+
+# _gate_is_stale <gate> <prd> — true (0) if the recorded hash no longer matches
+# the PRD on disk.
+_gate_is_stale() {
+  local gate="$1" prd="$2" recorded actual
+  recorded=$(yaml_get "$gate" prd_hash)
+  [ -f "$prd" ] || return 0
+  actual=$(hash_file "$prd")
+  [ "$recorded" != "$actual" ]
+}
+
+# gate <prd> status [--json] — print current gate status, computing stale on the
+# fly (hash drift). Does not mutate the file.
+gate_status() {
+  local prd="$1" json="${2:-}"
+  [ -n "$prd" ] || die "$COMATE_USAGE" "Usage: comate.sh gate <prd> status [--json]"
+  local gate; gate=$(gate_path_for "$prd")
+  if [ ! -f "$gate" ]; then
+    if [ "$json" = "--json" ]; then
+      printf '{"gate":"none","prd":"%s"}\n' "$(json_escape "$prd")"
+    else
+      echo "gate: none ($prd) — run 'gate review' to start"
+    fi
+    return "$COMATE_OK"
+  fi
+  local st score blocking; st=$(yaml_get "$gate" gate_status)
+  score=$(yaml_get "$gate" score); blocking=$(yaml_get "$gate" blocking_open)
+  if [ -f "$prd" ] && _gate_is_stale "$gate" "$prd"; then st="stale"; fi
+  if [ "$json" = "--json" ]; then
+    printf '{"gate":"%s","status":"%s","score":"%s","blocking_open":"%s","report":"%s"}\n' \
+      "$(json_escape "$gate")" "$(json_escape "$st")" "$(json_escape "$score")" \
+      "$(json_escape "$blocking")" "$(json_escape "$(yaml_get "$gate" review_report)")"
+  else
+    echo "gate: $st  score=$score  blocking_open=$blocking  ($gate)"
+  fi
+  return "$COMATE_OK"
+}
+
+# gate <prd> check — the precondition guard comate-open runs before spawning a
+# change. PASS (exit 0) requires: gate.yaml exists, status ∈ {passed,
+# passed-with-tbd}, and prd_hash matches the current PRD. Anything else BLOCKs.
+gate_check() {
+  local prd; prd=$(require_prd "$1")
+  local gate; gate=$(gate_path_for "$prd")
+  if [ ! -f "$gate" ]; then
+    die "$COMATE_BLOCK" "BLOCK: no gate for $prd — run /comate-intake to review the PRD before creating a change"
+  fi
+  local st; st=$(yaml_get "$gate" gate_status)
+  case "$st" in
+    passed|passed-with-tbd) ;;
+    *) die "$COMATE_BLOCK" "BLOCK: gate_status='$st' (not passed) — a change cannot be spawned until the PRD gate passes" ;;
+  esac
+  if _gate_is_stale "$gate" "$prd"; then
+    die "$COMATE_BLOCK" "BLOCK: PRD changed since it passed the gate (hash mismatch) — re-run /comate-intake to re-gate before spawning a change"
+  fi
+  log_pass "[GATE] check PASS ($st) — $prd"
+  return "$COMATE_OK"
+}
+
 # =====================================================================
 # archive
 # =====================================================================
@@ -1678,6 +1868,20 @@ case "$CMD" in
       esac
     fi
     ;;
+  gate)
+    PRD="${1:-}"; SUB="${2:-}"
+    [ -n "$PRD" ] && [ -n "$SUB" ] || { usage_top; exit "$COMATE_USAGE"; }
+    shift 2 || true
+    case "$SUB" in
+      review)  gate_review "$PRD" ;;
+      set)     gate_set "$PRD" "${1:-}" "${2:-}" ;;
+      pass)    gate_pass "$PRD" "${1:-}" ;;
+      spawned) gate_spawned "$PRD" "${1:-}" ;;
+      status)  gate_status "$PRD" "${1:-}" ;;
+      check)   gate_check "$PRD" ;;
+      *) die "$COMATE_USAGE" "Unknown gate subcommand: $SUB" ;;
+    esac
+    ;;
   archive)
     [ -n "${1:-}" ] || { usage_top; exit "$COMATE_USAGE"; }
     archive "$1" "${2:-}"

package/skills/comate/tests/comate.bats

@@ -447,3 +447,200 @@ SH
   run comate frobnicate
   [ "$status" -eq 2 ]
 }
+
+# --- gate ---
+
+seed_prd() {
+  mkdir -p docs/knowledge-base/requirements/test
+  printf '# PRD-001\n功能清单:登录、登出\n' > \
+    docs/knowledge-base/requirements/test/PRD-001-demo.md
+  echo "docs/knowledge-base/requirements/test/PRD-001-demo.md"
+}
+
+@test "gate review creates gate.yaml next to PRD" {
+  local prd; prd=$(seed_prd)
+  run comate gate "$prd" review
+  [ "$status" -eq 0 ]
+  [ -f "docs/knowledge-base/requirements/test/PRD-001-demo.gate.yaml" ]
+}
+
+@test "gate review writes reviewing status and pins prd_hash" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  local gate="docs/knowledge-base/requirements/test/PRD-001-demo.gate.yaml"
+  run comate gate "$prd" status
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"reviewing"* ]]
+  local hash; hash=$(grep '^prd_hash:' "$gate" | awk '{print $2}')
+  [ -n "$hash" ]
+  [ "$hash" != "null" ]
+}
+
+@test "gate check blocks when status is reviewing" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" check
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"BLOCK"* ]]
+}
+
+@test "gate pass blocked when blocking_open not zero" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 80 >/dev/null
+  run comate gate "$prd" pass
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"blocking_open"* ]]
+}
+
+@test "gate pass blocked when review report missing" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  run comate gate "$prd" pass
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"report"* ]]
+}
+
+@test "gate pass succeeds and check passes after report written" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  printf '# 评审报告\n' > \
+    "docs/knowledge-base/requirements/test/PRD-REVIEW-PRD-001-demo.md"
+  run comate gate "$prd" pass
+  [ "$status" -eq 0 ]
+  run comate gate "$prd" check
+  [ "$status" -eq 0 ]
+}
+
+@test "gate pass --tbd sets passed-with-tbd" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 65 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  printf '# 评审报告\n' > \
+    "docs/knowledge-base/requirements/test/PRD-REVIEW-PRD-001-demo.md"
+  run comate gate "$prd" pass --tbd
+  [ "$status" -eq 0 ]
+  run comate gate "$prd" status
+  [[ "$output" == *"passed-with-tbd"* ]]
+}
+
+@test "gate check blocks after PRD modified post-pass (stale)" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  printf '# 评审报告\n' > \
+    "docs/knowledge-base/requirements/test/PRD-REVIEW-PRD-001-demo.md"
+  comate gate "$prd" pass >/dev/null
+  # mutate PRD after passing
+  printf '\n额外内容\n' >> "$prd"
+  run comate gate "$prd" check
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"stale"* ]] || [[ "$output" == *"hash mismatch"* ]]
+}
+
+@test "gate status reports stale on hash drift without mutating file" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  printf '# 评审报告\n' > \
+    "docs/knowledge-base/requirements/test/PRD-REVIEW-PRD-001-demo.md"
+  comate gate "$prd" pass >/dev/null
+  printf '\n改动\n' >> "$prd"
+  run comate gate "$prd" status
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"stale"* ]]
+  # gate.yaml should still say passed (status is computed, not written by status cmd)
+  local gate="docs/knowledge-base/requirements/test/PRD-001-demo.gate.yaml"
+  local stored; stored=$(grep '^gate_status:' "$gate" | awk '{print $2}')
+  [ "$stored" = "passed" ]
+}
+
+@test "gate spawned records change name in spawned_changes" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  printf '# 报告\n' > \
+    "docs/knowledge-base/requirements/test/PRD-REVIEW-PRD-001-demo.md"
+  comate gate "$prd" pass >/dev/null
+  run comate gate "$prd" spawned login-flow
+  [ "$status" -eq 0 ]
+  local gate="docs/knowledge-base/requirements/test/PRD-001-demo.gate.yaml"
+  local sc; sc=$(grep '^spawned_changes:' "$gate" | sed 's/spawned_changes: //')
+  [[ "$sc" == *"login-flow"* ]]
+}
+
+@test "gate spawned appends second change comma-joined" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  printf '# 报告\n' > \
+    "docs/knowledge-base/requirements/test/PRD-REVIEW-PRD-001-demo.md"
+  comate gate "$prd" pass >/dev/null
+  comate gate "$prd" spawned login-flow >/dev/null
+  comate gate "$prd" spawned logout-flow >/dev/null
+  local gate="docs/knowledge-base/requirements/test/PRD-001-demo.gate.yaml"
+  local sc; sc=$(grep '^spawned_changes:' "$gate" | sed 's/spawned_changes: //')
+  [[ "$sc" == *"login-flow"* ]]
+  [[ "$sc" == *"logout-flow"* ]]
+}
+
+@test "gate status returns none when gate does not exist" {
+  mkdir -p docs/knowledge-base/requirements/test
+  run comate gate "docs/knowledge-base/requirements/test/PRD-001-demo.md" status
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"none"* ]]
+}
+
+@test "gate unknown subcommand returns usage error" {
+  local prd; prd=$(seed_prd)
+  run comate gate "$prd" frobnicate
+  [ "$status" -eq 2 ]
+}
+
+@test "gate review re-opens reviewing when PRD changes after pass" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  comate gate "$prd" set score 90 >/dev/null
+  comate gate "$prd" set blocking_open 0 >/dev/null
+  printf '# 报告\n' > \
+    "docs/knowledge-base/requirements/test/PRD-REVIEW-PRD-001-demo.md"
+  comate gate "$prd" pass >/dev/null
+  printf '\n改动\n' >> "$prd"
+  # re-run review after PRD change — should reset to reviewing
+  run comate gate "$prd" review
+  [ "$status" -eq 0 ]
+  run comate gate "$prd" status
+  [[ "$output" == *"reviewing"* ]]
+}
+
+@test "gate set rejects unknown field" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" set nonexistent_field foo
+  [ "$status" -eq 2 ]
+}
+
+@test "gate set rejects invalid gate_status value" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" set gate_status flying
+  [ "$status" -eq 2 ]
+}
+
+@test "gate status --json emits json with status field" {
+  local prd; prd=$(seed_prd)
+  comate gate "$prd" review >/dev/null
+  run comate gate "$prd" status --json
+  [ "$status" -eq 0 ]
+  [[ "$output" == *'"status"'* ]]
+  [[ "$output" == *'"reviewing"'* ]]
+}

package/skills/comate-build/SKILL.md

@@ -54,13 +54,38 @@ bash "$COMATE" state <name> set plan docs/superpowers/plans/YYYY-MM-DD-feature.m
 
 ### 3. 选择工作方式（决策阻塞点 3）
 
-**一次性询问用户**工作区隔离方式、执行方式和 TDD 模式。规则见 `comate/reference/decision-points.md` 第 3 条。
+就工作区隔离、执行方式、TDD 模式做**一个联合决策**。规则与判定协议见 `comate/reference/decision-points.md`（先判定"三类行动"，第 3 条）。
 
-**工作区隔离**：A 创建分支（简单快速）/ B 创建 Worktree（完全独立，适合并行）。推荐：≤ 3 文件→A；需并行或当前分支有未提交工作→B。
+#### 3a. 能力预检（展示选项前先做）
 
-**执行方式**：A `superpowers:subagent-driven-development`（任务独立、复杂、需双阶段审查）/ B `superpowers:executing-plans`（任务简单、轻量）。推荐：任务 ≥ 3→A；≤ 2 且无跨模块依赖→B；来自 hotfix→B。
+逐维度检查当前平台/仓库实际可执行的选项，只保留可执行者：
 
-**必须使用 AskUserQuestion 工具暂停等待用户明确选择**，不得用推荐规则自行选择。用户选择后：
+- **isolation**（脚本枚举仅 `branch` / `worktree`）
+  - `worktree`：仅当 `superpowers:using-git-worktrees` skill 可用时保留；不可用则剔除。
+  - `branch`：始终可用（HEAD detached 时先提示用户切到实分支）。
+- **build_mode**
+  - `subagent-driven-development`：仅当当前平台有真实后台子 agent / Task 派发能力时保留；无则剔除。
+  - `executing-plans`：始终可用。
+- **tdd_mode**：`tdd` / `direct` 始终可用。
+
+#### 3b. 唯一选项自动应用（属"自动处理"，不阻塞）
+
+预检后某维度只剩一个可执行选项，**直接写入并说明原因，不为它单独问用户**。例如：
+
+- 仅 `executing-plans` 可用（无后台派发能力）→ 自动写 `build_mode: executing-plans`，说明"无后台子 agent 能力"。
+- 仅 `branch` 可用（`using-git-worktrees` 未安装）→ 自动写 `isolation: branch`，说明"worktree skill 不可用"。
+
+多个维度都只剩单值时，一并自动写入并逐条说明；三个维度全部只剩单值时本决策点整体跳过，直接进入 Step 3c 执行。
+
+#### 3c. 联合决策（仍有 ≥2 有效选项的维度才问）
+
+对仍有多个有效选项的维度，**一次 AskUserQuestion 问清全部**，选 `branch` 时**分支名也在同一次确认**，不得先问是否继续再二次追问配置或命名。已在 3b 自动写入的维度不再列入问题。每个选项附推荐理由（推荐只说明倾向，不代替用户拍板）：
+
+- **工作区隔离**：`branch` 新建分支（简单快速，≤3 文件推荐）/ `worktree` 独立工作区（需并行或当前分支有未提交工作时推荐）。
+- **执行方式**：`subagent-driven-development`（任务 ≥3、独立、需双阶段审查）/ `executing-plans`（任务 ≤2 且无跨模块依赖，或来自 hotfix）。
+- **TDD 模式**：`tdd`（涉及业务逻辑/新功能/API，推荐）/ `direct`（无需测试覆盖或用户明确跳过）。
+
+用户选择后（连同 3b 已自动应用的维度）写入：
 
 ```bash
 bash "$COMATE" state <name> set isolation <branch|worktree>

package/skills/comate-grill/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: comate-grill
+description: "决策点穷追式澄清工具。对计划/设计/PRD 问题进行深度优先遍历，逐个决策点给推荐答案并等用户确认，直到所有歧义清零。可由 comate-intake 内部调用，或用户直接 /comate-grill 使用。"
+---
+
+# comate-grill —— 决策点穷追式澄清
+
+**定位**：一个通用的决策澄清引擎，用于在计划/设计/需求阶段对模糊点、依赖链、歧义进行**逐个深挖**，直到所有分支清晰。
+
+**算法来源**：改编自社区 [grill-me pattern](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/)（Timothy Vang、Matt Pocock 等贡献的最佳实践），内化到 comate 家族以避免外部依赖漂移。
+
+---
+
+## 核心算法（四条铁律）
+
+1. **决策树深度优先遍历**  
+   串行解决决策点，不批量轰炸。后续分支常依赖前面的答案，所以必须一个接一个。
+
+2. **每个问题附推荐答案**  
+   不是裸问题（"你觉得 X 怎么设计？"），而是"我建议用 Y 方案，因为 Z 理由。你同意吗？如果不同意，你倾向什么？"
+
+3. **优先探索代码库/文档，不问能查到的事实**  
+   - 已有架构约定、字段定义、接口规范、对接档案 → 用 Read/Grep/Glob/LSP 核实，引用来源，不丢给用户。
+   - 产品决策（范围、优先级、用户行为、状态流转、数据口径、失败处理、验收规则）→ 必须问用户。
+
+4. **一次一问，等回答再进下一个**  
+   并行提多个问题会让用户不知从哪答起，且前面的答案可能让后面的问题失效。
+
+---
+
+## 调用场景
+
+### 由其他 skill 内部调用（主场景）
+
+- **comate-intake 步骤 3（阻断闸门）**：当 PRD 阻断问题 > 3 个或有决策依赖链时，用户可选「深度澄清模式」，此时 intake 调用本 skill，传入阻断问题清单，逐个深挖。
+- **未来扩展**：comate-design 的方案澄清、comate-verify 的验收标准澄清等，都可复用本 skill。
+
+**调用方式**（从其他 skill 内）：
+
+```markdown
+用 Skill 工具加载 `comate-grill`，传入：
+
+话题：<要澄清的主题，如「PRD 阻断问题清单」>
+问题列表：
+1. [ID] 问题描述 | 原文依据 | 影响范围 | 当前歧义
+2. ...
+```
+
+### 用户直接调用
+
+用户可以在任何阶段直接 `/comate-grill <话题>` 对计划、设计、决策进行穷追式澄清。适用于：
+
+- 自己的计划草稿想被挑战一遍
+- 技术方案有多个路径，想逐条过一遍利弊
+- PRD/需求文档的边界不清楚，想被问到无死角
+
+---
+
+## 工作流
+
+### 输入
+
+- **话题**：澄清的主题（如「PRD 阻断问题」「技术选型」「API 设计」）
+- **问题列表**（可选，无则从话题自由展开）：带 ID、描述、依据、影响的问题清单
+
+### 过程
+
+1. **建决策树骨架**  
+   根据问题列表（或从话题展开）识别所有决策点，按依赖关系排序（前面的决策会影响后面的选项）。
+
+2. **逐点深挖**  
+   从第一个决策点开始：
+   - 先查代码库/文档/架构约定能否直接回答（能则引用来源，告知用户，进入下一个）
+   - 不能则构造推荐答案：2–3 个互斥选项 + 推荐项 + 理由 + 各选项的后果
+   - 用 **AskUserQuestion** 提问，等用户回答
+   - 记录答案，更新后续决策点的前置条件
+
+3. **递归展开新分支**  
+   用户的回答可能引出新的子问题（如选了"分布式事务"就要问"补偿机制怎么设计"）。把新问题插入决策树对应位置，继续深挖。
+
+4. **终止条件**  
+   所有决策点都有明确答案（非"待定""看情况"），或用户主动喊停。
+
+### 输出
+
+- **决策台账**（markdown 表格）：每个问题的 ID、问题、推荐、用户答案、依据/来源
+- **待办事项**（若有）：哪些答案需要后续在代码/文档中落地
+
+---
+
+## Guardrails
+
+- **AskUserQuestion 是真阻塞点**：推荐答案、默认值、"通常做法"、历史偏好都不能替代用户明确回答。只有用户选了选项或输入自定义答案，才能进入下一个决策点。
+- **不替用户拍板**：可以给建议、列利弊、引用案例，但最终选择必须等用户确认。
+- **不问能查到的事实**：已有的架构文档、代码约定、接口规范先用工具核实，只问"怎么做"的决策，不问"是什么"的事实。
+- **分支依赖显式标注**：后续问题若依赖前面的答案，在提问时点明"因为你选了 X，所以这里..."，让用户理解为什么要问这个。
+- **深度有限，避免无底洞**：单个决策点最多展开 2 层子问题。若发现需要第 3 层，说明原问题拆得不够，停下来重新拆解问题本身。
+
+---
+
+## 示例
+
+**输入**（由 comate-intake 调用）：
+
+```
+话题：PRD 门禁阻断问题清单
+问题列表：
+1. [B-03] 用户登录失败后的重试机制未明确 | 原文"支持登录" | 影响：异常路径、用户体验
+2. [B-07] 数据同步到第三方失败时的降级策略缺失 | 原文"对接外部 API" | 影响：可用性、数据一致性
+3. [B-11] 管理员权限范围模糊（能否删除其他管理员的数据？）| 原文"管理员可管理所有数据" | 影响：权限设计、安全
+```
+
+**执行**：
+
+1. **问题 1（登录重试）**  
+   - 先查现有登录模块代码：发现有 `max_retries` 配置但未用
+   - 给推荐："我建议限制 5 次/15 分钟，超过后锁定账户 30 分钟并发邮件通知，理由是防暴力破解。你同意吗？"
+   - 用户答："改成 3 次/10 分钟，锁定 1 小时"
+   - 记录，进入下一个
+
+2. **问题 2（第三方失败降级）**  
+   - 查架构文档：无降级策略先例
+   - 给推荐："我建议失败后写本地队列，定时重试 3 次，3 次后人工介入。你倾向什么？"
+   - 用户答："可以，但重试间隔用指数退避"
+   - 追问："指数退避的初始间隔和最大间隔？"（新分支）
+   - 用户答："初始 30s，最大 10min"
+   - 记录，进入下一个
+
+3. **问题 3（管理员权限）**  
+   - 查权限表和现有角色定义：只有 `admin` 和 `user` 两角色
+   - 给推荐："建议引入超级管理员（super_admin）和普通管理员（admin），普通管理员不能删除其他管理员的数据。你同意吗？"
+   - 用户答："不需要超级管理员，所有管理员平级，但删除操作需二次确认"
+   - 记录
+
+**输出**：
+
+```markdown
+## 决策台账
+
+| ID    | 问题 | 推荐 | 用户答案 | 依据/来源 |
+|-------|------|------|----------|-----------|
+| B-03  | 登录重试机制 | 5次/15分钟，锁定30分钟 | 3次/10分钟，锁定1小时 | 用户确认 |
+| B-07  | 第三方失败降级 | 本地队列+定时重试3次 | 同意，重试用指数退避（30s→10min） | 用户确认 |
+| B-11  | 管理员权限范围 | 引入super_admin和admin两级 | 不分级，删除操作二次确认 | 用户确认 |
+
+所有阻断问题已澄清，可更新 PRD 评审报告并置 `blocking_open=0`。
+```
+
+---
+
+## 与 comate 其他 skill 的区别
+
+| skill | 定位 | 提问方式 |
+|-------|------|----------|
+| **comate-grill** | 决策点穷追引擎，逐个深挖直到无歧义 | 深度优先、一次一问、附推荐 |
+| comate-intake | PRD 门禁+拆分，暴露问题但不深挖每个 | 批量扫描+分轮处理 |
+| openspec-explore | 探索问题空间，发散式头脑风暴 | 开放式、多角度、不强制收敛 |
+| comate-design | 技术设计+方案 brainstorming | 方案对比、架构决策、不逐点穷举 |
+
+**简单说**：explore 是发散、grill 是收敛、intake 是门禁、design 是方案对比。grill 的独特价值是"不放过任何一个模糊点"。
+
+---
+
+## 何时用 comate-grill
+
+**推荐用**：
+- 阻断问题 > 3 个且有依赖链（intake 自动提供选项）
+- 技术方案有多条路径，想逐条过利弊（design 阶段手动调用）
+- 自己的计划草稿想被挑战到无死角（用户直接 `/comate-grill <话题>`）
+
+**不推荐用**：
+- 简单问题（≤ 2 个独立决策点）→ 直接 AskUserQuestion 即可
+- 纯事实查询（"这个字段在哪张表"）→ 用 Read/Grep/LSP
+- 开放式头脑风暴（"有哪些可能的方案"）→ 用 openspec-explore
+
+---
+
+## 维护说明
+
+本 skill 是社区最佳实践的内化版本，避免外部依赖漂移。若社区 grill-me 有新算法改进，可在此同步更新，但保持 comate 命名空间和中文文档风格。
+
+**来源致谢**：
+- [mattpocock/skills - grill-me](https://github.com/mattpocock/skills/blob/main/skills/productivity/grill-me/SKILL.md)
+- [gsarig/skills - grill-me](https://github.com/gsarig/skills/blob/main/skills/grill-me/README.md)
+- [RobMitt/grill-me-skill](https://github.com/RobMitt/grill-me-skill)