error-diagnosis

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Error Diagnosis Framework

错误诊断框架

When This Activates

触发场景

This skill activates when:

User shares an error message or stack trace
Something failed unexpectedly
Debugging session errors
Need to categorize and prevent errors

当出现以下情况时，该技能会被激活：

用户分享错误信息或stack trace
某操作意外失败
调试会话中出现错误
需要对错误进行分类并制定预防措施

Error Categories

错误分类

1. Prompt Errors (User → Claude)

1. 提示错误（用户→Claude）

Subcategory	Description	Prevention
`ambiguous_instruction`	Could be interpreted multiple ways	Be specific about expected output
`missing_constraints`	Didn't specify what NOT to do	State exclusions explicitly
`too_verbose`	Key requirements buried in text	Put critical info first
`implicit_expectations`	Requirements in head, not prompt	Write everything down
`wrong_abstraction`	Too high/low level for task	Match detail to task complexity

子类别	描述	预防措施
`ambiguous_instruction`	可被多种方式解读	明确预期输出
`missing_constraints`	未说明禁止操作的内容	明确列出排除项
`too_verbose`	关键要求被淹没在文本中	将关键信息放在开头
`implicit_expectations`	要求仅存在于用户脑海中，未写入提示词	将所有要求明确写出
`wrong_abstraction`	抽象级别与任务不匹配	根据任务复杂度调整细节程度

2. Context Errors (Session State)

2. 上下文错误（会话状态）

Subcategory	Description	Prevention
`context_rot`	Conversation too long	Clear context periodically
`stale_context`	Old info polluting responses	Start fresh for new topics
`missing_context`	Assumed Claude remembered	Re-state critical context
`wrong_context`	Irrelevant info drowning signal	Provide focused context

子类别	描述	预防措施
`context_rot`	对话过长	定期清理上下文
`stale_context`	旧信息干扰响应	开启新话题时重新开始会话
`missing_context`	假设Claude已记住相关信息	重新说明关键上下文
`wrong_context`	无关信息掩盖有效信号	提供聚焦的上下文

3. Harness Errors (Agent System)

3. 代理系统错误（Agent System）

Subcategory	Description	Prevention
`subagent_context_loss`	Info didn't reach subagents	Pass explicit context
`wrong_agent_type`	Used wrong specialized agent	Match agent to task
`no_guardrails`	Didn't constrain behavior	Set clear boundaries
`missing_validation`	No check that output correct	Verify results

子类别	描述	预防措施
`subagent_context_loss`	信息未传递给子代理	显式传递上下文
`wrong_agent_type`	使用了错误的专用代理	匹配代理类型与任务
`no_guardrails`	未限制代理行为	设置明确的边界
`missing_validation`	未检查输出是否正确	验证结果正确性

4. Tool Errors (Execution)

4. 工具错误（执行阶段）

Subcategory	Description	Prevention
`wrong_command`	Incorrect command/syntax	Verify syntax before running
`missing_dependency`	Package not installed	Check deps first
`permission_error`	Insufficient permissions	Check access rights
`path_error`	File/directory not found	Verify paths exist
`syntax_error`	Code syntax issue	Lint before running

子类别	描述	预防措施
`wrong_command`	命令/语法错误	运行前验证语法
`missing_dependency`	依赖包未安装	先检查依赖
`permission_error`	权限不足	检查访问权限
`path_error`	文件/目录未找到	验证路径是否存在
`syntax_error`	代码语法问题	运行前进行代码检查

Diagnosis Workflow

诊断流程

Step 1: Categorize

步骤1：分类

Error received → Identify category → Identify subcategory

Error received → Identify category → Identify subcategory

Step 2: Extract Details

步骤2：提取细节

json

{
  "category": "tool",
  "subcategory": "path_error",
  "summary": "File not found when trying to read config",
  "root_cause": "Path was relative but CWD was different",
  "prevention": "Use absolute paths or verify CWD"
}

json

{
  "category": "tool",
  "subcategory": "path_error",
  "summary": "File not found when trying to read config",
  "root_cause": "Path was relative but CWD was different",
  "prevention": "Use absolute paths or verify CWD"
}

Step 3: Generate Fix

步骤3：生成修复方案

Based on category, apply targeted fix strategy.

根据错误类别，应用针对性的修复策略。

Step 4: Record Learning

步骤4：记录经验

Add to ReasoningBank for future reference.

将错误信息添加到ReasoningBank，以备未来参考。

Common Error Patterns

常见错误模式

"Module not found"

Category: tool/missing_dependency
Check: Is the package installed? Right version? Correct import path?
Fix: npm install / pip install / check import statement

Category: tool/missing_dependency
Check: Is the package installed? Right version? Correct import path?
Fix: npm install / pip install / check import statement

"Permission denied"

Category: tool/permission_error
Check: File permissions? Running as correct user? Sudo needed?
Fix: chmod, chown, or run with appropriate privileges

Category: tool/permission_error
Check: File permissions? Running as correct user? Sudo needed?
Fix: chmod, chown, or run with appropriate privileges

"Undefined is not a function"

Category: tool/syntax_error (or context/stale_context)
Check: Is object initialized? Correct method name? Async/await issue?
Fix: Add null checks, verify object shape, await promises

Category: tool/syntax_error (or context/stale_context)
Check: Is object initialized? Correct method name? Async/await issue?
Fix: Add null checks, verify object shape, await promises

"CORS error"

Category: tool/wrong_command (or infrastructure)
Check: Server CORS config? Proxy setup? Credentials mode?
Fix: Configure CORS headers, use proxy in dev

Category: tool/wrong_command (or infrastructure)
Check: Server CORS config? Proxy setup? Credentials mode?
Fix: Configure CORS headers, use proxy in dev

"Claude did the wrong thing"

Category: prompt/* (most likely)
Check: Was instruction ambiguous? Missing constraints? Too much context?
Fix: Rewrite prompt with specific details

Category: prompt/* (most likely)
Check: Was instruction ambiguous? Missing constraints? Too much context?
Fix: Rewrite prompt with specific details

Error Response Template

错误响应模板

When diagnosing an error, respond with:

markdown

undefined

诊断错误时，需按照以下模板回复：

markdown

undefined

Error Analysis

Category: [category/subcategory] Root Cause: [what actually went wrong]

Fix

[specific steps to resolve]

Prevention

[how to avoid this in the future]

Similar Past Issues

[if any relevant observations exist]

undefined

[if any relevant observations exist]

undefined

MCP Tools for Diagnosis

用于诊断的MCP工具

undefined

undefined

Check past similar errors

memory_sessions category=bugfix query="similar error"

Get reasoning bank solutions

reasoning_query context="error description"

Check if this was a known gotcha

memory_sessions category=gotcha query="topic"

undefined

memory_sessions category=gotcha query="topic"

undefined

Learning Integration

学习集成

Errors feed into:

ReasoningBank trajectories
Observation extractor (bugfix category)
Confidence calibration (track error rates by domain)

错误信息会被用于：

ReasoningBank轨迹记录
观察提取器（bugfix类别）
置信度校准（按领域跟踪错误率）