Implementation Tasks

Implementation Tasks

Synthesized from this review's findings. Each task derives from a specific finding above. Run with Claude Code or Codex; checkbox as you ship.

• [ ] T1 (P1, human: ~2h / CC: ~15min) — —
  • Surfaced by:
    —
  • Files:
  • Verify:
• [ ] T2 (P2, human: ~30min / CC: ~5min) — ...

优先级语义：P1 阻塞发布；P2 应与主改动同分支落地；P3 是后续 TODO。

**JSONL artifact（始终写入，零任务也写）**：`/autoplan` 会读取该文件跨阶段聚合。文档强制用 `jq -nc` 逐任务序列化（标题与发现文本可能含引号、换行、反斜杠，"never use hand-rolled echo / printf"）：

```bash
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
TASKS_DIR="${HOME}/.gstack/projects/${SLUG:-unknown}"
mkdir -p "$TASKS_DIR"
TASKS_FILE="$TASKS_DIR/tasks-devex-review-$(date +%Y%m%d-%H%M%S).jsonl"
COMMIT=$(git rev-parse HEAD 2>/dev/null || echo unknown)
BRANCH=$(git branch --show-current 2>/dev/null || echo unknown)
RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"

# 每个任务一次 jq 调用，占位符替换为 TASK_ID、PRIORITY、COMPONENT、TITLE、
# SOURCE_FINDING、EFFORT_HUMAN、EFFORT_CC、FILES_JSON（JSON 数组字面量）。
jq -nc \
  --arg phase 'devex-review' \
  --arg run_id "$RUN_ID" \
  --arg branch "$BRANCH" \
  --arg commit "$COMMIT" \
  --arg id "$TASK_ID" \
  --arg priority "$PRIORITY" \
  --arg component "$COMPONENT" \
  --arg effort_human "$EFFORT_HUMAN" \
  --arg effort_cc "$EFFORT_CC" \
  --arg title "$TITLE" \
  --arg source_finding "$SOURCE_FINDING" \
  --argjson files "$FILES_JSON" \
  '{phase:$phase, run_id:$run_id, branch:$branch, commit:$commit, id:$id, priority:$priority, component:$component, files:$files, effort_human:$effort_human, effort_cc:$effort_cc, title:$title, source_finding:$source_finding}' \
  >> "$TASKS_FILE"

两条边界规则值得注意：jq 未安装时跳过 JSONL 写入并提醒用户安装（绝不手写 JSONL）；零任务时用 : > "$TASKS_FILE" touch 空文件——空文件表示"本轮跑了、无发现"，与"没跑"在聚合器眼中语义不同。

若存在未获回复的 AskUserQuestion，必须在 Unresolved Decisions 段中记录，"Never silently default"。

Review Log、就绪仪表盘与计划文件报告

Review Log（记分卡之后必须落盘）

仪表盘、GSTACK REVIEW REPORT 以及 SKILL.md 中 EXIT PLAN MODE GATE 的 "review log was called" 检查都依赖这一步（PLAN MODE EXCEPTION — ALWAYS RUN，因为只写 ~/.gstack/ 不碰项目文件）：

~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-devex-review","timestamp":"TIMESTAMP","status":"STATUS","initial_score":N,"overall_score":N,"product_type":"PRODUCT_TYPE","tthw_current":"TTHW_CURRENT","tthw_target":"TTHW_TARGET","mode":"MODE","persona":"PERSONA","competitive_tier":"COMPETITIVE_TIER","unresolved":N,"commit":"COMMIT"}'

字段来源：TIMESTAMP 为当前 ISO 8601 时间；STATUS 为 clean（评分 ≥8 且 0 未决）否则 issues_open；其余字段来自 DX Scorecard 与 Step 0；COMMIT 为 git rev-parse --short HEAD。

Review Readiness Dashboard：解析评审日志并给出裁定

运行 gstack-review-read 后按规则解析：每个 skill 取最近一条、忽略 7 天前的条目；Eng Review 行取 review（diff 范围、落地前）与 plan-eng-review（计划阶段架构评审）中较新者并标注 (DIFF)/(PLAN)；Adversarial 行取 adversarial-review 与 codex-review（legacy）较新者；Design Review 取 plan-design-review（完整视觉审计）与 design-review-lite（代码级检查）较新者并标注 (FULL)/(LITE)；Outside Voice 行展示最近的 codex-plan-review 条目。若条目带 via 字段则并入状态标签（如 via:"autoplan" 显示为 "CLEAR (PLAN via /autoplan)"）。autoplan-voices 与 design-outside-voices 条目仅用于取证，不出现在仪表盘。

评审分层（原文定义）：

• Eng Review（默认必需）：唯一卡发布的评审，可被 gstack-config set skip_eng_review true 全局关闭；
• CEO Review（可选）：重大产品/业务变化、新用户可见功能、范围决策时推荐，bug 修复/重构/基建跳过；
• Design Review（可选）：UI/UX 变化时推荐，纯后端、基建或 prompt 改动跳过；
• Adversarial Review（自动）：每次评审都跑 Claude 对抗 subagent + Codex 对抗挑战，200+ 行大 diff 额外加 Codex 结构化评审与 P1 gate；
• Outside Voice（可选）：不同 AI 模型的独立计划评审，Codex 不可用时回退 Claude subagent，永不卡发布。

裁定逻辑：CLEARED = Eng Review 在 7 天内有来自 review 或 plan-eng-review 的 clean 条目（或 skip_eng_review=true）；NOT CLEARED = 缺失、过期（>7 天）或有未决问题。CEO/Design/Codex 行仅作上下文，不阻塞。

陈旧检测（文档给出精确算法）：

• 内容优先规则（仅适用于 diff 范围行：review、adversarial-review、codex-review 及 ship 阶段条目）：解析 bash 输出的 ---WTREE--- 与 ---DIRTY--- 段；条目的 wtree 字段等于当前值即 CURRENT——"wtree 相等本身就证明内容相同"是这一条的基石性质，无论 commit 数、rebase 与否都跳过 commit 计数启发式；
• 计划层行（plan-ceo-review、plan-eng-review、plan-design-review）评审对象是计划文件而非仓库树，永不套用 wtree 规则，保持 7 天新鲜度逻辑；若条目带 plan_sha256 可与当前计划文件 sha256 对比，不一致时注明 "plan changed since review"；
• 回退路径（无 wtree 或不匹配）：解析 ---HEAD--- 段，对比条目的 commit 字段，用 git rev-list --count STORED_COMMIT..HEAD 数经过的 commit；命令失败（commit 被 rebase 掉）则评级 UNKNOWN 按陈旧处理，显示 "Note: {skill} review from {date} may be stale — {N} commits since review"；无 commit 字段的遗留条目提示 "has no commit tracking — consider re-running"。

Plan File Review Report：把评审状态写回计划文件

仪表盘在对话中展示后，还要把报告写进计划文件本身，让任何读计划的人都能看到评审状态。流程：先检测活跃计划文件（宿主在 system message 中提供路径），找不到就静默跳过；然后读取评审日志（每个 skill 记录不同字段，文档给出了 plan-ceo-review / plan-eng-review / plan-design-review / plan-devex-review / devex-review / codex-review 各自的 Findings 列生成公式，例如 plan-devex-review → "score: {initial_score}/10 → {overall_score}/10, TTHW: {tthw_current} → {tthw_target}"），生成固定表格：

## GSTACK REVIEW REPORT

| Review | Trigger | Why | Runs | Status | Findings |
|--------|---------|-----|------|--------|----------|
| CEO Review | `/plan-ceo-review` | Scope & strategy | {runs} | {status} | {findings} |
| Codex Review | `/codex review` | Independent 2nd opinion | {runs} | {status} | {findings} |
| Eng Review | `/plan-eng-review` | Architecture & tests (required) | {runs} | {status} | {findings} |
| Design Review | `/plan-design-review` | UI/UX gaps | {runs} | {status} | {findings} |
| DX Review | `/plan-devex-review` | Developer experience gaps | {runs} | {status} | {findings} |

表下依次是可选的 CODEX（仅 codex-review 跑过时）、CROSS-MODEL（仅两种评审都存在时）与必有的 VERDICT 行（列出 CLEARED 的评审；若 Eng Review 非 CLEAR 且未全局跳过，追加 "eng review required"）。

未决决策状态是强制项（"MANDATORY — never omitted"）：报告（## GSTACK REVIEW REPORT 标题下的内容，用粗体标签而非新 ## 标题）的最后一个非空行必须是二选一：精确的未加粗 NO UNRESOLVED DECISIONS，或 **UNRESOLVED DECISIONS:** 头 + 每个未决项一条 bullet（最后一个 bullet 即文件末行；仅当 N>0 时加 + N unresolved from prior reviews）。文档特别给出防重复计数算法：本评审的未决项从上下文列；历史评审按 skill 取 7 天窗口内最新行求和 unresolved，但先 DROP 当前 skill 自己的行；两者皆零才输出哨兵行。

写入流程（delete-then-append），这是针对真实回归设计的硬约束：

1. Read 计划文件全文，搜索任意位置的 ## GSTACK REVIEW REPORT 标题；
2. 若存在，Edit 删除整个旧段（从该标题到下一个 ## 或文件尾），无论它当前在文件中部还是底部——"mid-file deletion is intentional, not a special case"；Edit 失败则重读重试一次；
3. 删除后把新报告段追加到文件末尾（Edit 匹配末段后追加，或 Write 整文件重放）；
4. 用 Read 验证 ## GSTACK REVIEW REPORT 是文件中最后一个 ## 标题，不是就重复步骤 2-3 一次。

文档解释了为什么禁止原地替换："replace mid-file" 路径曾导致旧报告残留在文件中部，用户看到报告不在底部的计划会（正确地）拒绝它。而 SKILL.md 的 EXIT PLAN MODE GATE 把这一结构变成阻塞检查：确认文件最后一个 ## 标题是 ## GSTACK REVIEW REPORT、表格与 VERDICT 存在、末行是未决决策状态，且 gstack-review-log 与 gstack-review-read 至少各调用过一次——不满足就不准调用 ExitPlanMode。

Capture Learnings、Brain 回写与评审链

Capture Learnings：评审中发现的非显然模式、坑或架构洞见要记录下来。命令与语义：

~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"plan-devex-review","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'

• Types：pattern（可复用做法）、pitfall（不要做什么）、preference（用户声明）、architecture（结构性决策）、tool（库/框架洞见）、operational（项目环境/CLI/工作流知识）；
• Sources：observed（代码里发现的）、user-stated（用户告知）、inferred（AI 推断）、cross-model（Claude 与 Codex 都同意）；
• Confidence：1-10，要求诚实——代码中验证过的 observed 模式给 8-9，不确定的推断给 4-5，用户明确声明的偏好给 10；
• files 字段用于陈旧检测：相关文件日后被删除时该学习可被标记；
• 只记录真正的发现："would this insight save time in a future session? If yes, log it."

Brain Calibration Write-Back（Phase 2 / 门控开启）：当技能做出值得追踪的类型化预测（范围决策、TTHW 目标、架构下注、wedge 承诺）时，可以向 brain 写一条 kind=bet 的 take 以积累校准画像。双门控：① 活动端点的 brain 信任策略为 personal（通过 gstack-config get brain_trust_policy@<endpoint-hash> 检查；共享 brain 跳过回写以免污染团队校准）；② 功能开关 BRAIN_CALIBRATION_WRITEBACK 已开启（文档注明当前为 false，待上游 gbrain v0.42+ 提供 takes_add MCP op 后翻转为 true）。双门通过时经 mcp__gbrain__takes_add 以权重 0.6 记录（按 SKILL_CALIBRATION_WEIGHTS）；MCP op 不可用时回退 mcp__gbrain__put_page 写 gstack:takes fence 块。take frontmatter 形状：

kind: bet
holder: <user identity from whoami>
claim: <one-line prediction the skill is making>
weight: 0.6
since_date: <today's date>
expected_resolution: <date in 1-3 months depending on skill>
source_skill: plan-devex-review

写后使受影响 digest 失效：

eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
~/.claude/skills/gstack/bin/gstack-brain-cache invalidate developer-persona --project "$SLUG" 2>/dev/null || true

Brain Cache Background Refresh：技能工作完成（且遥测已记录）后，后台刷新接近 TTL 的缓存 digest——非阻塞，用户不等待，下次调用享受热缓存：

eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)" 2>/dev/null || true
(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true

Next Steps — Review Chaining：展示仪表盘后按规则推荐下一步评审：Eng Review 未全局跳过则推荐 /plan-eng-review（DX 问题常带架构含义——API 设计、错误处理、CLI 手感问题应由工程评审验证修复方案）；存在面向用户的 UI 则建议 /plan-design-review（DX 评审面向开发者表面，设计评审面向终端用户 UI）；实现后推荐 /devex-review（boomerang：计划说 TTHW 是目标值，现实是否达成？此时竞品基准第一次兑现价值——有了可测量的具体目标）。选项：A) 先跑 /plan-eng-review（必需 gate）B) 跑 /plan-design-review（仅在检测到 UI 范围时）C) 准备实现，发布后跑 /devex-review D) 跳过，手动处理。

Mode Quick Reference（文档末尾的模式速查表，对应 SKILL.md Step 0E 选定的模式）：

             | DX EXPANSION     | DX POLISH          | DX TRIAGE
Scope        | Push UP (opt-in) | Maintain           | Critical only
Posture      | Enthusiastic     | Rigorous           | Surgical
Competitive  | Full benchmark   | Full benchmark     | Skip
Magical      | Full design      | Verify exists      | Skip
Journey      | All stages +     | All stages         | Install + Hello
             | best-in-class    |                    | World only
Passes       | All 8, expanded  | All 8, standard    | Pass 1 + 3 only
Outside voice| Recommended      | Recommended        | Skip