address-github-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Retrieve a GitHub issue and coordinate a team to address it.

Usage:

```
/address-github-issue 42
```
— Address issue #42 in the current repo
```
/address-github-issue owner/repo#42
```
— Address issue #42 in a specific repo

/address-github-issue https://github.com/owner/repo/issues/42

— Address issue by URL

Instructions:

Validate the
gh
CLI is available:

Run
```
gh --version
```
to confirm it is installed

If not found, stop and display:

❌ GitHub CLI (`gh`) is not installed.
Install it with: brew install gh
Then authenticate with: gh auth login

Run
```
gh auth status
```
to confirm authentication

If not authenticated, stop and display:

❌ GitHub CLI is not authenticated.
Run: gh auth login

Parse the issue reference from
$ARGUMENTS
:
- If
```
$ARGUMENTS
```
  is empty, use
```
AskUserQuestion
```
  to ask for the issue reference and STOP until provided.
- Accepted formats:
  - A bare number (e.g.,
```
42
```
    ) → use the current repo
  - ```
  owner/repo#42
```
  → explicit repo and number
- A full GitHub URL (e.g.,
```
  https://github.com/owner/repo/issues/42
```
  ) → parse repo and number from it
- For bare numbers, determine the current repo with
```
gh repo view --json nameWithOwner -q .nameWithOwner
```
  . If this fails (not in a GitHub repo), stop:
```
❌ Could not determine the GitHub repository.
Run this skill from inside a GitHub repo, or provide a full issue reference (e.g., owner/repo#42).
```

Fetch the issue:

Run:

bash

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

If the issue is not found or access is denied, stop with the error message from
```
gh
```
.
Parse the JSON output to extract:
- ```
title
```
  ,
```
body
```
  ,
```
labels
```
  ,
```
state
```
  ,
```
url
```
- ```
comments
```
  array (each has
```
author.login
```
  and
```
body
```
  )

Analyze the issue:
- Read the title, body, and all comments thoroughly.
- Identify the issue type:
  - Bug — something is broken; labels like
```
bug
```
    ,
```
defect
```
    ,
```
regression
```
  - Feature — new capability; labels like
```
enhancement
```
    ,
```
feature request
```
  - Chore / Maintenance — tech debt, refactor, CI, docs; labels like
```
chore
```
    ,
```
docs
```
    ,
```
refactor
```
  - Question / Investigation — needs research before coding
- Identify the scope and complexity:
  - Simple (1 developer) — isolated fix or small addition, touches ≤2 files, no API or schema changes
  - Medium (2 developers) — moderate feature or bug with multiple moving parts; may touch frontend and backend separately
  - Complex (3 developers) — large feature, architectural change, cross-cutting concern, or multiple independent workstreams
- Note any ambiguities or missing information that the PM should clarify in requirements.
Determine team composition:
- Always spawn exactly 1 PM.
- Spawn 1, 2, or 3 developers based on the complexity assessment above.
- No designers or testers are spawned by this skill (developers are expected to include tests in their implementation).
Create the team:
- Use
```
TeamCreate
```
  with a short kebab-case name derived from the issue title or number (e.g.,
```
issue-42
```
  ,
```
fix-login-crash
```
  ,
```
add-dark-mode
```
  ).
- Use
```
TaskCreate
```
  to create one task per role before spawning agents:
  - PM task: "Write requirements and acceptance criteria for issue #<number>"
  - One developer task per developer: "Implement <area> for issue #<number>"

