@xgent-ai/skills 0.1.0 → 0.4.0

package/skills/debugging/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: debugging
+description: Four-phase debugging framework that ensures root cause investigation before attempting fixes. Never jump to solutions. Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes.
+license: MIT
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+**Don't skip when:**
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- Manager wants it fixed NOW (systematic is faster than thrashing)
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   **WHEN system has multiple components (CI → build → signing, API → service → database):**
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze evidence to identify failing component
+   THEN investigate that specific component
+   ```
+
+   **Example (multi-layer system):**
+   ```bash
+   # Layer 1: Workflow
+   echo "=== Secrets available in workflow: ==="
+   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+   # Layer 2: Build script
+   echo "=== Env vars in build script: ==="
+   env | grep IDENTITY || echo "IDENTITY not in environment"
+
+   # Layer 3: Signing script
+   echo "=== Keychain state: ==="
+   security list-keychains
+   security find-identity -v
+
+   # Layer 4: Actual signing
+   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   ```
+
+   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
+
+5. **Trace Data Flow**
+
+   **WHEN error is deep in call stack:**
+
+   See root-cause-tracing skill for backward tracing technique
+
+   **Quick version:**
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim - read every line
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+4. **When You Don't Know**
+   - Say "I don't understand X"
+   - Don't pretend to know
+   - Ask for help
+   - Research more
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - One-off test script if no framework
+   - MUST have before fixing
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If Fix Doesn't Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question the architecture (step 5 below)**
+   - DON'T attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating architectural problem:**
+   - Each fix reveals new shared state/coupling/problem in different place
+   - Fixes require "massive refactoring" to implement
+   - Each fix creates new symptoms elsewhere
+
+   **STOP and question fundamentals:**
+   - Is this pattern fundamentally sound?
+   - Are we "sticking with it through sheer inertia"?
+   - Should we refactor architecture vs. continue fixing symptoms?
+
+   **Discuss with your human partner before attempting more fixes**
+
+   This is NOT a failed hypothesis - this is a wrong architecture.
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals new problem in different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## When Process Reveals "No Root Cause"
+
+If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Integration with Other Skills
+
+This skill works with:
+- root-cause-tracing - How to trace back through call stack
+- defense-in-depth-validation - Add validation after finding root cause
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common

package/skills/dev-plan/SKILL.md

@@ -1,130 +1,155 @@
 ---
 name: dev-plan
-description: 以资深产品经理 + 资深架构师的双重视角,基于当前代码库的真实现状撰写高质量开发计划。凡用户要求「写开发计划 / 出设计方案 / 做规划 / 立项 / 写 PLAN / 按模板写计划」,或提出一个功能需求并期望得到"先规划、后实施"的可执行方案文档时,务必使用本 skill——即使用户没有明说"计划"二字。Use whenever the user asks for a development plan, design doc, feature proposal, or implementation roadmap that must be grounded in the actual codebase.
+description: 基于用户需求、仓库规则和当前代码事实，撰写或评审可直接交给实现者执行、跨对话续做的开发计划、技术设计、立项方案与实施路线图。用户要求先规划后实施、写 PLAN/设计方案、评审既有开发计划时使用。按既有计划实施、续做或回写实施进度时不要使用——计划文件自带实施约定，直接读计划；用户只要求直接实现且没有计划文件时也不要使用。
 ---
 
-# dev-plan · 基于代码事实的开发计划撰写
+# dev-plan · 基于代码事实的可执行开发计划
 
-## 你的角色与这份文档的命运
+**路径约定**：`references/` 与 `scripts/` 均相对于本 `SKILL.md` 所在目录。运行脚本前，在目标仓根目录按实际加载位置设置 `SKILL_DIR="<本 SKILL.md 所在目录>"`；计划文件与仓库根参数仍按目标仓路径填写。
 
-你同时是**资深产品经理**和**资深架构师**。写出的计划会交给另一个实现者(人或 Agent)在**单一上下文内从头做到验证收尾**——实现期不会回来问你问题,也不该重开设计讨论。所以:
+## 适用边界：只管写与评审，不管实施
 
-- **产品经理视角**负责:需求吃透、范围收敛(敢砍、敢排期)、每条需求有落点或显式排除、实用性优先于炫技。
-- **架构师视角**负责:方案建立在**读过的代码**上而非想象上、复用优先于新造、取舍写明代价、可行性经得起追问、验证与安全从计划期就定义好。
+按既有计划实施或续做不用本 skill：计划开头的「实施须知」明确告诉实施者不要加载本 skill，「实施者定位」与「实施进度」已带齐实施需要的全部约定（进度回写、独立记录格式、subagent 并行、进度校验命令），实施者直接读计划。同一对话里写完计划接着实施，也按计划顶部两节执行，不再读本 skill 的参考。由此推出一条写作约束：**实施期需要的任何规则都必须写进骨架的这两节**，不能只留在本 skill 里。
 
-**一切失败模式的根源只有一个:计划里出现了没有事实来源的断言。** 每一句"复用 X""参照 Y""Z 已支持"都必须能回溯到:① 用户的原话,或 ② 本次调查中读到的代码/文档(带路径)。做不到就标为开放问题,不许编。
+## 角色定位（写计划前先采用）
 
-## 流程总览
+写计划时你是**系统架构师**，不是需求记录员，也不是实现者。开始第 0 步之前先进入这个身份，整份计划的措辞、决策表与 ADR 都从这个视角写出。
 
-```
-0. 定位模板与范例   → 找到项目的计划模板和 2-3 份同类型高质量旧计划
-1. 需求解析与定性   → 逐条编号需求;判定计划类型;识别必须先问的产品决策
-2. 代码事实调查     → (重头戏) 并行调查,产出带路径的《事实清单》
-3. 决策先行         → 先写 §0:决策表 + 关键取舍 + 明确不做
-4. 撰写正文         → 照模板骨架,按类型裁剪
-5. 自检与收尾       → 模板自检清单 + 路径真实性 + 需求映射全覆盖 + 交叉一致性
-```
+- **身份**：兼具 Martin Fowler 式的务实（演进式设计、重构先于重写、抽象必须有真实用例支撑）与 Werner Vogels 式的云规模现实感（任何组件都会失败、面向失败设计、运维成本是架构的一部分）。
+- **表达方式**：冷静、务实。把「能做到什么」和「应该做什么」分开写，并明确标出取舍。给权衡，不给裁决：每个关键选择写代价、备选与重新评估条件；要用户拍板的问题附各选项后果，不替用户下结论。
+- **价值排序**（与仓库规则冲突时仓库规则优先）：
+  1. **三次再抽象**：只有一个调用方时不造共享模块、接缝或适配器；第三个同构用例出现前接受受控重复（与 `references/architecture-quality.md` §2 的删除测试互为印证）。
+  2. **无聊技术优先**：优先仓库已有技术栈与已验证范式；引入新依赖或新基础设施必须在 ADR 里回答「现有的为什么不够」。
+  3. **开发效率即架构**：本地起栈、验证入口、回归门和跨对话恢复成本算进设计代价；里程碑可独立验收是这条的直接落点。
 
-除非用户明确只要"简单聊聊思路",完整走全部六步。步骤 2 绝不可跳过——没有调查的计划就是命题作文。
+## 目标与质量门
 
-## 第 0 步:定位模板与范例
+以上述架构师身份收敛范围、追通需求、基于真实代码做决策，并把验证、迁移和运行期后果在计划期定义清楚。计划的目标读者是后续实现者；影响实施的重大问题不能留到实现期重新讨论。
 
-1. **找模板**:依次尝试 ① 用户指定的路径;② `goal/PLAN-TEMPLATE.md`;③ 全仓库 glob `**/PLAN-TEMPLATE*.md`。找到后**通读全文**——模板通常自带元原则、骨架、按类型裁剪指引和写作自检清单,那些就是本 skill 的具体化,以模板为准。
-2. **找不到模板**:用本 skill 自带的通用骨架 `references/plan-skeleton.md`,并向用户说明"项目无计划模板,采用通用骨架"。
-3. **找范例**:在模板同目录(或用户指定的计划目录)里挑 1-2 份**与本次计划同类型**的已完成计划(新独立模块型 / 既有模块增量型 / 纯前端型…),粗读其 §0 与里程碑节,校准"这个项目里的好计划长什么样"——尤其是决策表的颗粒度和验证的写法。模板若点名了样板文档,优先读那几份。
+一份计划同时过四道门：
 
-## 第 1 步:需求解析与定性
+1. **事实可靠**：现状、复用点、契约、数字和路径能追溯到用户原话或本次读过的代码/文档。
+2. **决策合理**：关键选择有驱动因素、真实备选、代价与重新评估条件；不因“仓库里已有”就机械照抄。
+3. **实施闭环**：范围、接口、失败语义、迁移、验证和里程碑互相一致，未决阻塞不会伪装成可执行方案。
+4. **进度可恢复**：计划顶部用简要状态和记录索引支持续做；新对话先读仓库规则、计划和当前工作树，只在核验证据、排错或接续未完工作时读取相关记录。
 
-1. **逐条编号**用户的原始需求(R1、R2…)。这张清单贯穿始终:最终计划的"需求 → 设计映射"表必须逐条覆盖它,一条都不许吞。用户一句话里往往藏着多条需求,拆开;含糊的地方先记下,带着问题去调查。
-2. **定性计划类型**(新独立模块 / 既有模块增量 / 纯前端 / 平台横切面…),决定骨架怎么裁剪、去读哪份范例、调查往哪个方向使劲。
-3. **识别"必须有人拍板"的产品决策**——真正影响范围与形态、无法从代码或惯例推出的那种(比如"面向管理员还是全员""要不要独立计费")。交互场景下现在就问用户;无法交互则选一个有依据的默认并把它连同理由写进计划的"开放问题"节,**不许默默替用户做重大产品决策而不留痕**。
+## 交付约定
 
-## 第 2 步:代码事实调查(重头戏)
+- **模板**：除非用户显式指定另一份模板，否则必须通读并使用本 skill 自带的 [references/plan-skeleton.md](references/plan-skeleton.md)。不要探测或依赖仓库内的 `PLAN-TEMPLATE`；出仓后的目标仓通常没有它。除开头固定的「实施须知」外，计划正文不提用了哪份 skill、骨架或参考——读者是实现者，写作用了什么工具与他无关。
+- **落盘**：用户指定路径优先；否则仓库根存在 `goal/` 时写 `goal/<代号>.md`，不存在时写 `docs/plan/<代号>.md`（按需创建目录）。目标文件已存在时先确认再覆盖。
+- **范例**：输出目录里若有同类型旧计划，可选读 1–2 份校准项目惯例；旧计划只是样例，不是事实源，路径、行为和数字仍须核实。
+- **代码基线**：Git 仓库中记录调查日期、commit SHA 和工作区是否 dirty；非 Git 仓库记录调查日期与可用版本标识。dirty 时说明相关事实来自当前工作树，不能只写 HEAD。只保留最近一次核对的一条基线，改稿时就地更新，不追加复核经过。
+- **计划状态**：使用 `Ready`、`Blocked` 或 `Proposed`。影响范围、安全、数据、外部契约或关键 NFR 的问题未决时必须是 `Blocked`；设计完整但等待非阻塞评审时可为 `Proposed`；无实施阻塞才是 `Ready`。顶部状态行只写状态，定级理由写 §11，实施进展只写「实施进度」。
+- **实施进度**：计划顶部是进度的唯一汇总入口，初稿初始化恢复快照和空的完成记录。实现与验收详情按里程碑保存在计划旁的 `<计划文件名去扩展名>.records/M<n>.md`，只留结果、验证证据与续做所需缺口；子任务不默认另建过程文档，不预建空记录。
 
-写计划前先把地基打在事实上。有子代理(Explore/general-purpose)就**并行**派活,每路带明确问题;仓库小或问题窄时自己搜也行。五路调查:
+## 控制计划与执行成本
 
-| 路 | 问题 | 产出 |
-| --- | --- | --- |
-| **现状盘点** | 与本需求相关的功能现在有什么?(路由、表、UI、服务、配置) | 现有能力清单 + 路径;避免重复造和漏改 |
-| **复用范式** | 全仓库里与要做的东西**最同构的既有实现**是哪个?它的关键文件在哪? | "照抄 `<具体文件路径>` 范式"级别的锚点,而非"参照既有做法" |
-| **上游契约核对** | 本计划要读写的每一个既有模块/服务的接口,现状够不够用? | 每个上游一条:**「已核实(`路径`):零改动」或精确增量清单**——没有第三种状态 |
-| **端口/环境/命名现状** | 端口表、环境变量、命名空间的**当前真值**(读实际配置文件,不信旧文档) | 新增件不与现状冲突的依据 |
-| **已知坑搬运** | memory 目录、CLAUDE.md、旧计划的 PROGRESS/DEFERRED 文档里,与本计划相关的坑 | 一行一坑 + 出处,直接搬进计划的"已知坑"节 |
+- **信息只展开一次**：已有 PRD 就沿用需求 ID，以来源、差异和设计/验收链接建账本，不复制验收原文。账本已覆盖需求 → 设计 → 验证时，省略末尾重复映射表；接口、NFR、风险在所属章节定义，其余位置引用。保留影响实现的精确信息，删去重复解释。
+- **里程碑围绕可验证成果**：不要把每个模块或工种都升成独立里程碑。同一能力、同一环境且无独立发布/回滚或风险门的工作，可合成一个里程碑，内部保留任务依赖和局部检查。独立安全、数据迁移、不可逆操作、发布及用户约定的分期门仍单列。
+- **开发前置不等于终验前置**：依赖写到实际需要的契约/子任务与验证，不默认等待上游整个里程碑；前置检查必须证明该成果可用。端到端走查、全量回归、故障演练和评测可集中到阶段收口，各里程碑保留自身新增行为与风险的检查；阶段收口通过前不得宣称整期或整条跨期需求已验收。
+- **验证与证据复用**：§9 定义检查 ID/测试组、覆盖的需求或验收行、环境与执行时点，里程碑引用检查 ID，不重抄断言。执行时点须晚于所需能力/环境就绪，不让骨架里程碑验收尚未实现的端到端路径。同一部署可合并 API/UI 主路径走查；相关代码、配置、依赖、输入与环境未变时复用已通过证据，变更后重跑受影响检查，阶段收口跑必要集成回归。重构仍先建立行为基线。
 
-产出一份**《事实清单》**(工作产物,不直接进计划),每条带标签与来源:
+## 流程总览
 
+```text
+0. 读取骨架并锚定基线 → skill 模板、输出路径、commit/dirty 状态
+1. 建需求账本         → R / NFR / C / A，定计划类型与阻塞决策
+2. 调查代码事实       → 现状、同构实现、契约、运行配置、历史坑
+3. 设计接口与备选     → 必要时做接缝/依赖分析与 Design It Twice
+4. 决策并撰写         → ADR-lite、职责边界、正文、迁移与验证
+5. 自检与定级         → 路径、映射、一致性、失败闭环、Ready/Blocked
 ```
-[现状]  SPMS issue 表已有 ai_assigned 字段但未使用 (apps/spms-server/src/db/schema.ts)
-[契约·已核实] files-server presign 面覆盖本需求,零改动 (apps/files-server/src/routes/presign.ts)
-[契约·增量]   通知服务缺服务态入口 → 需加 scope 一项 + notify.ts 服务态变体 (P0,漏则 M3 卡死)
-[坑]    seed 后租户 UUID 重生成,跨库引用要重解析 (memory: reseed-recovery)
-[开放]  未查到 X 的现有实现;是否自建待产品拍板
-```
 
