Use the complete superpowers workflow to fix GitHub issues, including requirements understanding, test-driven development, verification, and code review.
⚠️ Important requirement: all responses must be in Chinese! Must be in Chinese! Must be in Chinese!
No matter what I ask, no matter what language the code is in, all your replies, explanations, descriptions, and comments must be in Chinese. This is a mandatory requirement, with no exceptions.
Work Modes
Normal Mode
Execute step by step, with user confirmation required at each key decision point.
Automation Mode
When the user input contains "automated processing":
- Fully automated execution, no user confirmation required
- Use the issue from upstream (the original repository) by default
- No restriction on issue type (bug/enhancement/feature, etc.)
- Choose simple or medium difficulty
- Automatically complete all steps until the code modification is finished
Mandatory Workflow
You must execute the following steps in order, and you cannot skip any step:
Step 1: Sync the latest upstream code
First, make sure the local code is up to date:
# 查看当前 remote 配置
git remote -v
# 同步 upstream 最新代码到当前分支
git fetch upstream
git rebase upstream/main
# 或者使用 superpowers:git-sync-upstream skill
Step 2: Understand the user's preferred mode
Key questions must be confirmed (automation mode uses default values):
| Question | Normal Mode | Automation Mode Default Value |
|---|---|---|
| Which remote repository's issue should be used? | Ask the user | upstream (the original repository) |
| Issue type preference? | Bug/New feature/Improvement/Any | Any |
| Difficulty preference? | Simple/Medium/Complex | Simple or Medium |
Step 3: Find a suitable Issue
3.1 Query processed issues (deduplication check)
Before looking for a new issue, you must check which issues have already been processed:
# 查看本地分支
git branch -a | grep "myfix/issue-"
# 查看 origin 远程分支（已推送的处理记录）
git ls-remote --heads origin | grep "myfix/issue-"
Branch naming rule for processed issues:
- Branch name:
myfix/issue-{issueId}-简短英文描述 - For example:
myfix/issue-48928-poll-params-zero-check
If an issue already has a corresponding branch, skip that issue and do not fix it again.
3.2 Get the list of open issues
Based on the remote repository selected by the user (upstream by default):
# 使用 GitHub CLI 获取 issue 列表
gh issue list --repo <owner>/<repo> --state open --limit 30
# 或使用 curl
curl -sL "https://api.github.com/repos/<owner>/<repo>/issues?state=open&per_page=30"
3.3 Review candidate issues in detail
For each candidate issue,you must use the gh command to view the details page：
# 查看 issue 详情
gh issue view <issue-number> --repo <owner>/<repo>
# 查看 issue 评论和讨论
gh issue view <issue-number> --repo <owner>/<repo> --comments
Review points:
- Read the complete issue description
- View comments and feedback from maintainers
- Exclusion conditions:
- Maintainers consider the issue ambiguous or problematic
- Maintainers marked it as "wontfix" or "invalid"
- The issue has already been assigned to someone else
- The issue needs more information but none was added
- The issue already has a PR being worked on
Selection criteria:
- Prioritize issues with clear descriptions and a moderate scope
- Prioritize issues confirmed by maintainers
- Moderate difficulty (simple or medium)
Step 4: Create a worktree and branch and ensure you are already in the worktree
After finding a suitable issue, use the superpowers:using-git-worktrees skill to create an isolated working environment:
# 调用 skill 创建 worktree
# worktree 名称: myfix-issue-{issueId}-简短英文描述
# 分支名称: myfix/issue-{issueId}-简短英文描述
Ensure you are currently working in the worktree. If you are not in the worktree, switch to the worktree before proceeding to the next step.
Naming example:
- Issue #295: Remove hardcoded port 18080
- Worktree:
myfix-issue-295-remove-hardcoded-port - Branch:
myfix/issue-295-remove-hardcoded-port
Step 5: Create a Task document in the worktree and push it
Create a task document in the project root directory:
# 创建 tasks 目录
mkdir -p tasks
# 创建 task 文件
# 文件名: tasks/myfix-issue-{issueId}-简短英文描述.md
Task document template:
# Fix Issue #{issueId}: {issue标题}
## Issue 概述
- **Issue 编号**: #{issueId}
- **Issue 类型**: bug/enhancement/feature
- **仓库**: owner/repo
- **状态**: In Progress
## 问题描述
{issue 的详细描述}
## 相关链接
- Issue URL: https://github.com/owner/repo/issues/{issueId}
## 实现计划
- [ ] 理解需求
- [ ] 编写测试
- [ ] 实现修复
- [ ] 验证通过
- [ ] 代码审查
## 进度记录
- {日期}: 开始处理
Push to origin immediately:
git add tasks/myfix-issue-{issueId}-*.md
git commit -m "docs: add task for issue #{issueId}"
git push -u origin myfix/issue-{issueId}-简短英文描述
This way others can immediately know that the issue is being handled.
Step 6: brainstorming - Deeply understand the Issue
Use the Skill tool to invoke the superpowers:brainstorming skill to deeply understand the issue requirements. When invoking this skill, ensure fully automated execution throughout, with no user confirmation required. After completion, update the plan content in the task, stating whether the skill was used and what the result was.
Content that must be explored:
- View the complete description on the issue detail page
- View feedback and discussion from relevant users
- Understand the root cause of the issue
- Determine the scope and boundaries of the fix
- Assess whether there are other dependencies or impacts
Step 7: test-driven-development - Write tests
Before writing any implementation code, you must first write tests! Ensure fully automated execution throughout, with no user confirmation required. After completion, update the plan content in the task, stating whether the skill was used and what the result was.
- Explore the project test structure:
# 查找测试文件和目录
ls -la tests/ test/ __tests__/ spec/
find . -name "*test*" -o -name "*_test*" -o -name "*.spec.*" | head -20
# 查看项目使用的测试框架
cat package.json | grep -A5 "test"
cat pyproject.toml | grep -A5 "pytest"
- Install dependencies and ensure tests can run:
# 根据项目类型安装依赖
# Python: pip install -e . pytest
# Node.js: npm install
# Rust: cargo build
# Go: go mod download
-
Write tests for the feature to be fixed:
- Create test files under the project's tests/ directory
- Use the project's existing testing framework and style
- Tests should cover the feature points to be fixed
-
Verify that the tests fail - Run the tests to confirm they can execute (but should fail)
Key principle: tests must be written before implementation!
Step 8: subagent-driven-development - Implement the fix
Use the Skill tool to invoke the superpowers:subagent-driven-development skill to implement the fix. When invoking this skill, ensure fully automated execution throughout, with no user confirmation required. After completion, update the plan content in the task, stating whether the skill was used and what the result was.
Or, depending on the project situation, write the implementation code directly:
- Write minimal implementation code based on the tests
- Ensure the code can pass the previously written tests
- Follow the project's code style and conventions
Step 9: verification-before-completion - Verification
Use the Skill tool to invoke the superpowers:verification-before-completion skill for verification. When invoking this skill, ensure fully automated execution throughout, with no user confirmation required. After completion, update the plan content in the task, stating whether the skill was used and what the result was.
Verification that must be performed:
- Run tests - all must pass:
pytest tests/ -v # Python npm test # Node.js cargo test # Rust go test ./... # Go - If there is a linter, run the linter check
- Check the contents of the modified files
Step 10: requesting-code-review - Code review
Use the Skill tool to invoke superpowers:requesting-code-review skill, when invoking this skill, ensure fully automated execution throughout, without user confirmation, and after completion update the plan content in the task, explaining whether the skill was used and what the completion result was.
Important: note that when the review does not pass, the issue must be fixed again, and then code review must be requested again, until the review passes.
Step 11: Complete, update the plan content in the task and display the results
Update the plan content in the task and display the results:
- Which files were modified
- Test results (evidence required)
- Code change summary
Important: after the task is completed, automatically commit and push the code to origin. Note: do not automatically submit a PR to upstream for me; the user needs to confirm offline before manually submitting the PR.
Flowchart
┌─────────────────────────────────────────────────────────────┐
│ 开始处理 Issue │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 步骤 1: 同步 upstream 最新代码 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 步骤 2: 理解用户偏好模式 │
│ 自动化模式: 使用默认值，无需确认 │
│ 普通模式: 询问用户偏好 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 步骤 3: 查找合适的 Issue │
│ 3.1 查询已处理的 issue（去重检查） │
│ 3.2 获取 open issues 列表 │
│ 3.3 使用 gh issue view 详细审查候选 issue │
│ - 排除有歧义或问题的 issue │
│ - 排除已有 PR 处理的 issue │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 步骤 4: 创建 Worktree 和分支 │
│ Worktree: myfix-issue-{issueId}-简短英文描述 │
│ Branch: myfix/issue-{issueId}-简短英文描述 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 步骤 5: 创建 Task 文档并推送 │
│ 文件: tasks/myfix-issue-{issueId}-简短英文描述.md │
│ 立即 push 到 origin │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 步骤 6: brainstorming - 深入理解 Issue │
│ 查看 issue 详情、用户反馈、讨论 │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 步骤 7-12: 开发、测试、验证、审查 │
│ 使用对应的 superpowers skills │
└─────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 完成并展示结果，并更新task中的计划内容 │
└─────────────────────────────────────────────────────────────┘
Key principles
- Do not skip brainstorming - Must understand user requirements and issue details
- Must perform duplicate check - Avoid repeatedly handling issues that someone has already handled
- Must review issue details - Use gh issue view to view the full discussion
- Tests must precede implementation - TDD principle
- Verification must have evidence - Show test output
- Automatically commit code - Automatically commit and push code to origin
- Use other superpowers skills - Invoke relevant skills as needed
- Fully automated mode with no confirmation throughout - Unless an error or blockage is encountered