# fec-debug Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Replace `fec-build-fix` / `fec-build-fixer` with a unified `fec-debug` / `fec-debugger` system that covers build failures, runtime errors, UI anomalies, and API/data problems via a 5-step diagnostic framework.

**Architecture:** A single command (`fec-debug`) routes problems by type. A core skill (`fec-debug-framework`) defines the 5-step methodology (Classify → Collect → Hypothesize → Verify → Fix & Validate) with four diagnostic modules (build, runtime, ui, api). A subagent (`fec-debugger`) handles complex or cross-type cases.

**Tech Stack:** Markdown skill/command/agent definitions (no code changes). Existing `fec-validation-fix` skill is retained and referenced by the Build module.

---

## File Map

| Action        | Path                                                                                              | Responsibility                                                            |
| ------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| Create        | `skills/fec-debug-framework/SKILL.md`                                                             | Core diagnostic framework: 5-step methodology + 4 modules + report format |
| Create        | `commands/fec-debug.md`                                                                           | Entry command: type routing + delegation to skill/agent                   |
| Create        | `agents/fec-debugger.md`                                                                          | Subagent: executes complex multi-type diagnostics                         |
| Delete        | `commands/fec-build-fix.md`                                                                       | Superseded by `fec-debug`                                                 |
| Delete        | `agents/fec-build-fixer.md`                                                                       | Superseded by `fec-debugger`                                              |
| Rename+Update | `npm-packages/openclaw/commands/fec-build-fix.md` → `npm-packages/openclaw/commands/fec-debug.md` | npm-side command sync                                                     |
| Keep          | `skills/fec-validation-fix/SKILL.md`                                                              | Retained as Build module reference                                        |
| Keep          | `npm-packages/openclaw/skills/fec-validation-fix/SKILL.md`                                        | Retained (npm-side mirror)                                                |

---

### Task 1: Create Core Skill — `fec-debug-framework`

**Files:**

- Create: `skills/fec-debug-framework/SKILL.md`

- [ ] **Step 1: Create the skill directory and file**

Create `skills/fec-debug-framework/SKILL.md` with the full content below. This is the central piece — command and agent both reference it.

