issue-analyze

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Issue Analyze

Issue 分析

Fetches a GitHub issue, analyzes its full scope, cross-references local project docs, checks blocking relationships, and outputs a structured analysis with an implementation task list. Standalone — no forced next step.

获取GitHub Issue，分析其完整范围，交叉参考本地项目文档，检查阻塞关系，并输出带有实现任务清单的结构化分析报告。独立运行——无强制后续步骤。

Phase 1: Resolve & Fetch

阶段1：解析与获取

Guard: no argument

防护检查：无参数

$ARGUMENTS

is empty, stop:

Provide an issue number or URL. Usage: /issue-analyze 42

如果

$ARGUMENTS

为空，则终止运行：

请提供Issue编号或URL。用法：/issue-analyze 42

Detect repo

检测仓库

bash

gh repo view --json nameWithOwner --jq '.nameWithOwner'

Outputs

owner/repo

. Split on

to get owner and repo name separately.

bash

gh repo view --json nameWithOwner --jq '.nameWithOwner'

输出格式为

owner/repo

。按

分割以分别获取所有者和仓库名称。

Parse argument

解析参数

$ARGUMENTS

is either:

A bare number:
```
42
```
A full URL:
```
https://github.com/owner/repo/issues/42
```

For a URL, extract the number from the last path segment. If the URL contains a different owner/repo than the current repo, use the URL's owner/repo for all API calls.

$ARGUMENTS

可以是以下两种形式之一：

纯数字：
```
42
```
完整URL：
```
https://github.com/owner/repo/issues/42
```

对于URL，从最后一个路径段中提取编号。如果URL中包含的所有者/仓库与当前仓库不同，则使用URL中的所有者/仓库进行所有API调用。

Fetch the issue

获取Issue

bash

gh issue view <N> --repo <owner>/<repo> --json number,title,body,state,labels,assignees,url

bash

gh issue view <N> --repo <owner>/<repo> --json number,title,body,state,labels,assignees,url

Detect current user

检测当前用户

bash

gh api user --jq .login

bash

gh api user --jq .login

Guard: closed issue

防护检查：已关闭的Issue

state

"closed"

Issue #<N> is closed — no implementation plan needed.

<url>

Stop. Do not output anything else.

如果

state

为

"closed"

：

Issue #<N>已关闭——无需生成实现计划。

<url>

终止运行，不输出其他内容。

Guard: not assigned to you

防护检查：未分配给当前用户

assignees

is non-empty and none match the current user login, print this line before all other output:

> Note: #<N> is assigned to @<other-user> — you may be looking at someone else's work.

Then continue normally.

如果

assignees

非空且没有匹配当前用户登录名的对象，则在所有其他输出之前打印以下内容：

> 注意：#<N>已分配给@<other-user>——你查看的可能是他人的工作内容。

之后正常继续运行。

Fetch sub-issues

获取子Issue

bash

gh api repos/<owner>/<repo>/issues/<N>/sub_issues 2>/dev/null

Empty array
```
[]
```
→ no sub-issues, skip
HTTP 404 → sub-issues feature not enabled on this repo, skip silently
Non-empty array → for each sub-issue number, fetch:

bash

gh issue view <sub-N> --repo <owner>/<repo> --json number,title,body,state

Collect all sub-issue data. Closed sub-issues are noted in the analysis as already done but do not generate implementation tasks.

bash

gh api repos/<owner>/<repo>/issues/<N>/sub_issues 2>/dev/null

空数组
```
[]
```
→ 无子Issue，跳过
HTTP 404 → 此仓库未启用子Issue功能，静默跳过
非空数组 → 对每个子Issue编号，执行以下命令获取信息：

bash

gh issue view <sub-N> --repo <owner>/<repo> --json number,title,body,state

收集所有子Issue数据。已关闭的子Issue会在分析中标记为已完成，但不会生成实现任务。

Phase 2: Local Context Search

阶段2：本地上下文搜索

Find the git root:

bash

git rev-parse --show-toplevel

Check whether any of these local context sources exist. If none do, skip this phase entirely — do not mention it in output.

```
<git-root>/AGENTS.md
```
```
<git-root>/CLAUDE.md
```
```
<git-root>/.claude/
```
```
<git-root>/.agents/
```

查找Git根目录：

bash

git rev-parse --show-toplevel