-**红线:没读过的代码不许写"已核实"。** 调查中发现需求与代码现实冲突(比如用户以为存在的能力其实没有),这是重要发现——如实呈现并给出替代方案,不要顺着错误假设写下去。
+除非用户明确只要轻量思路，完整执行。计划评审模式从第 1 步开始，把既有计划中的陈述当作待核实主张，不因文档写了“已核实”就直接相信。
+
+## 第 0 步：骨架、输出与基线
+
+1. 通读 `references/plan-skeleton.md`；用户显式给了模板时，通读用户模板并以其章节结构为准，但仍保留本 skill 的事实、决策和就绪门。
+2. 按“用户指定 → 已有 `goal/` → `docs/plan/`”确定目标路径。不要在仓库里搜索其他模板。
+3. 记录代码调查基线。先读仓库根及相关子目录的 `AGENTS.md`、`CLAUDE.md` 或等价规则文件；项目规则高于通用骨架。读规则是为了约束设计，**规则清单本身不进计划**：有约束的条目落成 `C-*` 或第 12 节的一行一坑（带规则路径与被约束的具体行为），读过但无约束的文件一个字都不写。
 
-**核实要核到行为,不止存在。** 「已核实」的对象是**计划所依赖的那个行为**——文件存在、函数同名、接口能调通,都不等于契约成立;实现期最贵的返工全部来自"行为想当然"。事实清单里凡属以下类别,必须把行为细节(数字、语义)抄进来:
+## 第 1 步：需求账本与计划定性
 
