issue-discover

Issue Discover

手動での Issue 作成、視点に基づく検出、プロンプト主導の探索という、3 つの開始方法をカバーする、Issue の検出と作成を統合したスキルです。

アーキテクチャの概要

┌─────────────────────────────────────────────────────────────────┐
│  Issue Discover Orchestrator (SKILL.md)                          │
│  → Action selection → Route to phase → Execute → Summary         │
└───────────────┬─────────────────────────────────────────────────┘
                │
                ├─ request_user_input: Select action
                │
    ┌───────────┼───────────┬───────────┐
    ↓           ↓           ↓           │
┌─────────┐ ┌─────────┐ ┌─────────┐   │
│ Phase 1 │ │ Phase 2 │ │ Phase 3 │   │
│  Create │ │Discover │ │Discover │   │
│   New   │ │  Multi  │ │by Prompt│   │
└─────────┘ └─────────┘ └─────────┘   │
     ↓           ↓           ↓          │
  Issue      Discoveries  Discoveries   │
(registered)  (export)    (export)      │
     │           │           │          │
     │           ├───────────┤          │
     │           ↓                      │
     │     ┌───────────┐               │
     │     │  Phase 4  │               │
     │     │Quick Plan │               │
     │     │& Execute  │               │
     │     └─────┬─────┘               │
     │           ↓                      │
     │     .task/*.json                 │
     │           ↓                      │
     │     Direct Execution             │
     │           │                      │
     └───────────┴──────────────────────┘
                  ↓ (fallback/remaining)
          issue-resolve (plan/queue)
                  ↓
            /issue:execute

主な設計原則

1. アクション主導のルーティング：request_user_input でアクションを選択してから、単一のフェーズを読み込みます
2. 段階的なフェーズ読み込み：選択したフェーズのドキュメントのみを読み込みます
3. CLI 優先のデータアクセス：Issue のすべての CRUD 操作には ccw issue CLI コマンドを使用します
4. 自動モードのサポート：-y フラグを使うと、アクション選択を省略して自動検出します
5. サブエージェントのライフサイクル：spawn_agent → wait_agent → close_agent でライフサイクルを明示的に管理します
6. ロールパスの読み込み：サブエージェントのロールは、MANDATORY FIRST STEPS のパス参照を通じて読み込みます

自動モード

--yes または -y の場合：アクション選択を省略し、入力タイプからアクションを自動検出します。

使用方法

issue-discover <input>
issue-discover [FLAGS] "<input>"

# Flags
-y, --yes              Skip all confirmations (auto mode)
--action <type>        Pre-select action: new|discover|discover-by-prompt

# Phase-specific flags
--priority <1-5>       Issue priority (new mode)
--perspectives <list>  Comma-separated perspectives (discover mode)
--external             Enable Exa research (discover mode)
--scope <pattern>      File scope (discover/discover-by-prompt mode)
--depth <level>        standard|deep (discover-by-prompt mode)
--max-iterations <n>   Max exploration iterations (discover-by-prompt mode)

# Examples
issue-discover https://github.com/org/repo/issues/42                              # Create from GitHub
issue-discover "Login fails with special chars"                                    # Create from text
issue-discover --action discover src/auth/**                                       # Multi-perspective discovery
issue-discover --action discover src/api/** --perspectives=security,bug            # Focused discovery
issue-discover --action discover-by-prompt "Check API contracts"                   # Prompt-driven discovery
issue-discover -y "auth broken"                                                    # Auto mode create

実行フロー

Input Parsing:
   └─ Parse flags (--action, -y, --perspectives, etc.) and positional args

Action Selection:
   ├─ --action flag provided → Route directly
   ├─ Auto-detect from input:
   │   ├─ GitHub URL or #number → Create New (Phase 1)
   │   ├─ Path pattern (src/**, *.ts) → Discover (Phase 2)
   │   ├─ Short text (< 80 chars) → Create New (Phase 1)
   │   └─ Long descriptive text (≥ 80 chars) → Discover by Prompt (Phase 3)
   └─ Otherwise → request_user_input to select action
   └─ Initialize progress tracking: functions.update_plan([...phases])

Phase Execution (load one phase):
   ├─ Phase 1: Create New          → phases/01-issue-new.md
   ├─ Phase 2: Discover            → phases/02-discover.md
   └─ Phase 3: Discover by Prompt  → phases/03-discover-by-prompt.md

Post-Phase:
   └─ Summary + Next steps recommendation

フェーズ参照ドキュメント

フェーズ	ドキュメント	読み込み条件	目的
Phase 1	phases/01-issue-new.md	アクション = 新規作成	GitHub URL またはテキストの説明から Issue を作成します
Phase 2	phases/02-discover.md	アクション = 検出	複数の視点から Issue を検出します（バグ、セキュリティ、テストなど）
Phase 3	phases/03-discover-by-prompt.md	アクション = プロンプトによる検出	Gemini による計画を用いて、プロンプト主導で反復的に探索します
Phase 4	phases/04-quick-execute.md	フェーズ後 = クイック計画と実行	信頼度の高い検出結果をタスクに変換し、直接実行します

コアのルール

1. 最初にアクションを選択：フェーズを読み込む前に、必ずアクションを決定します
2. フェーズは 1 つだけ読み込み：選択したフェーズのドキュメントのみを読み込み、すべてのフェーズを読み込んではいけません
3. CLI によるデータアクセス：Issue に関するすべての操作には ccw issue CLI を使用し、ファイルを直接読み込んではいけません
4. コンテンツの保持：各フェーズには、元のコマンドから引き継いだ実行ロジックがすべて含まれています
5. 入力の自動検出：入力をスマートに解析することで、明示的な --action フラグの必要性を減らします
6. ⚠️ 重要：停止しないこと：複数のフェーズにまたがるワークフローは継続します。各フェーズの完了後、直ちに次へ進みます
7. 段階的なフェーズ読み込み：フェーズの実行直前にのみ、そのフェーズのドキュメントを読み込みます
8. 明示的なライフサイクル管理：wait_agent の完了後は、リソースを解放するため、必ず close_agent を呼び出します

入力処理

自動検出ロジック

function detectAction(input, flags) {
  // 1. Explicit --action flag
  if (flags.action) return flags.action;

  const trimmed = input.trim();

  // 2. GitHub URL → new
  if (trimmed.match(/github\.com\/[\w-]+\/[\w-]+\/issues\/\d+/) || trimmed.match(/^#\d+$/)) {
    return 'new';
  }

  // 3. Path pattern (contains **, /, or --perspectives) → discover
  if (trimmed.match(/\*\*/) || trimmed.match(/^src\//) || flags.perspectives) {
    return 'discover';
  }

  // 4. Short text (< 80 chars, no special patterns) → new
  if (trimmed.length > 0 && trimmed.length < 80 && !trimmed.includes('--')) {
    return 'new';
  }

  // 5. Long descriptive text → discover-by-prompt
  if (trimmed.length >= 80) {
    return 'discover-by-prompt';
  }

  // Cannot auto-detect → ask user
  return null;
}