检查是否存在以下本地上下文源。如果均不存在，则完全跳过此阶段——输出中不提及该阶段。

```
<git-root>/AGENTS.md
```
```
<git-root>/CLAUDE.md
```
```
<git-root>/.claude/
```
```
<git-root>/.agents/
```

Find doc files

查找文档文件

Use

Glob

tool to find:

```
<git-root>/AGENTS.md
```
```
<git-root>/CLAUDE.md
```
```
<git-root>/.claude/*.md
```
```
<git-root>/.claude/docs/*.md
```
```
<git-root>/.agents/*.md
```
```
<git-root>/.agents/docs/*.md
```
```
<git-root>/docs/superpowers/**/*.md
```

If no files found, skip phase.

使用

Glob

工具查找以下文件：

```
<git-root>/AGENTS.md
```
```
<git-root>/CLAUDE.md
```
```
<git-root>/.claude/*.md
```
```
<git-root>/.claude/docs/*.md
```
```
<git-root>/.agents/*.md
```
```
<git-root>/.agents/docs/*.md
```
```
<git-root>/docs/superpowers/**/*.md
```

如果未找到文件，则跳过此阶段。

Search for issue number

搜索Issue编号

Use

Grep

to search all found files for:

```
#<N>
```
(e.g.
```
#42
```
)
Word-boundary match for bare number (to avoid matching
```
142
```
when looking for
```
42
```
)

使用

Grep

在所有找到的文件中搜索：

```
#<N>
```
（例如
```
#42
```
）
匹配独立数字（避免在查找
```
42
```
时匹配到
```
142
```
）

Extract and search key terms

提取并搜索关键术语

From the issue title and body, extract:

Capitalized component/module names (e.g.
```
TreeView
```
,
```
AuthService
```
)
camelCase or PascalCase identifiers
File paths mentioned (e.g.
```
src/components/Button.tsx
```
)
Technical terms: API endpoint names, config keys, function names in backticks

Use

Grep

to search all found files for each extracted term. Collect unique (file path, matching line) pairs. Deduplicate across term searches.

从Issue标题和正文中提取：

大写的组件/模块名称（例如
```
TreeView
```
、
```
AuthService
```
）
camelCase或PascalCase标识符
提到的文件路径（例如
```
src/components/Button.tsx
```
）
技术术语：API端点名称、配置键、反引号中的函数名称

使用

Grep

在所有找到的文件中搜索每个提取的术语。收集唯一的（文件路径，匹配行）对。在多次术语搜索中去重。

Result

结果

If nothing found across all searches → omit the Local Context section from output. If matches found → collect as:

{ file: string, reason: string }[]

for use in Phase 4.

如果所有搜索均未找到内容 → 输出中省略本地上下文部分。如果找到匹配项 → 整理为

{ file: string, reason: string }[]

格式，供阶段4使用。

Phase 3: Dependency Analysis

阶段3：依赖分析

Query issue relationships via GraphQL. Fetch the issue's tracking relationships:

bash

gh api graphql -f query='{
  repository(owner: "<owner>", name: "<repo>") {
    issue(number: <N>) {
      trackedInIssues(first: 5) {
        nodes { number title state url }
      }
    }
  }
}'

trackedInIssues

— parent issues or epics that track this issue. If this issue is part of a larger epic, these are the parents.

Also try blocked-by relationships. GitHub stores these via node-ID-based relationships (same mechanism as

addBlockedBy

removeBlockedBy

mutations). Query them directly as a separate call so a failure here does not affect the

trackedInIssues

result:

bash

gh api graphql -f query='{
  repository(owner: "<owner>", name: "<repo>") {
    issue(number: <N>) {
      blockedByIssues(first: 10) {
        nodes { number title state url }
      }
      blockingIssues(first: 10) {
        nodes { number title state url }
      }
    }
  }
}' 2>&1 || true

blockedByIssues

— what is blocking this issue (must be resolved first).

blockingIssues

— what this issue blocks (expects deliverables from this one).

These fields are part of GitHub's issue dependencies preview and are not available on most repos or plans. When unavailable,

gh api

exits with code 1 and prints an

undefinedField

GraphQL error on stdout (not stderr). Handle this silently:

The
```
|| true
```
above prevents the non-zero exit from surfacing as a tool error.
If the response contains an
```
errors
```
field, or any
```
undefinedField
```
/
```
Field '...' doesn't exist
```
message, treat it as "not available" and skip this section.

