---
description: 会话级回顾：总结本会话 KB 流程失败/摩擦经验，并自动提交 Gitee Issue 改进流程
argument-hint: "[可选：聚焦主题或补充说明]"
---

> Pi 包 `@suwenguang/pi-kb`：运行时包根为环境变量 `PI_KB_ROOT`（由 `extensions/kb-root.ts` 注入）。
> 工种子 Agent 通过 **pi-subagents** 派发（已 bundled）；agent 定义见本包 `agents/`。
> 脚本调用示例：`node "$PI_KB_ROOT/scripts/<name>.mjs"`。

## 用户输入

${@:-（未附带参数；结合**当前会话**对话上下文执行，缺信息时向用户澄清。）}

---
对本 **Pi 会话**做一次回顾：提炼 KB 工作流上的**失败经验与流程摩擦**，并对可改进项**自动**走上游反馈（Gitee Issue），推动流程进化。

完整口径：[kb-feedback-gitee.md](../skills/kb-workflow/references/kb-feedback-gitee.md)。

**与相邻命令的区分**：

| 对象 | 命令 |
|------|------|
| **本会话**流程失败/摩擦 → 自动开 Issue | **本命令** `/kb-session-retro` |
| 用户已有明确单条流程吐槽 | `/kb-feedback` |
| 某变更产品验收问题 | `/kb-verify-issue` |
| 编码规矩沉淀（目录 `AGENTS.md`） | apply/lite 收尾；见 `kb-agents-precipitation.md` |
| 变更级总结 `05-summary.md` | `/kb-archive` / `/kb-lite` |

## Bootstrap 门禁（本命令豁免）

本命令只读会话上下文并向上游开 Issue，**不依赖**业务仓 KB 骨架。**禁止**跑 `kb-bootstrap-check.mjs` 并因未初始化而停止——尤其当摩擦本身是「门禁设计」时，硬拦会形成反馈悖论。

可选用候选池（不阻断）：`node "${PI_KB_ROOT}/scripts/kb-feedback-candidates.mjs" list --json`（扩展旁路采集；无候选则跳过）。

## 约束

- **禁止**创建或修改 `knowledge/工程平台/KB工作流/反馈/`（及任何本地 FB 文件）。
- **禁止**修改 `prompts/`、`skills/`、`agents/`、schema、业务代码（本命令只反馈，不进化）。
- **禁止**建议在业务仓直接跑 `/kb-evolve`（应引导 Issue 等待合入，或 `/kb-evolve-setup` 后在源码仓进化并提 MR）。
- 需要 Gitee token（`GITEE_ACCESS_TOKEN` 或 `node "$PI_KB_ROOT/scripts/kb-config.mjs" set-token`）；缺失时：**仍完成会话回顾报告**，对拟反馈项给出草稿标题/正文，并提示配置令牌后再重跑本命令或 `/kb-feedback`。
- **主 Agent 不写文件**：Issue 创建/评论由子 Agent 调 `kb-gitee-issue.mjs` 完成。
- 编码类教训：在报告中列出「建议写入的 `AGENTS.md` 路径与规矩摘要」；**本命令不落盘** AGENTS（留给 apply/lite 收尾或用户明示）。

## 回顾范围（只看本会话）

从当前对话上下文提取（勿臆造未发生事件）：

1. **流程摩擦**：门禁反复失败、阶段跳步/漏步、命令口径歧义、子 Agent 编排失败、manifest/schema 阻断、archive 迁移/commit 摩擦、CodeGraph/MCP 不可用导致硬拦、用户抱怨步骤繁琐等。
2. **可复用失败模式**：同一类错误出现 ≥2 次，或用户明确表达「流程应改」。
3. **非流程项**（只记录、不开 Issue）：纯业务 bug、产品验收、一次性环境/网络故障、用户操作失误且流程已正确提示。

## Issue 正文模板

Title：`[流程反馈][会话回顾] <中文主题>`

Body（写入临时文件再 `--body-file`）：

```markdown
[pi-kb-feedback]
[pi-kb-session-retro]

| 字段 | 内容 |
|---|---|
| 来源 | /kb-session-retro |
| 触发命令/阶段 | 如 /kb-apply、多命令、全局 |
| 严重度 | 高 / 中 / 低 |
| 频次（本会话） | 1 / ≥2 |
| pi-kb 版本 | <读 $PI_KB_ROOT/package.json version> |
| 业务仓 | <basename pwd> |

## 现象
<本会话实际摩擦；可列时间线要点，勿贴长日志>

## 失败经验（可复用）
- <一条可执行教训：下次如何避免 / 流程应如何改>

## 期望
<希望流程变成什么样>

## 场景追加
- <YYYY-MM-DD：本会话回顾；新建时可写「无」>
```

## 执行步骤

1. **扫描会话**：列出候选摩擦项表（主题 / 触发命令 / 严重度 / 频次 / 是否开 Issue）。先合并旁路候选（若有）：

```bash
node "${PI_KB_ROOT}/scripts/kb-feedback-candidates.mjs" list --json
```

信息不足时最多问用户 **一个** 关键澄清问题。
2. **分流**：
   - 流程摩擦且严重度 ≥ **中**，或频次 ≥2，或用户明示要改流程 → **自动反馈**（步骤 3–4）。
   - 严重度仅「低」且单次 → 写入回顾报告「观察项」，**默认不开** Issue（用户参数要求「全部反馈」时除外）。
   - 编码规矩 → 报告「AGENTS 建议」；产品验收 → 提示 `/kb-verify-issue`。
3. **查重**（对每个将开 Issue 的项）：

```bash
node "${PI_KB_ROOT}/scripts/kb-gitee-issue.mjs" list --state open --labels pi-kb-feedback --json
```

与现有 open Issue 标题/现象同因时：对该 `#number` 执行 `comment`（追加本会话场景与频次），**不**新建。

4. **新建**（无同因时；可多项则逐条 create，同轮最多 **3** 个新 Issue，其余进报告「待续反馈」）：

```bash
node "${PI_KB_ROOT}/scripts/kb-gitee-issue.mjs" create \
  --title "[流程反馈][会话回顾] <中文主题>" \
  --body-file /tmp/pi-kb-session-retro-body.md
```

5. **回报**：会话回顾摘要 + Issue 列表；对已开 Issue / 仅记录的旁路候选执行 `ack` / `dismiss`：

```bash
node "${PI_KB_ROOT}/scripts/kb-feedback-candidates.mjs" ack --id <id>
# 或 dismiss --id <id>
```

提示可 `/kb-evolve-setup` 后源码仓 `/kb-evolve`。

## 输出格式

```markdown
## 会话回顾（失败经验）

| 主题 | 类型 | 严重度 | 处置 |
|---|---|---|---|
| … | 流程 / 编码 / 验收 / 观察 | 高/中/低 | Issue #n / 追加评论 / 仅记录 / 建议 AGENTS |

### 流程反馈
- Issue #<n>：…（URL）

### AGENTS 建议（未落盘）
- `<path>/AGENTS.md`：…

### 下一步
等待合入；或 /kb-evolve-setup → 源码仓 /kb-evolve → MR。
无流程项时写：本会话无明显 KB 流程摩擦，未创建 Issue。
```

## 退出口径

- 不推进变更阶段、不提交业务仓 git、不改流程文件。
- 本命令完成即视为本会话「回顾已做」；扩展在 `/new` 前可跳过再次催促。
- 扩展触发时**不向用户确认**：检测到摩擦即注入本命令。