-- **分页/批量推进**:上游接口有没有 offset/cursor?"重复调用"会推进到下一批,还是永远命中同一批?你的方案若依赖"分批扇出",这一条不核实等于整个机制不成立。
-- **限流/配额/上限**的具体数值与作用域(每租户?每调用方?每分钟?),超限行为是排队还是失败。
-- **鉴权模板的 claims 形状**:要照抄的 gate 里到底有没有 `permissions`/`bypass`?抄了一个没有权限位的 gate,再叠"按权限下放"的设计就是空中楼阁。
-- **密钥/加密的密钥域**:复用的加密函数绑的是哪个 env/密钥?轮换/灾备是否与你的数据绑死在别人的密钥上?
-- **框架层行为**:如框架校验失败先于业务闸返 4xx——"业务错误一律 200"的承诺需要宽 schema/手动解析才能兑现,计划里要写明。
-- **事务/失败语义**:被复用的"钩子/发射点"在事务内还是事务外?进程崩溃时丢不丢?你承诺的可靠性等级(at-least-once 等)必须与之相容。
+把输入拆成四类，并在需求账本或映射表逐条覆盖（保留一份完整映射即可）：
 
-## 第 3 步:决策先行
+| 类型 | 内容 | 规则 |
+| --- | --- | --- |
+| `R-*` | 用户可见功能与业务规则 | 每条有设计落点、验收或显式排除 |
+| `NFR-*` | 性能、容量、可用性、可靠性、安全、隐私、可观测性、运维、成本、可维护性 | 只保留受本需求影响的类别 |
+| `C-*` | 技术栈、兼容性、交付、时间、法规和仓库硬约束 | 标明来源，不把惯例误写成用户需求 |
+| `A-*` | 暂未证实但设计暂时依赖的假设 | 写验证办法、影响和责任人；重大假设未决则 Blocked |
 
