skill-issues

宿主：Codex CLI — 此技能最初为 Claude Code 设计，后适配至 Codex。 交叉引用命令在 Codex 中使用已安装的技能名称，而非 /octo:* 斜杠命令。 使用当前 Codex shell 和子 Agent 工具。在当前会话尚未提供相关能力之前，不要声称可使用某个提供商、模型或宿主子 Agent。 宿主工具的对应项请参阅 skills/blocks/codex-host-adapter.md。

问题跟踪

概述

跨会话问题跟踪，用于持续管理问题。问题存储在 .octo/ISSUES.md 中，并会在多个 Claude Code 会话之间保留。

核心原则： 跟踪 → 解决 → 学习。

适用场景

在用户希望执行以下操作时使用此技能：

• 跟踪问题或阻塞项，以便稍后处理
• 记录开发过程中发现的问题
• 跨会话查看未解决的问题
• 将问题标记为已解决
• 查看特定问题的详情

请勿用于：

• GitHub 问题管理（使用 gh CLI）
• Git 跟踪的问题（使用 git 命令）
• 临时待办事项（使用任务计划工具）

子命令

1. 列出问题（默认）

触发方式： /octo:issues 或 /octo:issues list

以表格形式显示所有未解决的问题：

## Open Issues

| ID | Severity | Category | Description | Created | Phase |
|----|----------|----------|-------------|---------|-------|
| ISS-20260203-001 | high | integration | Auth not working | 2026-02-03 | Develop |
| ISS-20260203-002 | medium | performance | Slow query performance | 2026-02-03 | Deliver |

模式检测： 列出问题后，检查是否有 3 个或更多未解决问题属于同一类别。如果有，请提醒：

⚠ Pattern detected: 3 open issues in category "integration" — may indicate a systemic problem.

实现：

1. 检查 .octo/ISSUES.md 是否存在
2. 如果不存在，则根据模板初始化
3. 读取并解析 Open Issues 部分
4. 以表格形式显示

2. 添加问题

触发方式： /octo:issues add <description>

添加新问题并自动生成 ID。

流程：

第 1 步：收集信息

使用 AskUserQuestion 提出两个问题：

AskUserQuestion({
  questions: [
    {
      question: "What severity is this issue?",
      header: "Severity",
      multiSelect: false,
      options: [
        {label: "critical", description: "Blocks all progress"},
        {label: "high", description: "Significant impact"},
        {label: "medium", description: "Should address"},
        {label: "low", description: "Nice to fix"}
      ]
    },
    {
      question: "What category does this issue fall into?",
      header: "Category",
      multiSelect: false,
      options: [
        {label: "logic-error", description: "Incorrect behavior or wrong output"},
        {label: "integration", description: "Cross-component or API compatibility"},
        {label: "quality-gate", description: "Quality gate failures during workflows"},
        {label: "security", description: "Security vulnerabilities or concerns"},
        {label: "performance", description: "Speed, memory, or scalability issues"},
        {label: "ux", description: "User experience or usability problems"},
        {label: "architecture", description: "Structural or design pattern issues"}
      ]
    }
  ]
})

第 2 步：确定当前阶段

# Check if STATE.md exists
if [ -f .octo/STATE.md ]; then
  grep "current_phase:" .octo/STATE.md
else
  echo "Unknown"
fi

第 3 步：生成问题 ID

格式： ISS-YYYYMMDD-NNN

# Get today's date
TODAY=$(date +%Y%m%d)

# Find existing issues for today
grep "ISS-${TODAY}-" .octo/ISSUES.md | tail -1

# Increment sequence number
# If ISS-20260203-001 exists, next is ISS-20260203-002

第 4 步：追加到 ISSUES.md

在 Open Issues 表格中添加新行：

| ISS-20260203-003 | medium | performance | Slow query performance | 2026-02-03 | Develop |

保留现有问题——仅追加，不要覆盖。

第 5 步：确认

✅ Issue created: ISS-20260203-003

**Severity:** medium
**Category:** performance
**Description:** Slow query performance
**Created:** 2026-02-03
**Phase:** Develop

View with: /octo:issues show ISS-20260203-003

3. 解决问题

触发方式： /octo:issues resolve <id>

将问题标记为已解决，并移至 Resolved 部分。

流程：

第 1 步：验证问题是否存在

# Check if issue ID exists in Open Issues
grep "ISS-20260203-001" .octo/ISSUES.md

如果未找到，则显示错误：

❌ Issue ISS-20260203-001 not found in open issues.

Use `/octo:issues list` to see all open issues.

第 2 步：询问解决说明

**Resolving issue:** ISS-20260203-001

Please provide resolution notes:

第 3 步：移至 Resolved 部分

1. 从 Open Issues 表格中提取问题行
2. 从 Open Issues 中移除
3. 添加到 Resolved Issues，并附上解决日期和说明

Resolved Issues 格式：

| ID | Severity | Category | Description | Created | Resolved | Resolution |
|----|----------|----------|-------------|---------|----------|------------|
| ISS-20260203-001 | high | integration | Auth not working | 2026-02-03 | 2026-02-04 | Fixed OAuth token refresh |

第 4 步：确认

✅ Issue resolved: ISS-20260203-001

**Resolution date:** 2026-02-04
**Resolution notes:** Fixed OAuth token refresh

View with: /octo:issues show ISS-20260203-001