Only parse

data.repository.issue.blockedByIssues

blockingIssues

when the response has no

errors

field.

If all queries fail or return no data, skip silently.

通过GraphQL查询Issue关系。获取Issue的跟踪关系：

bash

gh api graphql -f query='{
  repository(owner: "<owner>", name: "<repo>") {
    issue(number: <N>) {
      trackedInIssues(first: 5) {
        nodes { number title state url }
      }
    }
  }
}'

trackedInIssues

—— 跟踪此Issue的父Issue或史诗（Epic）。如果此Issue属于更大的史诗，这些就是父级。

同时尝试查询被阻塞关系。GitHub通过基于节点ID的关系存储这些信息（与

addBlockedBy

removeBlockedBy

突变使用相同机制）。作为单独调用查询这些关系，这样此处的失败不会影响

trackedInIssues

的结果：

bash

gh api graphql -f query='{
  repository(owner: "<owner>", name: "<repo>") {
    issue(number: <N>) {
      blockedByIssues(first: 10) {
        nodes { number title state url }
      }
      blockingIssues(first: 10) {
        nodes { number title state url }
      }
    }
  }
}' 2>&1 || true

blockedByIssues

—— 阻塞此Issue的内容（必须先解决）。

blockingIssues

—— 此Issue阻塞的内容（依赖此Issue的交付成果）。

这些字段属于GitHub Issue依赖关系预览功能，并非在大多数仓库或计划中可用。当不可用时，

gh api

会以代码1退出，并在标准输出（而非标准错误）上打印

undefinedField

GraphQL错误。静默处理此情况：

上述命令中的
```
|| true
```
可防止非零退出码被视为工具错误。
如果响应包含
```
errors
```
字段，或任何
```
undefinedField
```
/
```
Field '...' doesn't exist
```
消息，则视为“不可用”并跳过此部分。

仅当响应无

errors

字段时，才解析

data.repository.issue.blockedByIssues

blockingIssues

。

如果所有查询失败或返回空数据，则静默跳过。

Relevance filter

Phase 4: Synthesize & Output

阶段4：合成与输出

Scope Analysis — quality bar

范围分析——质量标准

This is the highest-value section. Write it to be directly useful for implementation planning — not a summary of the issue text, but an interpretation of it.

A high-quality Scope Analysis:

Explains what the issue is truly asking for (beyond restating the title)
Identifies technical scope: what needs to be built or changed, and roughly where
For epics: weaves sub-issues into a coherent narrative. Example: "This epic covers three areas: authentication (#43, done), session management (#44), and token refresh (#45)." Closed sub-issues are noted as already implemented and excluded from tasks.
Surfaces implicit requirements not stated in the issue (e.g., "adding X implies Y also needs to handle the new input format")
Calls out ambiguities or decisions the implementer will face
States what is explicitly out of scope
When a blocker is open: explains what cannot be built until it's resolved, and what can be built in parallel

Length: 2–5 paragraphs for a normal issue; more for a large epic (one paragraph per sub-issue area).

这是价值最高的部分。撰写内容时需直接服务于实现规划——不是Issue文本的摘要，而是对其的解读。

高质量的范围分析应：

解释Issue真正的需求（不仅仅是重述标题）
明确技术范围：需要构建或更改什么，大致在何处
对于史诗：将子Issue整合为连贯的叙述。示例：“此史诗涵盖三个领域：身份验证（#43，已完成）、会话管理（#44）和令牌刷新（#45）。”已关闭的子Issue会标记为已实现，不纳入任务。
揭示Issue中未明确说明的隐含需求（例如：“添加X意味着Y也需要处理新的输入格式”）
指出实现者将面临的模糊点或需要做出的决策
明确说明哪些内容不在范围内
当存在未解决的阻塞项时：解释在其解决前无法构建的内容，以及可并行构建的内容

篇幅：普通Issue为2-5段；大型史诗可更长（每个子Issue领域一段）。

Implementation Tasks — quality bar

实现任务——质量标准

Each task is a concrete, actionable step (not "investigate X" — investigation is part of Scope Analysis)
Ordered logically: setup before implementation, implementation before tests, tests before integration
3–12 tasks (3–4 is fine for small/trivial issues; 5–12 for normal scope)
For epics: group tasks under sub-issue headings
If a blocker is open: mark affected tasks as "blocked by #N" and list them last