```markdown
---
name: fec-debug-framework
description: Use when diagnosing and fixing frontend issues including build failures, runtime errors, UI anomalies, and API/data problems. Provides a unified 5-step diagnostic methodology with type-specific modules. Chinese triggers: 调试, debug, 排查, 定位, 报错, 异常, 白屏, 请求失败.
---

# 前端诊断框架

## 核心方法论（5 步法）

所有前端问题诊断遵循统一流程：

### Step 1: 分类（Classify）

识别问题类型和影响范围：

| 类型    | 判断依据                     | 诊断入口       |
| ------- | ---------------------------- | -------------- |
| build   | 命令退出非零、stderr 有错误  | → Build 模块   |
| runtime | 控制台异常、白屏、功能不可用 | → Runtime 模块 |
| ui      | 视觉偏差、交互不符预期       | → UI 模块      |
| api     | 请求状态码异常、数据不一致   | → API 模块     |

跨类型问题（如 API 失败导致 UI 异常）从最表层症状入手，逐层深入。

### Step 2: 收集（Collect）

按类型收集证据（各模块有具体策略，见下方）。

### Step 3: 假设（Hypothesize）

基于证据提出可能根因，按可能性排序：

- 每个假设必须可测试（有明确的验证方法）
- 最多保留 3 个假设，避免发散
- 格式：「因为 X，导致 Y，可通过 Z 验证」

### Step 4: 验证（Verify）

逐一测试假设：

- 从最可能的假设开始
- 每次只改一个变量
- 验证结果记录：证实 / 证伪 / 待定
- 假设全部证伪时回到 Step 2 重新收集

### Step 5: 修复与确认（Fix & Validate）

- 应用最小修复
- 运行受影响验证命令
- 确认无回归
- 输出修复报告

---

## 诊断模块

### Build 模块

**收集**：运行最小失败命令，捕获完整 stderr/stdout
**假设**：按错误类型分组（类型错误、导入失败、配置解析、依赖缺失），匹配已知模式
**验证**：修一类根因 → 重跑命令 → 确认错误减少
**特殊处理**：

- 依赖升级/peer dependency/ESM/CJS 问题同时参考 `fec-dependency-upgrade`
- CI 专属失败检查 Node 版本、包管理器、环境变量差异

### Runtime 模块

**收集**：

- 复现路径（用户操作序列）
- 控制台错误和堆栈
- 组件渲染树状态（检查关键组件是否正确挂载）
- 相关 store/state 快照

**假设**：

- 堆栈反向追踪：从异常位置回溯到触发源
- 状态流分析：检查 state 变化是否符合预期
- 生命周期分析：是否在错误的时机访问了未初始化的数据

**验证**：

- 添加临时日志确认状态值
- 在可疑路径添加断言
- 复现路径验证修复

### UI 模块

**收集**：

- 当前截图 vs 期望效果
- DOM 结构检查（元素是否存在、层级是否正确）
- 计算样式检查（实际应用的 CSS 值）
- 响应式断点测试

**假设**：

- CSS 特异性冲突（选择器权重不够被覆盖）
- 组件状态不匹配（props/state 未正确传递）
- 布局模型问题（flex/grid 配置错误）
- 响应式断点遗漏

**验证**：

- 浏览器 DevTools 实时调整验证
- 隔离组件测试（排除外部样式干扰）
- 多断点逐一验证

### API 模块

**收集**：

- 请求 URL、method、headers、body
- 响应 status、headers、body
- 网络瀑布时序
- 相关 store/state 中的缓存数据

**假设**：

- 请求链路逐跳检查（URL → 中间件 → 拦截器 → 服务端）
- 数据转换检查（响应解析、类型映射）
- 缓存策略检查（过期、失效、竞态）
- 并发请求竞态（race condition）

**验证**：

- curl 独立复现（排除前端干扰）
- 逐层 mock 定位问题层级
- 端到端请求验证修复

---

## 报告格式

保存至 `reports/debug-YYYY-MM-DD-HHmmss.md`：

### 诊断报告

| 项目       | 内容                       |
| ---------- | -------------------------- |
| 问题类型   | build / runtime / ui / api |
| 问题描述   | 用户报告的现象             |
| 收集的证据 | 关键日志、截图、请求记录   |
| 假设与验证 | 每个假设的验证结果         |
| 根因       | 最终确认的根本原因         |
| 修复内容   | 修改的文件和具体改动       |
| 验证结果   | 修复后的验证命令和结果     |
| 剩余风险   | 未覆盖的边界或潜在回归     |

---

## 强约束

- 不在缺少证据时猜测根因
- 不通过关闭规则、删除测试或降低类型安全来「修复」
- 每次只改一个变量来验证假设
- 不在验证前扩大改动范围
- 同一假设连续 3 次验证失败，停止并报告阻塞
```

- [ ] **Step 2: Verify file was created**

Run: `cat skills/fec-debug-framework/SKILL.md | head -5`
Expected: First 5 lines show the frontmatter with `name: fec-debug-framework`

- [ ] **Step 3: Commit**

```bash
git add skills/fec-debug-framework/SKILL.md
git commit -m "feat(debug): add fec-debug-framework skill with 5-step diagnostic methodology"
```

---

### Task 2: Create Command — `fec-debug`

**Files:**

- Create: `commands/fec-debug.md`

- [ ] **Step 1: Create the command file**

Create `commands/fec-debug.md` with the content below. This is the user-facing entry point that routes to the framework skill.

```markdown
---
name: fec-debug
description: 前端问题诊断与修复：覆盖构建失败、运行时错误、UI 异常、接口问题，使用统一诊断框架按类型分流。
---

按 `fec-debug-framework` 执行前端问题诊断与修复。先分类问题类型（build / runtime / ui / api），再进入对应诊断模块执行 5 步法（分类→收集→假设→验证→修复）。复杂或跨类型问题可委托 **`fec-debugger`** 子代理。

## 问题类型速查

| 类型    | 典型场景                                        |
| ------- | ----------------------------------------------- |
| build   | lint/type-check/test/build/CI 失败              |
| runtime | JS 异常、白屏、组件渲染错误、路由异常、状态丢失 |
| ui      | 样式错位、交互异常、动画卡顿、响应式问题        |
| api     | 请求失败、超时、数据不一致、CORS、缓存问题      |

## 执行步骤

1. 读取用户描述的问题，按 `fec-debug-framework` Step 1 分类问题类型。
2. 进入对应诊断模块，执行 Step 2 收集证据。
3. 基于证据提出假设（Step 3），逐一验证（Step 4）。
4. 确认根因后执行最小修复（Step 5），运行受影响验证命令。
5. 输出诊断报告到 `reports/debug-YYYY-MM-DD-HHmmss.md`。

## 强约束

- 不通过关闭规则、删除测试或降低类型安全来「修复」问题
- 不顺手重构无关代码
- 不在缺少证据时猜测根因
- 修复后必须验证，不能只改不测
```