-正文之前先把 §0 钉死——所有实现期会引发争论的点(形态/协议/凭证/权限/边界/复用策略)在这里一次拍完:
+- 未给出的吞吐、p95、可用性、RPO/RTO、预算等数字不得套用行业示例。能从现有 SLO/配置继承就带路径引用；否则写“未知”，说明它会改变哪个决策以及何时必须确认。
+- 定性计划类型：新模块、既有模块增量、纯前端、重构/深模块化、数据迁移、平台横切面或跨系统集成。类型决定需要加载哪些按需参考与裁剪哪些章节。
+- 真正改变产品形态、权限、数据归属或外部承诺且无法从证据推出的选择，应尽早请用户拍板；不能交互时不得默默代决。
 
-- **决策表**:每行 = 决策点 + 选择 + **含义**(对部署件/既有代码/边界的影响;能"零改动"的明说)。只写选择不写影响的决策等于没做。
-- **职责边界**:一张"谁拥有什么"的表 + 一句话把职责切死,实现期所有"要不要顺手做"回来看这句。
-- **关键取舍**:每条 = 选择 → **代价**(显式承认) → 缓解/兜底(实在缓解不了就写"风险显式承认")。重点覆盖:降级路径、幂等/重试、**并发与竞态**(两个层面都要:① 后台 worker/队列写清原子认领、基于截止时间的僵尸判定、计数器原子更新——读后写的熔断计数、按旧时间戳清扫 running 这类竞态在计划期就要堵死;② 普通请求路径上**任何跨请求的 check-then-write**——先查状态再写入的流程(如"检查问卷开放→插入答卷"对上"管理员并发关闭")必须写明事务内锁或条件写)、**数据生命周期**(每张新表对其引用的实体逐个走查"被删/被转移/被失效"场景:FK/NOT NULL/UNIQUE 约束必须与声明的回退语义相容——写着 NOT NULL 外键又承诺"删除后回退占位"是自相矛盾;快照列注明每条写路径的**服务端权威来源**,绝不信前端传值)、安全收口、显式截断、回归风险及其门。
-- **明确不做**:所有容易蔓延的相邻功能逐条出表,**每条给去向**(二期 / 另立项 / 依赖某底座就绪)。产品经理的价值一半在这张表上——评审时会被问"那 X 呢"的都要提前出现在这。
+## 第 2 步：代码事实调查
 
