停。在调用任何端点之前，请完整阅读本 SKILL.MD。
评估（Assess）
后退一步，批判性地重新评估项目状态。提供交互式指导（人在环中）和程序化分析（自动化流水线）。专门用于文档修剪和文档-代码对齐。
CLI 使用
# 用于流水线的结构化 JSON 评估
.pi/skills/assess/assess.py run . --output assessment.json
# 从评估结果生成所有图表
create-figure from-assess --input assessment.json --output-dir ./figures/
评估流程
1. 界定评估范围
明确范围（“评估 auth 模块”）→ 直接进行。 开放范围（“后退一步”）→ 询问：关注点？代码质量 vs 文档？已知问题需要跳过？ 文档修剪（“修剪文档”）→ 询问：已弃用的功能？缺失的文档？对齐情况？
2. 查找项目根目录并检测生态系统
通过标记文件（pyproject.toml、package.json、Cargo.toml、go.mod）检测。 读取生态系统特定的元数据，然后是通用文档（README.md、CONTEXT.md、AGENTS.md）。
3. 加载技能清单（路由门控）
对于可能导致“我们应该构建 X”建议的评估，加载 .pi/skills-manifest.json。对于状态检查和纯文档审查则跳过。
cat .pi/skills-manifest.json | python3 -c "
import json, sys
data = json.load(sys.stdin)
print(f'技能数量: {data[\"skill_count\"]} (生成时间: {data[\"generated\"]})')
"
如果清单超过 7 天未更新则发出警告。备用方案：ls .pi/skills/ | wc -l。
4. 快速扫描 → 确认 → 深入分析
- 读取项目元数据、README，进行 glob 遍历以了解结构
- 记录 2-3 个初步观察结果，与用户确认
- 根据用户指导进行深入分析——针对每个发现：是否阻塞？是否已知？修复复杂度？
5. 协作报告
展示发现结果，并询问哪些需要修复。提供 /create-figure 进行可视化。
评估类别
1. 文档-代码对齐
- README 声明与实现对比
- 交叉引用验证（内部链接、代码示例）
- 占位符标记和过时信息
- 弃用：已移除功能的文档
2. 期望 vs 实现
- 桩代码（
pass、raise NotImplementedError）、占位符注释 - 代码结构中存在但无逻辑的功能、未使用的依赖
3. 脆弱代码
- 硬编码值、缺少错误处理、脆弱的正则表达式/解析
4. 非工作代码
- 死代码路径、静默吞没异常、损坏的集成
5. 过度设计代码
- 只有单一实现的抽象、为假设的灵活性而设计的配置
6. 测试覆盖（不可妥协）
检查每个特性/模块是否有测试文件、测试是否通过、边界情况。
标记 pytest.mark.skip 但未注明原因、“0 test collected”、不包含断言的测试。
任务文件审计： 验证每个任务都有包含具体测试/断言的完成定义（Definition of Done）。 如果实现任务缺少完成定义，则阻止执行。
7. 运行良好的部分
肯定代码中的扎实部分，以校准评估。
输出格式
# 评估：<项目名称>
## 摘要
<2-3 句话：整体健康状况、关键发现>
## 发现
### 文档-代码对齐
| 声明 | 现实 | 操作？ |
### 发现的问题
1. **file.py:123** - [问题] — 严重级别：高/中/低 — 建议修复：[简要说明]
### 测试覆盖
| 特性 | 测试状态 | 需要采取的行动 |
### 运行良好的部分
- [值得肯定的扎实代码]
## 建议的后续步骤
1-4 项优先行动。询问从哪一步开始。
策略
- 默认只读 — 未经明确同意绝不写入文件
- 先展示，经同意再写入 — 先展示提议内容，然后提供写入选项
- 协作 — 评估是对话，而非独白
- 运行前询问 — 在运行测试、构建、付费服务前必须先获得许可
- 明智地升级 — 对于复杂/关键问题，建议使用
/review-code - 具体化 — 提供文件路径和行号
- 可操作 — 每个发现都要提出后续步骤
- 测试覆盖不可妥协 — 将缺失测试标记为阻塞项
外部研究
需要时可使用（使用付费服务前需询问）：
/context7— 库文档（免费）/brave-search— 通用网络（免费）/perplexity— 深度研究（付费）
常见错误
# 错误：将所有评估发现视为阻塞性问题
# → 智能体自动为 12 个私有辅助函数添加文档字符串。造成不必要的膨胀。
# 正确：与用户一起审查发现结果。将复杂问题升级给 /review-code。
# 错误：重大更改后跳过 /assess
# → README 示例使用旧的函数签名。用户遇到错误。
# 正确：在编辑核心 API 后运行 assess --focus "doc-code-alignment"
# 错误：根据过时的评估结果运行 /assess
# → 评估来自 3 天前。代码库已发生变化。
# 正确：始终重新运行 assess；切勿跨会话缓存结果