@xulthekl/team-flow 0.22.4

package/skills/workflow-bootstrap/scripts/recon-probe.sh

@@ -0,0 +1,328 @@
+#!/usr/bin/env bash
+# ============================================================================
+# recon-probe.sh — 确定性代码库质量探查脚本（workflow-bootstrap B1）
+#
+# 用途
+#   对既有代码库做"固定化、可复现"的机械采集：目录树 / 依赖清单 / LOC 与文件
+#   类型分布 / 测试文件计数 / DB 迁移清单 / README-docs 探测。
+#   本脚本只做**确定性机械采集**（设计文档 v0.8 §17.8 第四类载体）——同项目两次
+#   运行结果一致，可横展对比。语义判断（架构模式 / 聚合根推断 / 框架定性）交给
+#   消费本脚本 JSON 输出的侦察子代理（codebase-recon-analyst）完成。
+#
+# 映射
+#   本脚本是未来 `tf recon` CLI 的底层实现雏形：
+#       tf recon [--root <path>] [--out <json>]
+#   现阶段以独立 bash 脚本形态供 workflow-bootstrap 调用，后续原样并入 CLI。
+#
+# 用法
+#   recon-probe.sh [--root <path>] [--out <json>]
+#     --root <path>   探查根目录（默认当前目录）
+#     --out  <json>   JSON 输出文件（默认写到 stdout）
+#
+# 输出
+#   - 结构化 JSON  → --out 指定文件或 stdout（供侦察子代理消费）
+#   - 人类可读摘要 → stderr（永远输出）
+#
+# 依赖
+#   纯 bash + 常见 unix 工具（find / grep / sed / awk / wc / sort / uniq）。
+#   jq **可选**：有 jq 时美化 JSON；无 jq 时输出脚本自建的合法 JSON（降级为文本）。
+#   健壮性：root 不存在不报错（输出最小 JSON + 提示），采集命令失败以 0/空兜底。
+# ============================================================================
+
+set -u  # 未定义变量报错；不用 -e（单条采集失败不应中断整体），逐处 || true 兜底
+
+# ----------------------------------------------------------------------------
+# 默认参数
+# ----------------------------------------------------------------------------
+ROOT="."
+OUT=""
+MAX_FILES=50000     # LOC 统计文件数上限（保护超大仓库）
+TREE_DEPTH=4        # 目录树限深
+
+# ----------------------------------------------------------------------------
+# 参数解析
+# ----------------------------------------------------------------------------
+print_help() {
+  sed -n '2,30p' "$0" 2>/dev/null | sed 's/^# \{0,1\}//'
+}
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --root)   ROOT="${2:-.}"; shift 2 ;;
+    --root=*) ROOT="${1#*=}"; shift ;;
+    --out)    OUT="${2:-}"; shift 2 ;;
+    --out=*)  OUT="${1#*=}"; shift ;;
+    -h|--help) print_help; exit 0 ;;
+    *) echo "[recon-probe] warn: unknown arg '$1' (ignored)" >&2; shift ;;
+  esac
+done
+
+# ----------------------------------------------------------------------------
+# 临时目录 + 清理
+# ----------------------------------------------------------------------------
+TMP="$(mktemp -d 2>/dev/null || echo "/tmp/recon-probe.$$")"
+mkdir -p "$TMP" 2>/dev/null
+trap 'rm -rf "$TMP" 2>/dev/null' EXIT
+
+# ----------------------------------------------------------------------------
+# JSON 辅助函数
+# ----------------------------------------------------------------------------
+# 转义字符串为合法 JSON 字符串内容（处理 \ " 及控制字符）
+json_escape() {
+  printf '%s' "$1" \
+    | sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/\t/\\t/g' -e 's/\r//g' \
+    | tr '\n' ' '
+}
+
+# 从"每行一个 item"的文件构建 JSON 字符串数组（确定性：调用方已 sort）
+json_array_from_file() {
+  _f="$1"
+  if [ ! -s "$_f" ]; then printf '[]'; return; fi
+  printf '['
+  _first=1
+  while IFS= read -r _line; do
+    [ -z "$_line" ] && continue
+    [ "$_first" -eq 1 ] && _first=0 || printf ','
+    printf '"%s"' "$(json_escape "$_line")"
+  done < "$_f"
+  printf ']'
+}
+
+# ----------------------------------------------------------------------------
+# root 健壮性处理
+# ----------------------------------------------------------------------------
+if [ ! -d "$ROOT" ]; then
+  echo "[recon-probe] warn: root '$ROOT' not found or not a directory" >&2
+  MIN_JSON='{"schema_version":1,"error":"root_not_found","root":"'"$(json_escape "$ROOT")"'"}'
+  if [ -n "$OUT" ]; then printf '%s\n' "$MIN_JSON" > "$OUT"; else printf '%s\n' "$MIN_JSON"; fi
+  exit 0
+fi
+ROOT_ABS="$(cd "$ROOT" 2>/dev/null && pwd)" || ROOT_ABS="$ROOT"
+
+# 噪音目录剪枝：包装 find，排除 .git/node_modules/构建产物等
+pruned_find() {
+  find "$ROOT_ABS" \
+    \( -type d \( \
+        -name .git -o -name node_modules -o -name target -o -name build \
+        -o -name dist -o -name out -o -name vendor -o -name .venv \
+        -o -name venv -o -name __pycache__ -o -name .idea -o -name .gradle \
+        -o -name coverage -o -name .next -o -name .turbo \
+    \) -prune \) -o "$@" 2>/dev/null
+}
+
+GENERATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo unknown)"
+
+# ============================================================================
+# ① 目录树（限深 TREE_DEPTH 层，相对路径，确定性排序）
+# ============================================================================
+find "$ROOT_ABS" -maxdepth "$TREE_DEPTH" \
+  \( -type d \( -name .git -o -name node_modules -o -name target -o -name build \
+     -o -name dist -o -name vendor -o -name .venv -o -name venv \
+     -o -name __pycache__ -o -name .idea -o -name .gradle \) -prune \) \
+  -o -type d -print 2>/dev/null \
+  | sed "s#^$ROOT_ABS/##; s#^$ROOT_ABS#.#" \
+  | sort > "$TMP/dirs.txt"
+DIR_COUNT=$(wc -l < "$TMP/dirs.txt" | tr -d ' ')
+
+# ============================================================================
+# ② 依赖清单（探测常见 manifest，机械提取依赖）
+# ============================================================================
+: > "$TMP/dep_manifests.json"
+add_manifest() {
+  # $1=file(rel) $2=type $3=deps-file(每行一个依赖)
+  _rel="$1"; _type="$2"; _deps="$3"
+  _arr="$(json_array_from_file "$_deps")"
+  printf '{"file":"%s","type":"%s","deps":%s},' \
+    "$(json_escape "$_rel")" "$(json_escape "$_type")" "$_arr" >> "$TMP/dep_manifests.json"
+}
+
+# 查找所有 manifest（相对路径），逐个解析
+pruned_find -type f \
+  \( -name pom.xml -o -name package.json -o -name requirements.txt \
+     -o -name go.mod -o -name build.gradle -o -name build.gradle.kts \
+     -o -name Gemfile -o -name Cargo.toml -o -name pyproject.toml \) \
+  -print 2>/dev/null | sort | while IFS= read -r mf; do
+    rel="${mf#"$ROOT_ABS"/}"
+    base="$(basename "$mf")"
+    deps_file="$TMP/deps_$(echo "$rel" | tr '/' '_').txt"
+    : > "$deps_file"
+    case "$base" in
+      pom.xml)
+        grep -oE '<artifactId>[^<]+</artifactId>' "$mf" 2>/dev/null \
+          | sed -E 's#</?artifactId>##g' | sort -u > "$deps_file" ;;
+      package.json)
+        grep -oE '"[@A-Za-z0-9/_-]+"[[:space:]]*:[[:space:]]*"[^"]+"' "$mf" 2>/dev/null \
+          | sed -E 's/[[:space:]]*:[[:space:]]*/@/; s/"//g' | sort -u > "$deps_file" ;;
+      requirements.txt)
+        grep -vE '^[[:space:]]*(#|$)' "$mf" 2>/dev/null \
+          | sed -E 's/[[:space:]]+$//' | sort -u > "$deps_file" ;;
+      go.mod)
+        sed -n '/require/,/)/p' "$mf" 2>/dev/null \
+          | grep -oE '[A-Za-z0-9./_-]+/[A-Za-z0-9./_-]+ v[0-9][^ ]*' \
+          | sort -u > "$deps_file" ;;
+      build.gradle|build.gradle.kts)
+        grep -E '(implementation|api|compile|testImplementation)[[:space:]]*[( ]' "$mf" 2>/dev/null \
+          | grep -oE "['\"][^'\"]+:[^'\"]+:[^'\"]+['\"]" \
+          | sed -E "s/['\"]//g" | sort -u > "$deps_file" ;;
+      Gemfile)
+        grep -E "^[[:space:]]*gem " "$mf" 2>/dev/null \
+          | sed -E "s/^[[:space:]]*gem ['\"]//; s/['\"].*//" | sort -u > "$deps_file" ;;
+      Cargo.toml)
+        sed -n '/\[dependencies\]/,/^\[/p' "$mf" 2>/dev/null \
+          | grep -E '^[A-Za-z0-9_-]+[[:space:]]*=' \
+          | sed -E 's/[[:space:]]*=.*//' | sort -u > "$deps_file" ;;
+      pyproject.toml)
+        sed -n '/dependencies/,/\]/p' "$mf" 2>/dev/null \
+          | grep -oE '"[A-Za-z0-9._-]+[^"]*"' \
+          | sed -E 's/"//g' | sort -u > "$deps_file" ;;
+    esac
+    # 限制每个 manifest 提取条数，避免 JSON 过大
+    head -n 200 "$deps_file" > "$deps_file.cut" 2>/dev/null && mv "$deps_file.cut" "$deps_file"
+    add_manifest "$rel" "$base" "$deps_file"
+  done
+# 去掉尾逗号
+MANIFESTS_JSON="$(sed 's/,$//' "$TMP/dep_manifests.json" 2>/dev/null)"
+[ -z "$MANIFESTS_JSON" ] && MANIFESTS_JSON=""
+
+# ============================================================================
+# ③ LOC 与文件类型分布（按扩展名统计；逐个 wc，避开 bash 关联数组以兼容 bash 3.2）
+# ============================================================================
+# 生成 "ext<TAB>lines" 对
+# 注意：不用 `head -z`（macOS BSD head 不支持 -z，会断管）；改用 while 内部计数 + break
+# 限制文件数（MAX_FILES）。sort -z 提供确定性顺序（BSD/GNU sort 均支持）。
+pruned_find -type f -print0 2>/dev/null \
+  | sort -z 2>/dev/null \
+  | while IFS= read -r -d '' f; do
+      _n=$(( ${_n:-0} + 1 ))
+      [ "$_n" -gt "$MAX_FILES" ] && break
+      name="$(basename "$f")"
+      case "$name" in
+        *.*) ext="${name##*.}" ;;
+        *)   ext="(none)" ;;
+      esac
+      lines="$(wc -l < "$f" 2>/dev/null | tr -d ' ')"
+      [ -z "$lines" ] && lines=0
+      printf '%s\t%s\n' "$ext" "$lines"
+    done > "$TMP/ext_lines.tsv"
+
+# awk 聚合（awk 关联数组无 bash 版本问题）
+awk -F'\t' '
+  { files[$1]++; loc[$1]+=$2; tf++; tl+=$2 }
+  END {
+    printf "%d\t%d\n", tf, tl > "'"$TMP"'/_totals.tsv";
+    for (e in files) printf "%s\t%d\t%d\n", e, files[e], loc[e];
+  }
+' "$TMP/ext_lines.tsv" 2>/dev/null | sort -t"$(printf '\t')" -k2,2nr > "$TMP/ext_stats.tsv"
+
+TOTAL_FILES="$(cut -f1 "$TMP/_totals.tsv" 2>/dev/null | head -1)"; TOTAL_FILES="${TOTAL_FILES:-0}"
+TOTAL_LINES="$(cut -f2 "$TMP/_totals.tsv" 2>/dev/null | head -1)"; TOTAL_LINES="${TOTAL_LINES:-0}"
+
+# 构建 by_extension JSON 数组
+: > "$TMP/byext.json"
+while IFS="$(printf '\t')" read -r ext fcnt lcnt; do
+  [ -z "$ext" ] && continue
+  printf '{"ext":"%s","files":%s,"lines":%s},' \
+    "$(json_escape "$ext")" "${fcnt:-0}" "${lcnt:-0}" >> "$TMP/byext.json"
+done < "$TMP/ext_stats.tsv"
+BYEXT_JSON="$(sed 's/,$//' "$TMP/byext.json" 2>/dev/null)"
+
+# ============================================================================
+# ④ 测试文件计数（test/spec 目录 + 命名约定）
+# ============================================================================
+pruned_find -type f \
+  \( -name '*Test.java' -o -name '*Tests.java' -o -name '*_test.go' \
+     -o -name '*.test.ts' -o -name '*.test.tsx' -o -name '*.test.js' -o -name '*.test.mjs' \
+     -o -name '*.spec.ts' -o -name '*.spec.tsx' -o -name '*.spec.js' -o -name '*.spec.mjs' \
+     -o -name 'test_*.py' -o -name '*_test.py' -o -name '*_spec.rb' \
+     -o -name '*Test.kt' -o -name '*Spec.scala' \) \
+  -print 2>/dev/null | sed "s#^$ROOT_ABS/##" | sort > "$TMP/test_files.txt"
+TEST_FILE_COUNT=$(wc -l < "$TMP/test_files.txt" | tr -d ' ')
+
+# 测试目录
+pruned_find -type d \( -name test -o -name tests -o -name spec -o -name __tests__ -o -name __test__ \) \
+  -print 2>/dev/null | sed "s#^$ROOT_ABS/##" | sort > "$TMP/test_dirs.txt"
+head -n 20 "$TMP/test_files.txt" > "$TMP/test_samples.txt" 2>/dev/null
+
+# ============================================================================
+# ⑤ DB 迁移文件清单（db/migration 目录 + *.sql）
+# ============================================================================
+pruned_find -type f -name '*.sql' -print 2>/dev/null | sed "s#^$ROOT_ABS/##" | sort > "$TMP/sql_files.txt"
+pruned_find -type d \( -name migration -o -name migrations -o -name migrate -o -name db \) \
+  -print 2>/dev/null | sed "s#^$ROOT_ABS/##" | sort > "$TMP/migration_dirs.txt"
+SQL_COUNT=$(wc -l < "$TMP/sql_files.txt" | tr -d ' ')
+head -n 50 "$TMP/sql_files.txt" > "$TMP/sql_samples.txt" 2>/dev/null
+
+# ============================================================================
+# ⑥ README / docs 探测
+# ============================================================================
+pruned_find -maxdepth 2 -type f \
+  \( -iname 'README*' -o -iname 'ARCHITECTURE*' -o -iname 'CONTRIBUTING*' \
+     -o -iname 'CHANGELOG*' -o -iname 'CLAUDE.md' -o -iname 'AGENTS.md' \) \
+  -print 2>/dev/null | sed "s#^$ROOT_ABS/##" | sort > "$TMP/doc_files.txt"
+if [ -d "$ROOT_ABS/docs" ]; then DOCS_DIR=true; else DOCS_DIR=false; fi
+
+# ============================================================================
+# 组装 JSON
+# ============================================================================
+{
+  printf '{\n'
+  printf '  "schema_version": 1,\n'
+  printf '  "tool": "recon-probe.sh (future: tf recon)",\n'
+  printf '  "root": "%s",\n' "$(json_escape "$ROOT_ABS")"
+  printf '  "generated_at": "%s",\n' "$GENERATED_AT"
+  # ① 目录树
+  printf '  "directory_tree": {"max_depth": %d, "dir_count": %s, "dirs": %s},\n' \
+    "$TREE_DEPTH" "$DIR_COUNT" "$(json_array_from_file "$TMP/dirs.txt")"
+  # ② 依赖清单
+  printf '  "dependencies": {"manifests": [%s]},\n' "$MANIFESTS_JSON"
+  # ③ LOC 与文件类型分布
+  printf '  "loc": {"total_files": %s, "total_lines": %s, "max_files_cap": %d, "by_extension": [%s]},\n' \
+    "$TOTAL_FILES" "$TOTAL_LINES" "$MAX_FILES" "$BYEXT_JSON"
+  # ④ 测试
+  printf '  "tests": {"test_file_count": %s, "test_dirs": %s, "sample_files": %s},\n' \
+    "$TEST_FILE_COUNT" \
+    "$(json_array_from_file "$TMP/test_dirs.txt")" \
+    "$(json_array_from_file "$TMP/test_samples.txt")"
+  # ⑤ DB 迁移
+  printf '  "db_migrations": {"sql_count": %s, "migration_dirs": %s, "sample_files": %s},\n' \
+    "$SQL_COUNT" \
+    "$(json_array_from_file "$TMP/migration_dirs.txt")" \
+    "$(json_array_from_file "$TMP/sql_samples.txt")"
+  # ⑥ docs
+  printf '  "docs": {"docs_dir": %s, "doc_files": %s}\n' \
+    "$DOCS_DIR" "$(json_array_from_file "$TMP/doc_files.txt")"
+  printf '}\n'
+} > "$TMP/out.json"
+
+# ============================================================================
+# 输出：JSON（--out 或 stdout，jq 可选美化）+ 人类可读摘要（stderr）
+# ============================================================================
+emit_json() {
+  if command -v jq >/dev/null 2>&1; then
+    jq '.' "$TMP/out.json" 2>/dev/null || cat "$TMP/out.json"
+  else
+    # 无 jq：降级为脚本自建的合法 JSON 文本
+    cat "$TMP/out.json"
+  fi
+}
+if [ -n "$OUT" ]; then
+  emit_json > "$OUT"
+  echo "[recon-probe] JSON written to: $OUT" >&2
+else
+  emit_json
+fi
+
+# 人类可读摘要 → stderr
+{
+  echo "================ recon-probe 摘要 ================"
+  echo "root        : $ROOT_ABS"
+  echo "目录(≤${TREE_DEPTH}层)  : $DIR_COUNT 个"
+  echo "源码文件     : $TOTAL_FILES 个 / $TOTAL_LINES 行 (cap $MAX_FILES)"
+  echo "依赖 manifest: $(grep -c '"file"' "$TMP/dep_manifests.json" 2>/dev/null || echo 0) 个"
+  echo "测试文件     : $TEST_FILE_COUNT 个"
+  echo "SQL 迁移     : $SQL_COUNT 个"
+  echo "docs/ 目录   : $DOCS_DIR"
+  echo "README 等    : $(wc -l < "$TMP/doc_files.txt" | tr -d ' ') 个"
+  echo "================================================="
+} >&2
+
+exit 0