アクションの選択（request_user_input）

// When action cannot be auto-detected
const answer = functions.request_user_input({
  questions: [{
    header: "Action",
    id: "action",
    question: "What would you like to do?",
    options: [
      {
        label: "Create New Issue (Recommended)",
        description: "Create issue from GitHub URL, text description, or structured input"
      },
      {
        label: "Discover Issues",
        description: "Multi-perspective discovery: bug, security, test, quality, performance, etc."
      },
      {
        label: "Discover by Prompt",
        description: "Describe what to find — Gemini plans the exploration strategy iteratively"
      }
    ]
  }]
});  // BLOCKS (wait for user response)

// Route based on selection
// answer.answers.action.answers[0] → selected label
const actionMap = {
  "Create New Issue (Recommended)": "new",
  "Discover Issues": "discover",
  "Discover by Prompt": "discover-by-prompt"
};

// Initialize progress tracking (MANDATORY)
functions.update_plan([
  { id: "action-select", title: "Action Selection", status: "completed" },
  { id: "phase-exec", title: `Phase: ${selectedAction}`, status: "in_progress" },
  { id: "post-phase", title: "Post-Phase: Next Steps", status: "pending" }
])

データフロー

User Input (URL / text / path pattern / descriptive prompt)
    ↓
[Parse Flags + Auto-Detect Action]
    ↓
[Action Selection] ← request_user_input (if needed)
    ↓
[Read Selected Phase Document]
    ↓
[Execute Phase Logic]
    ↓
[Summary + Next Steps]
    ├─ After Create → Suggest issue-resolve (plan solution)
    └─ After Discover → Suggest export to issues, then issue-resolve