- [ ] **Step 2: Verify file was created**

Run: `cat commands/fec-debug.md | head -5`
Expected: First 5 lines show the frontmatter with `name: fec-debug`

- [ ] **Step 3: Commit**

```bash
git add commands/fec-debug.md
git commit -m "feat(debug): add fec-debug command with type-based routing"
```

---

### Task 3: Create Agent — `fec-debugger`

**Files:**

- Create: `agents/fec-debugger.md`

- [ ] **Step 1: Create the agent file**

Create `agents/fec-debugger.md` with the content below. This subagent handles complex or cross-type diagnostic scenarios.

```markdown
---
name: fec-debugger
description: 前端诊断与修复子代理：使用统一 5 步诊断框架处理构建失败、运行时错误、UI 异常、接口问题。适合复杂或多层嵌套的前端问题排查。
tools: Read, Edit, Write, MultiEdit, Glob, Grep, LS, Bash
model: sonnet
permissionMode: default
maxTurns: 16
skills:
  - fec-debug-framework
  - fec-validation-fix
  - fec-vite-project-standard
  - fec-react-project-standard
  - fec-vue3-project-standard
  - fec-testing-strategy
  - fec-dependency-upgrade
  - fec-security-review
---

你是一名前端诊断专家，使用统一 5 步诊断框架（分类→收集→假设→验证→修复）定位和修复前端问题。

## 工作流

1. 读取问题描述，按 `fec-debug-framework` 的 Step 1 分类问题类型。
2. 进入对应诊断模块，执行 Step 2 收集证据。
3. 基于证据提出假设（Step 3），每个假设必须可测试。
4. 逐一验证假设（Step 4），每次只改一个变量，记录证实/证伪。
5. 确认根因后执行最小修复（Step 5），运行受影响验证命令。
6. 输出诊断报告到 `reports/debug-YYYY-MM-DD-HHmmss.md`。

## 跨类型问题

当问题涉及多个类型（如 API 失败导致 UI 异常）：

- 从最表层症状入手
- 逐层深入，每层确认后再进入下一层
- 在报告中标注问题链路

## 强约束

- 不在缺少证据时猜测根因
- 不通过关闭规则、删除测试或降低类型安全来"修复"
- 不在验证前扩大改动范围
- 同一假设连续 3 次验证失败，停止并报告阻塞
- 不顺手重构无关代码
```

- [ ] **Step 2: Verify file was created**

Run: `cat agents/fec-debugger.md | head -5`
Expected: First 5 lines show the frontmatter with `name: fec-debugger` and `maxTurns: 16`

- [ ] **Step 3: Commit**

```bash
git add agents/fec-debugger.md
git commit -m "feat(debug): add fec-debugger agent for complex diagnostic scenarios"
```

---

### Task 4: Delete Old Files

**Files:**

- Delete: `commands/fec-build-fix.md`
- Delete: `agents/fec-build-fixer.md`

- [ ] **Step 1: Remove old command and agent**

```bash
git rm commands/fec-build-fix.md
git rm agents/fec-build-fixer.md
```

- [ ] **Step 2: Verify deletion**

Run: `ls commands/fec-build-fix.md agents/fec-build-fixer.md 2>&1`
Expected: Both files show "No such file or directory"

- [ ] **Step 3: Verify `fec-validation-fix` still exists (intentionally retained)**

Run: `ls skills/fec-validation-fix/SKILL.md`
Expected: File exists

- [ ] **Step 4: Commit**

```bash
git commit -m "chore(debug): remove superseded fec-build-fix command and fec-build-fixer agent"
```

---