package/skills/workflow-feedback/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: workflow-feedback
+description: >
+  记录 team-flow 工作流使用过程中发现的问题和改进建议。
+  当 skill 触发不准、SOP 流程不顺、产物质量不符预期、
+  交互体验不好时使用；也可在 change 收尾时回顾性触发。
+  不适用于：记录业务代码 bug（用 bug-investigator）、
+  沉淀已解决问题的经验（用 ce-compound）。
+argument-hint: "[问题简述] [--category <分类>] [--severity <P0-P3>]"
+---
+
+# Workflow Feedback
+
+记录 team-flow 工作流使用中的问题，转化为可追踪的改进项。
+
+> **设计依据**：设计增强方案 v0.8 §21.2（P1-10，v0.16.0）
+> **与 ce-compound 的关系**：ce-compound 是"经验沉淀端"（解决方案→docs/solutions/），workflow-feedback 是"问题发现端"（痛点→结构化记录→待办输入）。
+
+## Use This Skill When
+
+- skill 触发不准（误触发、不触发、触发域冲突）
+- SOP 流程不顺畅（阶段转换卡壳、路由错误、回退不合理）
+- 产物质量不符预期（格式、内容、校验问题）
+- 交互体验不好（确认过多/过少、信息过载）
+- change 收尾时回顾性触发（release-archivist 联动）
+- 用户主动说"记录问题"、"这个不好用"、"流程有问题"、"工作流反馈"、"流程反馈"
+
+**Do NOT use when**：
+- 业务代码 bug → `bug-investigator`
+- 已解决问题的经验沉淀 → `ce-compound`
+- 上下文腐化需要保存会话状态 → `session-handoff`（本 skill 记录问题，不保存上下文）
+- 设计增强方案的重大变更 → 直接修订设计文档
+
+## Support Files
+
+| 文件 | 用途 | 何时读取 |
+|------|------|---------|
+| `references/feedback-template.md` | 问题记录模板（YAML frontmatter + 正文） | Step 3 记录时 |
+| `references/category-guide.md` | 10 类问题分类定义与示例 | Step 1 分类时 |
+| `references/review-mode.md` | 回顾模式：从会话中自动识别问题信号 | 回顾模式触发时 |
+
+**按需读取，勿批量加载。**
+
+## Problem Categories
+
+> 完整定义与示例见 `references/category-guide.md`，以下为快速分类简表。
+
+| 分类 | 说明 | 优化责任方 |
+|------|------|-----------|
+| `skill-trigger` | 触发不准（误触发/不触发/冲突） | skill description + 触发域分层表 |
+| `sop-flow` | 阶段转换、路由、回退不顺 | orchestrator + 设计增强方案 |
+| `artifact-quality` | 产物格式/内容/校验问题 | 对应 skill + 制品契约 |
+| `state-management` | 状态文件不一致、恢复失败 | state-model + CLI |
+| `agent-quality` | subagent 产出质量问题 | agent 定义 + §18.1 |
+| `cli-command` | tf CLI 命令问题 | scripts/ |
+| `ux-interaction` | 交互不流畅、确认过多/过少 | skill 工作流设计 |
+| `performance` | token 消耗过大、响应慢 | skill 拆分/渐进式披露 |
+| `cross-platform` | 跨平台兼容性问题 | 多安装面配置 |
+| `documentation` | 文档不一致、过时、缺失 | 文档维护规范 |
+
+## Core Workflow
+
+```
+触发 → 1. 问题采集 → 2. 上下文关联 → 3. 结构化记录 → 4. 改进建议
+```
+
+### Step 1：问题采集
+
+**主动模式**（用户传入 argument）：直接记录用户描述的问题。
+
+**回顾模式**（无 argument，或由 release-archivist 联动触发）：
+分析当前会话，识别问题信号（详见 `references/review-mode.md`）：
+- skill 被调用后用户手动纠正
+- 用户表达不满（"不对"、"不是这样"、"重来"）
+- 状态回退（mandatory rewind）
+- 多次确认同一事项
+- 工作流中断或跳过
+
+### Step 2：上下文关联
+
+自动检测并关联：
+- 当前 SOP 阶段（`.team-flow/` yaml）
+- 状态机状态（`.team-flow.yaml`）
+- 涉及的 skill / agent / CLI 命令
+- 涉及的产物路径
+
+### Step 3：结构化记录
+
+按 `references/feedback-template.md` 格式输出：
+
+- **输出路径**：`.team-flow/feedback/<YYYYMMDD-HHmmss>-<category>.md`
+- **Git 跟踪**：feedback/ 目录不加入 .gitignore（改进输入需持久化）
+- **severity 判定**：未指定时根据影响范围自动建议
+
+### Step 4：改进建议
+
+1. 生成可直接追加到 CLAUDE.md 待办列表的条目（含优先级建议）
+2. 如果问题已有解决方案 → 建议触发 `ce-compound` 沉淀经验
+3. 如果问题涉及 skill description → 建议具体的 description 修改方向
+
+## Guardrails
+
+1. **不记录业务 bug**：业务代码问题归 bug-investigator，不是工作流问题
+2. **不替代 ce-compound**：已解决问题的经验沉淀归 ce-compound
+3. **不修改代码**：本 skill 只记录问题和建议，不直接修改 skill/agent/脚本
+4. **severity 不虚高**：按实际影响范围判定，不为了引起重视而拔高
+5. **一条一文件**：每个问题独立一个文件，便于追踪和关闭
+
+## Output
+
+- 问题记录：`.team-flow/feedback/<timestamp>-<category>.md`
+- 终端输出：问题摘要 + 建议待办条目 + 后续建议
+
+## Exception Handling
+
+| 异常 | 处理 |
+|------|------|
+| 无法判定分类 | 询问用户，或标记为 `documentation`（最宽泛） |
+| 同一问题已存在 | 扫描 `.team-flow/feedback/` 已有文件的 frontmatter category + 标题模糊匹配，提示用户已有记录，询问是否补充而非新建 |
+| `.team-flow/feedback/` 不存在 | 自动创建 |

