skill-issues

ホスト：Codex CLI — このスキルは Claude Code 向けに設計され、Codex 用に調整されています。 相互参照コマンドでは、/octo:* スラッシュコマンドではなく、Codex にインストールされたスキル名を使用します。 現在の Codex シェルとサブエージェントツールを使用してください。現在のセッションで利用可能であることが確認できるまでは、プロバイダー、モデル、またはホストのサブエージェントが利用可能だと断言しないでください。 ホストのツールに相当するものについては、skills/blocks/codex-host-adapter.md を参照してください。

イシュー追跡

概要

セッションをまたいで問題を継続的に管理するためのイシュー追跡機能です。イシューは .octo/ISSUES.md に保存され、Claude Code のセッションをまたいで保持されます。

基本原則： 追跡 → 解決 → 学習。

使用するタイミング

ユーザーが次のことを希望する場合に、このスキルを使用します：

• 後で対応する問題やブロッカーを追跡する
• 開発中に発見したイシューを記録する
• セッションをまたいで未解決のイシューを確認する
• イシューを解決済みとしてマークする
• 特定のイシューの詳細を表示する

次の用途には使用しないでください：

• GitHub のイシュー管理（gh CLI を使用）
• Git で追跡するイシュー（git コマンドを使用）
• 一時的な ToDo（タスク計画ツールを使用）

サブコマンド

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 を使用して、次の 2 つの質問をします：

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

すべて記録し、体系的に解決し、履歴から学びましょう。