### Task 5: Sync npm-packages Side

**Files:**

- Delete: `npm-packages/openclaw/commands/fec-build-fix.md`
- Create: `npm-packages/openclaw/commands/fec-debug.md`

Note: The npm-packages side has no `agents/` directory, so no agent sync is needed.

- [ ] **Step 1: Remove old npm-side command**

```bash
git rm npm-packages/openclaw/commands/fec-build-fix.md
```

- [ ] **Step 2: Create new npm-side command**

Create `npm-packages/openclaw/commands/fec-debug.md` with content matching the source-side command (Task 2 content):

```markdown
---
name: fec-debug
description: 前端问题诊断与修复：覆盖构建失败、运行时错误、UI 异常、接口问题，使用统一诊断框架按类型分流。
---

按 `fec-debug-framework` 执行前端问题诊断与修复。先分类问题类型（build / runtime / ui / api），再进入对应诊断模块执行 5 步法（分类→收集→假设→验证→修复）。复杂或跨类型问题可委托 **`fec-debugger`** 子代理。

## 问题类型速查

| 类型    | 典型场景                                        |
| ------- | ----------------------------------------------- |
| build   | lint/type-check/test/build/CI 失败              |
| runtime | JS 异常、白屏、组件渲染错误、路由异常、状态丢失 |
| ui      | 样式错位、交互异常、动画卡顿、响应式问题        |
| api     | 请求失败、超时、数据不一致、CORS、缓存问题      |

## 执行步骤

1. 读取用户描述的问题，按 `fec-debug-framework` Step 1 分类问题类型。
2. 进入对应诊断模块，执行 Step 2 收集证据。
3. 基于证据提出假设（Step 3），逐一验证（Step 4）。
4. 确认根因后执行最小修复（Step 5），运行受影响验证命令。
5. 输出诊断报告到 `reports/debug-YYYY-MM-DD-HHmmss.md`。

## 强约束

- 不通过关闭规则、删除测试或降低类型安全来「修复」问题
- 不顺手重构无关代码
- 不在缺少证据时猜测根因
- 修复后必须验证，不能只改不测
```

- [ ] **Step 3: Verify npm-side sync**

Run: `ls npm-packages/openclaw/commands/fec-build-fix.md 2>&1 && echo "STILL EXISTS" || echo "REMOVED"`
Expected: `REMOVED`

Run: `cat npm-packages/openclaw/commands/fec-debug.md | head -3`
Expected: Frontmatter with `name: fec-debug`

- [ ] **Step 4: Commit**

```bash
git add npm-packages/openclaw/commands/fec-debug.md
git commit -m "chore(debug): sync npm-packages command from fec-build-fix to fec-debug"
```

---

### Task 6: Final Verification

- [ ] **Step 1: Verify all new files exist**

```bash
ls -la commands/fec-debug.md skills/fec-debug-framework/SKILL.md agents/fec-debugger.md
```

Expected: All three files exist with non-zero size.

- [ ] **Step 2: Verify all old files are gone**

```bash
ls commands/fec-build-fix.md agents/fec-build-fixer.md npm-packages/openclaw/commands/fec-build-fix.md 2>&1
```

Expected: All three paths show "No such file or directory".

- [ ] **Step 3: Verify retained files still exist**

```bash
ls skills/fec-validation-fix/SKILL.md npm-packages/openclaw/skills/fec-validation-fix/SKILL.md
```

Expected: Both files exist.

- [ ] **Step 4: Verify cross-references are consistent**

Run: `grep -r "fec-build-fix\|fec-build-fixer" commands/ agents/ skills/ npm-packages/`
Expected: No matches (all references to old names should be gone).

- [ ] **Step 5: Verify new cross-references resolve**

Run: `grep -r "fec-debug-framework" commands/ agents/ skills/fec-debug-framework/`
Expected: At least 2 matches — command references skill, agent references skill.

Run: `grep -r "fec-debugger" commands/ agents/`
Expected: At least 1 match — command mentions agent delegation.

- [ ] **Step 6: Final commit (if any fixups were needed)**

Only if steps 1-5 revealed issues that needed fixing:

```bash
git add -A
git commit -m "fix(debug): resolve cross-reference issues found during verification"
```

If no fixups needed, skip this step.