4. 显示问题详情

触发方式： /octo:issues show <id>

显示特定问题的完整详情。

流程：

第 1 步：查找问题

在 Open 和 Resolved 部分中搜索问题 ID。

第 2 步：显示详情

对于未解决的问题：

## Issue Details: ISS-20260203-001

**Status:** Open
**Severity:** high
**Category:** integration
**Description:** Auth not working
**Created:** 2026-02-03
**Phase:** Develop

**Actions:**
- Resolve: `/octo:issues resolve ISS-20260203-001`

对于已解决的问题：

## Issue Details: ISS-20260203-001

**Status:** Resolved
**Severity:** high
**Category:** integration
**Description:** Auth not working
**Created:** 2026-02-03
**Resolved:** 2026-02-04
**Resolution:** Fixed OAuth token refresh

第 3 步：如果未找到

❌ Issue ISS-20260203-001 not found.

Use `/octo:issues list` to see all open issues.

文件管理

初始化 ISSUES.md

时机： 首次使用此技能，或 .octo/ISSUES.md 不存在时。

操作：

# Create .octo directory if needed
mkdir -p .octo

# Copy template
cp ${HOME}/.claude-octopus/plugin/config/templates/ISSUES.md.template .octo/ISSUES.md

# Replace {{PROJECT_NAME}} with actual project name
PROJECT_NAME=$(basename $(pwd))
sed -i '' "s/{{PROJECT_NAME}}/$PROJECT_NAME/g" .octo/ISSUES.md

保留现有问题

重要： 添加或解决问题时，绝不要覆盖现有内容。

模式：

# Read existing content
EXISTING=$(cat .octo/ISSUES.md)

# Modify specific section only
# Append new issue to Open Issues table
# OR move issue from Open to Resolved

# Write back with all content preserved
echo "$MODIFIED" > .octo/ISSUES.md

ID 生成算法

格式： ISS-YYYYMMDD-NNN

示例： ISS-20260203-001

实现：

#!/bin/bash

# Get today's date in YYYYMMDD format
TODAY=$(date +%Y%m%d)

# Find all issues created today
TODAY_ISSUES=$(grep -o "ISS-${TODAY}-[0-9]\{3\}" .octo/ISSUES.md || echo "")

if [ -z "$TODAY_ISSUES" ]; then
  # No issues today, start at 001
  NEXT_NUM="001"
else
  # Get highest number for today
  HIGHEST=$(echo "$TODAY_ISSUES" | sed "s/ISS-${TODAY}-//" | sort -n | tail -1)
  
  # Increment
  NEXT_NUM=$(printf "%03d" $((10#$HIGHEST + 1)))
fi

# Generate ID
ISSUE_ID="ISS-${TODAY}-${NEXT_NUM}"
echo "$ISSUE_ID"

严重级别

级别	含义	示例
critical	阻碍所有进展	生产环境宕机、数据丢失
high	影响重大	功能损坏、安全问题
medium	应当处理	性能下降、UX 问题
low	有空可修复	小问题、外观问题

与其他技能集成

与 skill-debug 配合

User: "track this bug for later"

1. Use skill-issues to create issue
2. Use skill-debug to investigate if time permits
3. Link issue ID in debug notes

与 skill-task-management 配合

User: "add fixing ISS-20260203-001 to todos"

1. Use skill-task-management to add todo
2. Reference issue ID in todo description
3. Mark issue as resolved when todo completes

与 flow-develop 配合

User: "implement fix for ISS-20260203-001"

1. Use flow-develop to implement fix
2. Use skill-issues to resolve issue after fix
3. Link commit SHA in resolution notes

最佳实践

1. 清晰描述

良好示例：

Auth token refresh fails after 15 minutes

较差示例：

Auth broken

2. 合理设置严重级别

Critical： 仅用于会阻止所有工作的阻塞项
High： 影响重大，但存在变通方法
Medium： 应当修复，但不紧急
Low： 有则更好

3. 解决说明

良好示例：

Fixed OAuth token refresh by updating expiration logic in auth.ts
Commit: abc123

较差示例：

Fixed

常见模式

模式 1：开发期间跟踪

User: "track this issue: API rate limiting not working"

Action:
1. Create issue with appropriate severity
2. Record current phase from STATE.md
3. Continue development

模式 2：修复后解决

User: "resolve ISS-20260203-001, fixed in commit abc123"

Action:
1. Ask for resolution notes
2. Move to Resolved section
3. Record resolution date and notes

模式 3：查看未解决的问题

User: "what issues do we have?"

Action:
1. List all open issues
2. Show severity and phase
3. Offer to show details or resolve

危险信号——不要这样做

操作	错误原因
覆盖 ISSUES.md	丢失所有现有问题
跳过严重性验证	文件中的数据无效
重复问题 ID	ID 冲突
描述含糊	无法记起问题是什么
解决时不写备注	没有处理记录

快速参考

用户意图	技能操作	输出
“列出问题”	读取并显示未解决的问题	问题表格
“添加问题 X”	生成 ID 并追加到文件	已创建问题
“解决 ISS-X”	移至已解决部分	已解决问题
“显示 ISS-X”	查找并显示详情	问题详情

总结

Issue tracking → Persistent memory across sessions
Otherwise → Forget problems, repeat mistakes

跟踪所有事项。系统地解决问题。从历史中吸取经验。