Spawn the PM (

subagent_type: general-purpose

Provide:
- The full issue content (title, body, all comments, URL)
- The issue type and complexity assessment
- The team name

The PM's job:

Read the issue thoroughly, including all comments
Write detailed requirements and acceptance criteria to address the issue, resolving any ambiguities using the comments and their knowledge of the codebase

Structure the requirements as:

## Issue #<number>: <title>
**Type:** <Bug / Feature / Chore> | **URL:** <url>

## Context
<Brief summary of the issue and why it matters>

## Requirements
<Numbered list of concrete, testable requirements>

## Acceptance Criteria
<Checklist of conditions that must be true when the issue is resolved>

## Developer Workstreams
<If multiple developers: describe each workstream clearly with its scope and any shared interfaces or contracts they need to agree on>

## Out of Scope
<Anything explicitly excluded from this issue>

Check for a project lore file (
```
LORE.md
```
,
```
docs/lore.md
```
,
```
.agent/lore.md
```
, or similar) and update it with any relevant context this issue introduces
Mark their task as completed via
```
TaskUpdate
```
Message the team lead when done

Wait for the PM to finish and retrieve the requirements from the completed task or PM message.
Spawn developers (
```
subagent_type: general-purpose
```
) in parallel, one per workstream:
- Provide each developer with:
  - The original issue content (title, body, comments, URL)
  - The PM's requirements document
  - Their specific workstream scope (if multiple developers)
  - The issue type for context (bug fix → write a regression test; feature → write unit/integration tests; etc.)
- Each developer's job:
  - Explore the relevant parts of the codebase
  - Implement the changes required by their workstream
  - Write tests covering their changes (unit tests at minimum; integration tests if applicable)
  - Mark their task as completed via
```
TaskUpdate
```
  - Message the team lead when done
Wait for all developers to finish.
Verify no conflicts:
- If multiple developers were spawned, check whether any two agents modified the same files
- If conflicts exist, resolve them by reading both sets of changes and merging intelligently
- Run a quick sanity check: ensure the codebase compiles and lints cleanly after all changes are applied (use the project's existing lint/build scripts if available)

Present a final summary to the user:

## Issue #<number> Addressed

**Issue:** <title>
**URL:** <url>

### What was done
- <Bullet summary of changes made>

### Tests added
- <List of test files added or updated>

### Developers
- <Developer 1>: <what they implemented>
- <Developer 2>: <what they implemented> (if applicable)

### Recommended next steps
- Review the changes with `/review-changes`
- Create a PR with `/create-pr`
- Link the PR to the issue on GitHub: `gh issue develop <number> --repo <owner/repo>`

Shut down the team gracefully:
- Send a
```
shutdown_request
```
  to each teammate via
```
SendMessage
```
- Once all have confirmed, call
```
TeamDelete
```

获取GitHub issue并协调团队进行处理。

用法：

```
/address-github-issue 42
```
— 处理当前仓库的#42号issue
```
/address-github-issue owner/repo#42
```
— 处理指定仓库的#42号issue

/address-github-issue https://github.com/owner/repo/issues/42

— 通过URL处理对应issue

操作说明：

验证
gh
CLI可用：

运行
```
gh --version
```
确认已安装该工具

如果未找到，终止流程并展示：

❌ GitHub CLI (`gh`) 未安装。
可通过以下命令安装：brew install gh
安装后执行以下命令完成认证：gh auth login

运行
```
gh auth status
```
确认已完成认证

如果未认证，终止流程并展示：

❌ GitHub CLI 未完成认证。
执行命令：gh auth login

从
$ARGUMENTS
中解析issue引用：
- 如果
```
$ARGUMENTS
```
  为空，调用
```
AskUserQuestion
```
  询问用户issue引用，等待用户提供后再继续
- 支持的格式：
  - 纯数字（例如
```
42
```
    ）→ 自动使用当前仓库
  - ```
  owner/repo#42
```
  → 明确指定仓库和issue编号
- GitHub完整URL（例如
```
  https://github.com/owner/repo/issues/42
```
  ）→ 从中解析仓库和issue编号
- 如果是纯数字格式，通过
```
gh repo view --json nameWithOwner -q .nameWithOwner
```
  获取当前仓库信息。如果运行失败（不在GitHub仓库目录下），终止流程：
```
❌ 无法识别GitHub仓库。
请在GitHub仓库目录下运行该技能，或者提供完整的issue引用（例如owner/repo#42）。
```
拉取issue信息：
- 运行：
  bash
```
gh issue view <number> --repo <owner/repo> --json number,title,body,labels,assignees,milestone,state,comments,url
```
- 如果未找到issue或者无访问权限，终止流程并返回
```
gh
```
  返回的错误信息
- 解析JSON输出，提取以下信息：
  - ```
  title
```
  、
```
  body
```
  、
```
  labels
```
  、
```
  state
```
  、
```
  url
```
- ```
comments
```
    数组（每个评论包含
```
author.login
```
    和
```
body
```
    字段）
分析issue：
- 完整阅读标题、正文和所有评论
- 识别issue类型：
  - Bug — 功能故障；对应标签如
```
bug
```
    、
```
defect
```
    、
```
regression
```
  - Feature — 新增功能；对应标签如
```
enhancement
```
    、
```
feature request
```
  - Chore / Maintenance — 技术债务、重构、CI、文档；对应标签如
```
chore
```
    、
```
docs
```
    、
```
refactor
```
  - Question / Investigation — 编码前需要先进行调研
- 识别范围和复杂度：
  - 简单（1名开发）—— 独立修复或者小功能新增，修改≤2个文件，无API或者schema变更
  - 中等（2名开发）—— 复杂度中等的功能或者bug，涉及多个模块；可能分别涉及前端和后端
  - 复杂（3名开发）—— 大型功能、架构变更、跨模块需求，或者多个独立工作流
- 记录所有需要PM在需求中澄清的歧义或者缺失信息
确定团队组成：
- 固定组建1名PM
- 根据上述复杂度评估，组建1、2或3名开发人员
- 该技能不需要组建设计师或者测试人员（开发人员需要在实现中包含测试）
创建团队：
- 调用
```
TeamCreate
```
  ，团队名使用从issue标题或者编号衍生的短横线分隔命名（例如
```
issue-42
```
  、
```
fix-login-crash
```
  、
```
add-dark-mode
```
  ）
- 启动Agent前调用
```
TaskCreate
```
  为每个角色创建对应任务：
  - PM任务："为#<number>号issue编写需求和验收标准"
  - 每个开发人员对应一个任务："为#<number>号issue实现<对应模块>"

启动PM（

subagent_type: general-purpose

）：

提供以下信息：
- 完整的issue内容（标题、正文、所有评论、URL）
- issue类型和复杂度评估结果
- 团队名称

PM的职责：

完整阅读issue，包括所有评论
编写详细的需求和验收标准来处理该issue，结合评论和自身对代码库的了解解决所有歧义

按照以下结构编写需求：

## Issue #<number>: <title>
**类型:** <Bug / Feature / Chore> | **URL:** <url>

## 背景
<issue的简要概述和重要性说明>

## 需求
<具体可测试的需求编号列表>

## 验收标准
<issue解决后必须满足的检查项清单>

## 开发工作流
<如果有多名开发：清晰描述每个工作流的范围，以及需要达成一致的共享接口或者契约>

## 超出范围
<明确排除在本次issue处理外的所有内容>

查找项目说明文件（
```
LORE.md
```
、
```
docs/lore.md
```
、
```
.agent/lore.md
```
等），将本次issue引入的相关上下文更新到文件中
通过
```
TaskUpdate
```
标记自身任务已完成
完成后通知团队负责人

等待PM完成任务，从已完成的任务或者PM的消息中获取需求文档
并行启动开发人员（
```
subagent_type: general-purpose
```
），每个工作流对应一名开发：
- 为每位开发人员提供以下信息：
  - 原始issue内容（标题、正文、评论、URL）
  - PM输出的需求文档
  - 对应工作流的范围（如果有多名开发）
  - issue类型作为上下文参考（bug修复→编写回归测试；新功能→编写单元/集成测试等）
- 每个开发人员的职责：
  - 探索代码库相关部分
  - 实现所属工作流要求的变更
  - 编写覆盖变更内容的测试（至少包含单元测试；适用场景下需要编写集成测试）
  - 通过
```
TaskUpdate
```
    标记自身任务已完成
  - 完成后通知团队负责人
等待所有开发人员完成任务
验证无冲突：
- 如果启动了多名开发，检查是否有多个Agent修改了同一个文件
- 如果存在冲突，读取两组变更内容并智能合并解决
- 运行快速合理性检查：确保所有变更应用后代码库可以正常编译和通过lint检查（如果项目有现成的lint/构建脚本则调用对应脚本）

向用户呈现最终总结：

## Issue #<number> 处理完成

**Issue:** <title>
**URL:** <url>

### 完成内容
- <变更内容的要点列表>

### 新增测试
- <新增或者更新的测试文件列表>

### 开发人员
- <开发1>: <实现的内容>
- <开发2>: <实现的内容> (如果适用)

### 推荐后续步骤
- 执行`/review-changes` review变更内容
- 执行`/create-pr`创建PR
- 在GitHub上将PR关联到issue：`gh issue develop <number> --repo <owner/repo>`

优雅解散团队：
- 通过
```
SendMessage
```
  向每个团队成员发送
```
shutdown_request
```
- 所有成员确认后，调用
```
TeamDelete
```