package/skills/workflow-feedback/references/category-guide.md

@@ -0,0 +1,121 @@
+# 问题分类指南（10 类）
+
+> 本文件定义 workflow-feedback 的问题分类体系。
+> 每个分类对应 team-flow 的实际组件，有明确的优化责任方。
+
+## 分类详解
+
+### 1. skill-trigger（触发问题）
+
+**定义**：skill 的 description 触发条件不准确。
+
+**典型表现**：
+- 用户说了某个词，不该触发的 skill 被触发了（误触发）
+- 用户明确需要某 skill，但模型没有识别到（不触发）
+- 两个 skill 的触发词重叠，模型选错了（触发域冲突）
+
+**优化责任方**：skill description 文本 + AGENTS.md 触发域分层表
+
+**示例**：
+> 用户说"帮我规划一下"，触发了 ce-plan 而不是 workflow-orchestrator（产品级需求应走 orchestrator）
+
+### 2. sop-flow（流程问题）
+
+**定义**：SOP 阶段转换、路由、回退不顺畅。
+
+**典型表现**：
+- 阶段转换时卡壳（不知道下一步该做什么）
+- 路由到错误的 skill
+- 回退（mandatory rewind）触发条件不合理
+- S1-S5 之间的衔接不自然
+
+**优化责任方**：workflow-orchestrator + 设计增强方案 SOP 章节
+
+### 3. artifact-quality（产物质量）
+
+**定义**：生成的产物格式、内容、校验不符预期。
+
+**典型表现**：
+- PRD 缺少关键章节
+- plan.md 包含了不该有的内容（如接口清单）
+- spec 校验不通过
+- 产物之间的不一致
+
+**优化责任方**：对应 skill + 制品契约（artifact-contract.md）
+
+### 4. state-management（状态管理）
+
+**定义**：状态文件不一致、恢复失败、并发冲突。
+
+**典型表现**：
+- `.team-flow/` yaml 与实际产物状态不匹配
+- 跨 session 恢复失败
+- 多需求并行时状态混乱
+
+**优化责任方**：state-model 设计 + CLI 脚本
+
+### 5. agent-quality（子代理质量）
+
+**定义**：subagent 的产出质量不达标。
+
+**典型表现**：
+- subagent 返回结构不符合 §18.1 协议
+- subagent 产出内容质量低
+- subagent 没有正确处理阻断/非阻断疑问
+
+**优化责任方**：agent 定义文件 + §18.1 交接协议
+
+### 6. cli-command（CLI 命令）
+
+**定义**：tf CLI 命令的问题。
+
+**典型表现**：
+- 命令执行报错
+- 命令输出不符预期
+- 缺少必要的命令
+
+**优化责任方**：scripts/ 目录
+
+### 7. ux-interaction（交互体验）
+
+**定义**：交互不流畅、信息过载、确认过多/过少。
+
+**典型表现**：
+- 每个小决策都要确认，打断工作流
+- 一次性输出太多信息，用户无法消化
+- 该确认的时候没确认，直接做了
+
+**优化责任方**：skill 工作流设计
+
+### 8. performance（性能）
+
+**定义**：token 消耗过大、响应慢。
+
+**典型表现**：
+- SKILL.md 太长，加载就消耗大量上下文
+- 不必要的重复读取
+- 可以用脚本做的确定性工作用了 LLM
+
+**优化责任方**：skill 拆分 / 渐进式披露 / 脚本化
+
+### 9. cross-platform（跨平台）
+
+**定义**：在不同平台（Claude Code / Codex / Cursor 等）上的兼容性问题。
+
+**典型表现**：
+- 某平台不支持的功能被使用
+- 安装面配置不一致
+- 平台特有的限制未处理
+
+**优化责任方**：多安装面配置（.claude-plugin/ / .codex-plugin/ 等）
+
+### 10. documentation（文档）
+
+**定义**：文档不一致、过时、缺失。
+
+**典型表现**：
+- AGENTS.md 与实际 skills/ 不一致
+- CLAUDE.md 版本号过时
+- 设计增强方案与实际实现不匹配
+
+**优化责任方**：文档维护规范（CLAUDE.md 迭代同步清单）