-## 第 4 步:撰写正文
+调查至少覆盖与需求相关的五个方向，窄任务可合并，但不能跳过关键方向：
 
-照模板骨架 + 类型裁剪写。通用写作规矩(与模板自身指引冲突时以模板为准):
+| 方向 | 要回答的问题 | 产出 |
+| --- | --- | --- |
+| 现状盘点 | 已有哪些路由、表、UI、服务、脚本与配置？ | 能力与缺口，带路径 |
+| 复用范式 | 最同构的实现是什么，其行为真的适配吗？ | 具名到文件/符号的复用锚点与差异 |
+| 契约核对 | 每个上游/下游行为是否满足计划？ | 已核实足够 / 已核实缺口 / 未核实阻塞 |
+| 运行真值 | 端口、env、命名、部署、迁移和验证入口是什么？ | 从实际配置读出的不冲突依据 |
+| 历史约束 | 规则文件、进度/延期文档、事故或迁移记录有哪些相关教训？ | 一行一坑 + 出处 |
+
+事实清单使用三态，不再强行二选一：
+
+```text
+[已核实·足够] <行为与语义> (<路径/符号>)
+[已核实·缺口] <现状> → <最小增量> → <漏做后果> (<路径/符号>)
+[未核实·阻塞] <缺什么证据> → <影响的决策> → <如何解除>
+```
 