每个任务都是具体、可执行的步骤（而非“调研X”——调研属于范围分析的部分）
逻辑排序：先准备，再实现，然后测试，最后集成
3-12个任务（小型/简单Issue 3-4个即可；普通范围的Issue 5-12个）
对于史诗：将任务分组到子Issue标题下
如果存在未解决的阻塞项：将受影响的任务标记为“被#N阻塞”并放在最后

Output format

输出格式

Print output in this exact structure:

> Note: #<N> is assigned to @<user> — you may be looking at someone else's work.
(omit line if current user is among assignees, or if issue has no assignees)

严格按照以下结构打印输出：

> 注意：#<N>已分配给@<user>——你查看的可能是他人的工作内容。
（如果当前用户是经办人之一，或Issue无经办人，则省略此行）

#<N>: <title>

Scope Analysis

范围分析

<分析段落>

Local Context

本地上下文

(omit entire section if Phase 2 found nothing)

```
.claude/docs/foo.md
```
— <one sentence on why it's relevant to this issue>

（如果阶段2未找到任何内容，则省略整个部分）

```
.claude/docs/foo.md
```
—— <一句话说明其与本Issue的相关性>

Dependencies

依赖关系

(omit entire section if no implementation-relevant open dependencies)

Depends on #<M> (open) — <what that issue provides that this one needs>. This issue's output expected by #<K> — must deliver <Y>.

（如果没有与实现相关的未解决依赖项，则省略整个部分）

依赖#<M>（未关闭）—— <该Issue提供的本Issue所需内容>。本Issue的输出是#<K>所需的——必须交付<Y>。

Implementation Tasks

实现任务

<task>
<task>
<task>

<issue URL> ````

<任务>
<任务>
<任务>

<issue URL> ````

Error Handling

错误处理

Situation	Action
`$ARGUMENTS` is empty	Stop: "Provide an issue number or URL. Usage: /issue-analyze 42"
`gh` not authenticated	Stop: "Run `gh auth login` first."
Not in a git repo + no URL given	Stop: "Provide a full GitHub URL or run from inside a git repository."
Issue number not found ( `gh` 404)	Stop: "Issue #<N> not found in <owner>/<repo>."
Sub-issues API returns 404	Skip silently
No `.claude/` directory	Skip local context phase silently
GraphQL returns error or empty data	Skip dependencies section silently
Issue body is empty	Analyze from title only; note in Scope Analysis that the issue has no description

场景	操作
`$ARGUMENTS` 为空	终止：“请提供Issue编号或URL。用法：/issue-analyze 42”
`gh` 未认证	终止：“先运行 `gh auth login` 。”
不在Git仓库中且未提供URL	终止：“请提供完整的GitHub URL或在Git仓库内运行。”
Issue编号不存在（ `gh` 返回404）	终止：“<owner>/<repo>中未找到Issue #<N>。”
子Issue API返回404	静默跳过
无 `.claude/` 目录	静默跳过本地上下文阶段
GraphQL返回错误或空数据	静默跳过依赖关系部分
Issue正文为空	仅根据标题分析；在范围分析中注明Issue无描述

issue-analyze

Original

Translation

Issue Analyze

Issue 分析

Phase 1: Resolve & Fetch

阶段1：解析与获取

Guard: no argument

防护检查：无参数

Detect repo

检测仓库

Parse argument

解析参数

Fetch the issue

获取Issue

Detect current user

检测当前用户

Guard: closed issue

防护检查：已关闭的Issue

Guard: not assigned to you

防护检查：未分配给当前用户

Fetch sub-issues

获取子Issue

Phase 2: Local Context Search

阶段2：本地上下文搜索

Find doc files

查找文档文件

Search for issue number

搜索Issue编号

Extract and search key terms

提取并搜索关键术语

Result

结果

Phase 3: Dependency Analysis

阶段3：依赖分析

Relevance filter

相关性过滤

Phase 4: Synthesize & Output

阶段4：合成与输出

Scope Analysis — quality bar

范围分析——质量标准

Implementation Tasks — quality bar

实现任务——质量标准

Output format

输出格式

#<N>: <title>

#<N>: <title>

Scope Analysis

范围分析

Local Context

本地上下文

Dependencies

依赖关系

Implementation Tasks

实现任务

Error Handling

错误处理