package/skills/workflow-feedback/references/feedback-template.md

@@ -0,0 +1,73 @@
+# 问题记录模板
+
+> 本文件是 workflow-feedback skill 的结构化记录模板。
+> 设计依据：v0.8 §21.2
+
+## YAML Frontmatter
+
+```yaml
+---
+type: workflow-feedback
+version: 1
+created_at: <ISO 8601>
+category: <skill-trigger | sop-flow | artifact-quality | state-management | agent-quality | cli-command | ux-interaction | performance | cross-platform | documentation>
+severity: <P0 | P1 | P2 | P3>
+status: open
+related_skill: <skill-name | null>
+related_phase: <S1-S5 | change-level | null>
+related_requirement: <req-id | null>
+---
+```
+
+## Severity 判定标准
+
+| 级别 | 标准 | 示例 |
+|------|------|------|
+| P0 | 阻断工作流，无法继续 | 状态文件损坏导致无法恢复 |
+| P1 | 严重影响效率，有 workaround 但代价大 | skill 误触发导致每次都要手动纠正 |
+| P2 | 影响体验，有合理 workaround | 确认弹窗过多，但逐个确认也能完成 |
+| P3 | 锦上添花，不影响正常工作 | 输出格式可以更美观 |
+
+## 正文结构
+
+```markdown
+# [P?] <问题标题>
+
+## 现象
+<发生了什么——客观描述，不带情绪>
+
+## 期望
+<应该怎样——正确的行为是什么>
+
+## 复现路径
+1. 在 <阶段> 使用 <skill/命令>
+2. <具体操作>
+3. 观察到 <问题现象>
+
+## 影响
+- 影响范围：<哪些 skill/阶段/用户>
+- 频率：<首次 | 偶发 | 必现>
+
+## 改进建议
+<具体的修改方向，尽可能可操作>
+
+## 建议待办条目
+> 可直接追加到 CLAUDE.md 待办列表：
+> | P?-? | <标题> | 🔲 待实施 | v?.?.? | 来源：workflow-feedback <日期> |
+```
+
+## 文件命名
+
+`<YYYYMMDD-HHmmss>-<category>.md`
+
+示例：`20260725-143022-skill-trigger.md`
+
+## 状态流转
+
+```
+open → investigating → resolved → closed
+                   → wontfix（注明原因）
+```
+
+> 状态变更时更新 frontmatter 的 `status` 字段。
+> resolved 时建议触发 ce-compound 沉淀解决方案。