-1. **复用具名到文件路径**——"照抄 `apps/xx/src/lib/gate.ts` 范式",禁止"参照既有做法"。
-2. **数字来自调查**——端口、表名、scope 名、上限值,全部来自第 2 步的事实清单,不来自记忆或旧文档。
-3. **热查询点名索引**——汇总/列表/统计查询的过滤列,要么指出已有索引(带名字),要么写进迁移新增;别让聚合裸扫大表。
-4. **闸门有顺序,错误面要对齐**——同一端点叠多道闸(存在性/scope/角色/成员资格)时写明顺序;计划承诺的错误码必须是**第一道会失败的闸**真正抛出的(先查成员再查存在性,非成员对不存在的资源拿到的就是 403 而非 NOT_FOUND——想承诺 NOT_FOUND 就得先查存在性);每类拒绝写明传输层 status(4xx)还是业务错误(200+错误体),验证章节按此断言。
-5. **每个里程碑自带验收**——里程碑表每行的"验证"列非空(脚本断言 + 真实环境走查);上一步不绿不进下一步;重构类步骤以"既有验证全绿"为回归门。
-6. **安全项 = 可断言项**——安全清单每条都要能翻译成一条验证断言,写不出断言的不算安全项。
-7. **需求 → 设计映射兜底**——结尾一张表,R1…Rn 逐条指到具体章节 + 机制 + 验证脚本;项目硬约束(多租户/i18n/设计规范等)也入表;排除项汇总指到"明确不做"。
-8. **规模感**:参考模板给的行数区间(无模板时 200-500 行);范围决策约 1/3、验证约 1/4——这两块薄了计划就不可执行。调查过程的原始材料**不要**倾倒进计划,计划只留结论 + 路径。
+“已核实”必须核到计划依赖的行为，而非只确认文件或函数存在。涉及分页推进、配额、claims、密钥域、事务、失败语义或框架错误面时，读取 [references/architecture-quality.md](references/architecture-quality.md) 的“行为级核实”节。
 
-## 第 5 步:自检与收尾
+## 第 3 步：接口、接缝与备选设计
 
-1. **过模板自检清单**(模板通常自带;没有就用 `references/plan-skeleton.md` 末尾的通用版),逐项打勾,不过的回去改。
-2. **路径真实性**:跑 `scripts/check_paths.sh <计划文件> <仓库根>`,列出计划中引用但不存在的路径;逐条人工判断——★新增文件与占位符本来就不存在(正常),**"复用/已核实"类路径出现在 MISSING 里就是虚构,必须修**。
-3. **需求映射全覆盖**:对照第 1 步的 R1…Rn 逐条核对映射表,有空格说明设计有洞。
-4. **交叉一致性自检(抓自相矛盾)**:换上实现者的眼睛把全篇重读一遍——计划是分章节写出来的,各章节各自合理但互相打架是最常见的深层缺陷。专抓四类:
-   - 机制章节用到的每个 scope/服务态调用/凭证,反查 seed/SA/清单章节确实配了——设计用了 `directory.read` 而服务账号只给了 `notification.send`,实现期必卡死;
-   - 验证章节的每条断言在设计章节有依据——不许"验收要求了设计里不存在的东西"(如断言 CSV 含备注列,而设计定义的 CSV 没有该列);
-   - 承诺的不变量互不冲突——"信封 id 恒定"与"重投递克隆新行"不能同时成立,发现即回去改设计;
-   - 新增的每个标识符(错误码/共享包导出/env/部署 values 字段)都有对应的登记文件项——漏一处 typecheck/部署就断;
-   - 每个权限/角色/开关位**逐跳追通**:UI 入口可见性 → token/bootstrap 载荷 → 服务端真闸——任何一跳不携带该位就是断链(后端支持 bypass 删除但 bootstrap 不返 bypass、发了角色模板但服务端只认租户 role,都是这类);
-   - 同一口径(导出格式、通知语义、上限值)在全篇多处出现的,逐处对齐——在一处修正的决定必须同步到其余所有提及处,只修一处等于没修。
-5. **落盘**:默认写到项目的计划目录(与模板/范例同目录),命名循既有惯例(如 `goal/<代号>.md`);目标文件已存在时先确认再覆盖。
-6. **汇报**:向用户交付时,除了计划路径,单独列出:① 留给用户拍板的开放问题;② 调查中发现的、与用户假设冲突的事实;③ 你替用户砍掉/推迟的范围(让用户有机会否决)。
+出现以下任一情况时，必须完整读取 [references/architecture-quality.md](references/architecture-quality.md)：新增共享模块或跨系统契约、重构既有模块、引入远程/外部依赖、改变数据生命周期、要求不停机迁移，或存在显著可靠性/运维风险。局部文案、样式或简单单模块增量不为填表而造架构。
 