サブエージェント API リファレンス

spawn_agent

タスクを割り当てて、新しいサブエージェントを作成します。

const agentId = spawn_agent({
  agent_type: "{agent_type}",
  message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. Execute: ccw spec load --category exploration
2. Execute: ccw spec load --category debug (known issues cross-reference)

## TASK CONTEXT
${taskContext}

## DELIVERABLES
${deliverables}
`
})

wait_agent

サブエージェントの結果を取得します（結果を取得する唯一の方法です）。

const result = wait_agent({
  timeout_ms: 1800000  // 30 minutes
})

if (result.timed_out) {
  // Handle timeout via 4-step cascade: status probe → force finalize → close
}

// Check completion status
if (result.status[agentId].completed) {
  const output = result.status[agentId].completed;
}

followup_task

アクティブなサブエージェントに新しい作業を割り当てます（確認またはフォローアップ用）。

followup_task({
  target: agentId,
  message: `
## CLARIFICATION ANSWERS
${answers}

## NEXT STEP
Continue with plan generation.
`
})

close_agent

サブエージェントのリソースをクリーンアップします（取り消し不可）。

close_agent({ target: agentId })

基本ガイドライン

データアクセスの原則：Issue ファイルは非常に大きくなることがあります。コンテキストのオーバーフローを避けるには、次のとおりにします。

操作	正しい方法	誤った方法
Issue の一覧表示（簡易）	ccw issue list --status pending --brief	Read('issues.jsonl')
Issue の詳細を読む	ccw issue status <id> --json	Read('issues.jsonl')
Issue の作成	echo '...' | ccw issue create	ファイルへの直接書き込み
ステータスの更新	ccw issue update <id> --status ...	ファイルの直接編集

CRUD 操作には必ず CLI コマンドを使用してください。issues.jsonl 全体を直接読み込んではいけません。

エラー処理

エラー	解決方法
アクションが検出されない	3 つすべての選択肢を含む request_user_input を表示します
無効なアクションタイプ	使用可能なアクションを表示し、再度入力を求めます
フェーズの実行に失敗	エラーを報告し、手動での対応を提案します
該当するファイルがない（検出）	対象パターンを確認し、パスの存在を検証します
Gemini による計画に失敗（プロンプトによる検出）	qwen にフォールバックして再試行します
エージェントのライフサイクルエラー	リソースリークを防ぐため、エラー処理でも close_agent が実行されることを確認します

フェーズ実行後の次のステップ

進捗：functions.update_plan([{id: "phase-exec", status: "completed"}, {id: "post-phase", status: "in_progress"}])

フェーズの実行が成功した後、次のアクションを推奨します。

// After Create New (issue created)
functions.request_user_input({
  questions: [{
    header: "Next Step",
    id: "next_after_create",
    question: "Issue created. What next?",
    options: [
      { label: "Plan Solution (Recommended)", description: "Generate solution via issue-resolve" },
      { label: "Create Another", description: "Create more issues" },
      { label: "Done", description: "Exit workflow" }
    ]
  }]
});  // BLOCKS (wait for user response)
// answer.answers.next_after_create.answers[0] → selected label

// After Discover / Discover by Prompt (discoveries generated)
functions.request_user_input({
  questions: [{
    header: "Next Step",
    id: "next_after_discover",
    question: `Discovery complete: ${findings.length} findings, ${executableFindings.length} executable. What next?`,
    options: [
      { label: "Quick Plan & Execute (Recommended)", description: `Fix ${executableFindings.length} high-confidence findings directly` },
      { label: "Export to Issues", description: "Convert discoveries to issues" },
      { label: "Done", description: "Exit workflow" }
    ]
  }]
});  // BLOCKS (wait for user response)
// answer.answers.next_after_discover.answers[0] → selected label
// If "Quick Plan & Execute (Recommended)" → Read phases/04-quick-execute.md, execute

// Mark workflow complete
functions.update_plan([{ id: "post-phase", status: "completed" }])

関連するスキルとコマンド

• issue-resolve - ソリューションを計画し、成果物を変換し、ブレインストーミングからキューを作成します
• issue-manage - 対話形式でイシューの CRUD 操作を行います
• /issue:execute - DAG ベースの並列オーケストレーションでキューを実行します
• ccw issue list - すべてのイシューを一覧表示します
• ccw issue status <id> - イシューの詳細を表示します