skills/codex-collab/references/debug-analysis.md

Debug Analysis Template

Template Variables

• {error_message}: Error message or stack trace
• {reproduction_steps}: Steps to reproduce the issue
• {context}: What was happening when the error occurred
• {recent_changes}: Recent code changes that might be related

Prompt Template

请作为调试专家，帮助分析和定位以下问题：

## 错误信息

{error_message}

## 复现步骤
{reproduction_steps}

## 问题背景
{context}

## 最近改动
{recent_changes}

## 分析要求

请提供：

### 1. 问题定位
- 定位到具体的代码位置（文件:行号）
- 说明问题发生的直接原因
- 分析问题的根本原因

### 2. 影响范围
- 影响哪些功能模块
- 影响的用户场景
- 问题的严重程度评估

### 3. 可能的解决方案
- 推荐的修复方案（优先级排序）
- 每个方案的优缺点
- 推荐方案的实现要点

### 4. 预防措施
- 如何避免类似问题
- 需要添加的测试
- 需要改进的地方

### 5. 验证方法
- 如何验证问题已修复
- 需要测试的场景
- 回归测试建议

## 输出格式

1. **问题诊断**（一句话总结）
2. **根本原因分析**（详细说明）
3. **修复方案**（推荐方案+实现建议）
4. **验证清单**

## 搜索指令

请先搜索相关代码：
1. 搜索错误信息中的关键函数或类
2. 搜索相关的模块和文件
3. 查找最近的代码变更
4. 分析调用栈

Usage Example

# When encountering a bug
error_message = """
AssertionError: User should be authenticated
Traceback:
  File "/app/src/api/endpoints/orders.py", line 45, in create_order
    assert current_user.is_authenticated, "User should be authenticated"
  File "/app/src/auth/deps.py", line 23, in get_current_user
    user = decode_token(token)
  File "/app/src/auth/jwt.py", line 67, in decode_token
    raise ExpiredTokenError()
"""

reproduction_steps = """
1. 用户登录后获取 token
2. 等待 30 分钟
3. 使用该 token 创建订单
4. 收到认证错误
"""

context = """
订单创建接口需要用户认证，使用 JWT token。
token 有效期设置为 1 小时。
问题：用户在 token 有效期内但仍然收到认证失败错误。
"""

recent_changes = """
昨天修改了 JWT 解码逻辑，优化了 token 验证流程。
"""

# Call Codex for debug analysis
codex(
    PROMPT=f"""
    <debug template with variables>

    请先搜索以下内容：
    1. src/auth/jwt.py 中的 decode_token 函数
    2. src/api/endpoints/orders.py 中的 create_order 函数
    3. src/auth/deps.py 中的 get_current_user 函数
    4. 查找最近对 jwt.py 的修改
    """,
    cd="/project",
    sandbox="read-only"
)

Follow-up Actions

After receiving debug analysis:

1. Verify Codex's diagnosis by examining the code
2. Discuss the proposed solution if needed
3. Implement the fix
4. Ask Codex to review the fix
5. Add tests to prevent regression