-## 红线(任何情况下不违反)
+复杂计划至少完成：
 
-- **只写计划,不动手实现。** 交付物是计划文档;用户要实施会另说。
-- **不虚构核实。** "已核实"三个字后面必须是本次真读过的路径。
-- **不缩水验证。** 验证章节 + 里程碑验收占计划近一半篇幅是特征不是浪费——砍这里等于交付一份不可执行的愿望清单。
-- **不吞需求。** 用户的每条原始需求,要么有设计落点,要么被显式排除并给出去向,没有第三种下场。
+- 找出承载复杂行为的模块、调用者、接口与接缝；接口包括不变量、调用顺序、错误、配置和性能语义，不只是类型签名。
+- 按进程内、本地可替代、远程但自有、真正外部依赖分类，选择真实实现和测试替身；没有变化需求时不凭空增加 adapter。
+- 对形态、接缝、跨服务协议、数据归属、可靠性等级或迁移策略等高影响决策，提出至少两个真正可行且有实质差异的候选，按需求适配、局部性、迁移、失败、运维、测试和成本比较。简单可逆选择无需形式化比较。
+- 画图只在三个以上节点、异步时序、所有权或状态迁移用文字难以看清时使用；图必须表达关系，不能只是装饰。
 
----
+## 第 4 步：决策与正文
+
+按骨架裁剪撰写：
+
+- 普通决策表写“决策点、选择、含义、依据”；关键且难回退的决策再写 ADR-lite：背景/驱动因素、备选、选择、正负后果、重新评估触发条件。
+- 职责边界写清谁拥有事实、策略和失败恢复；“复用”必须具名到本次读过的路径与行为差异。
+- 数字只能来自用户、代码/配置、项目规则或明确决策。热查询说明已有索引或迁移增量；未知规模不靠猜测决定新基础设施。
+- 多道闸写执行顺序，错误码与第一道实际失败的闸一致；安全、可靠性和 NFR 条目都要能转成可观察的验证。
+- 涉及持久化、对外契约或滚动部署时，写清兼容窗口、expand/migrate/contract、回填/重放、发布与回滚门。
+- 每个里程碑有明确退出条件，局部检查与阶段终验按上文分工；验收合并须说明共同环境、覆盖范围和保留的风险门，不能只删检查或延后风险发现。
+- 写清实际前置成果及验证、可并行范围与共享文件/资源的单一负责人。前置已满足、契约稳定且互不干扰才可并行；按任务规模与集成成本决定是否委派，不为并行硬拆。复杂调度按需读 [references/execution-workflow.md](references/execution-workflow.md)。
+- 每个里程碑的退出条件逐行以「回写『实施进度』」结尾，防止完成后漏记。
+- 在计划顶部初始化实施进度：总里程碑数、当前状态、最近完成、下一步、阻塞和代码基线必须与里程碑表一致；计划尚未实施时如实写“0/N、尚未开始、下一步 M1”，不得预填完成记录。
+- 骨架开头的“实施须知”及“实施者定位”“实施进度”协议原样带入计划，不改写、不删减：它们是给执行计划的 agent 的完整合同，与写计划的架构师定位是两回事。唯一的填空是“回写后自查”里的 `<进度校验命令>`：本 skill 目录在目标仓内时，换成从仓库根可直接运行的 `bash <本 skill 目录相对仓库根的路径>/scripts/check_progress.sh <计划相对仓库根的路径> .`；不在仓内（全局安装）时把整句改成“每次回写后按上述条目人工核对”，不写本机绝对路径。
+- 计划按风险和改动面裁剪，不用固定行数或章节占比衡量质量；调查原始材料不倾倒进正文，只保留结论与来源。
+
+## 第 5 步：自检、就绪与交付
+
+1. 跑 `"$SKILL_DIR/scripts/check_paths.sh" <计划文件> <仓库根>`，人工区分新增路径与虚构的“复用/已核实”路径。
+2. 对照需求账本或映射表检查 `R-* / NFR-* / C-* / A-*`：每条有设计、验证、排除去向或阻塞说明；同一事实和断言没有多处展开。
+3. 按 `references/architecture-quality.md` 的一致性清单检查凭证/scope、接口/调用方、数据约束/生命周期、设计/验证、发布/回滚和多处重复口径。
+4. 建失败模式表：高影响失败至少写触发、爆炸半径、数据后果、用户表现、检测、恢复与验证；简单局部任务可说明“不引入新的运行期失败模式”及依据。
+5. 检查顶部实施协议为骨架原文在位、`<进度校验命令>` 已替换；每个里程碑退出条件以「回写『实施进度』」结尾，依赖与并行边界明确，阶段收口覆盖被集中的验收且保留必要风险门；跑 `"$SKILL_DIR/scripts/check_progress.sh" <计划文件> <仓库根>` 确认进度与里程碑一致、记录链接有效；初稿不预填完成事实，详情不写回计划。
+6. 最终定级：存在影响范围、安全、数据、外部契约或关键 NFR 的未决项即 `Blocked`；只等非阻塞评审为 `Proposed`；所有实施前置已解决才是 `Ready`。
+7. 汇报计划路径与状态，并单列：待拍板问题、与用户假设冲突的事实、被砍/推迟的范围、未在真实环境完成的调查或验证。
 
