@bovinphang/frontend-craft 2.6.0 → 2.8.0

package/docs/superpowers/plans/2026-05-29-fec-debug.md

@@ -0,0 +1,491 @@
+# 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.