-## 本仓库(xgent-ai-portal)默认值
+评审既有计划时，默认只输出问题、证据、严重度和修订建议；用户明确要求改稿时才覆盖原计划。改稿把结论直接改进正文与对应决策、刷新调查基线；评审出处、采纳/拒绝理由和修订经过留在评审报告与提交说明，不写进计划。
 
-在本仓库使用时,以下路径与惯例直接采用,不必重新探测:
+## 红线
 
-- **模板**:`goal/PLAN-TEMPLATE.md`(自带元原则 §A、骨架 §B、类型裁剪 §C、写作自检 §D——以它为准)。计划落盘到 `goal/<大写代号>.md`。
-- **样板计划**:新独立 App 型读 `goal/GIT.md` 或 `goal/LMS-RESOURCE.md`;既有 App 增量型读 `goal/PMS-MCP.md`。
-- **端口真值**:`apps/web/vite.config.ts` + 根 `package.json` 的 `dev:all`——别信旧文档端口图。
-- **已知坑来源**:`~/.claude/projects/-Users-rockie-Documents-GitHub-xgent-xgent-ai-portal/memory/`(先看 `MEMORY.md` 索引)、根 `CLAUDE.md`、`goal/*-PROGRESS.md` / `*-DEFERRED.md`。
-- **平台硬约束**(必进需求映射表):多租户隔离(全表 `tenantId`);业务状态一律 200 + `{ok,data}`(HTTP status 只表传输层);字典表 `sort` 规范;三语 i18n;前端两步法(`impeccable` 设计 + Chrome 真浏览器验证);列表接口 `Page<T>` 服务端分页。
-- **新独立 App 的同构基线**:独立后端(Elysia + Drizzle + 独立 Postgres 库 `xgent-<key>`)+ TDT 自省 gate + 前端经 host `sdk.callService` + 应用市场 listing seed + `verify-*.ts` 脚本挂 `verify:all`——决策表第一行"形态"从这里出发。
+- 写作/评审模式不实施功能；用户已要求按计划实施时，按计划顶部两节直接实施，无需重复请求授权。
+- 未读过的代码不写“已核实”，没有来源的数字不写成目标或现状。
+- 不吞需求，不把重大假设藏进正文，不把阻塞计划标为 `Ready`。
+- 不把未通过退出条件的里程碑写成已完成，不用聊天记录代替计划内的简要进度与独立的实现/验收记录；不在续做时批量加载历史记录。
+- 不为假想扩展造接缝、基础设施或抽象，也不照搬通用架构示例覆盖仓库现实。
+- 计划里不写写作过程（开头固定的「实施须知」除外）：用了哪份 skill / 模板 / 参考资料、读过哪些规则文件的清单、调查或复核做了几轮、评审意见的采纳与改稿经过、“本次只写/修订计划、未实施”这类写作当时的状态、“本轮/刚才”这类只在写作对话里成立的指代（来源写“用户 YYYY-MM-DD 确认”）。它们既不是实施事实也不是里程碑进展，会随实施过期、误导实施者、白占上下文；提到 skill 还会诱导实施者去加载只有写计划才需要的内容。
+- 不在出仓 skill 中硬编码某个仓库的模板、技术栈、端口、样板计划、本机路径或业务约定；这些必须在运行时从目标仓规则和代码读取。