piv-implement-issue

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implement Issue Fix: GitHub Issue #$ARGUMENTS

实施Issue修复：GitHub Issue #$ARGUMENTS

Prerequisites

前置条件

This skill implements fixes for GitHub issues based on RCA documents:

Working in a local Git repository with GitHub origin
RCA document exists at
```
docs/issues/issue-$ARGUMENTS.md
```
GitHub CLI installed and authenticated (optional, for status updates)

本技能基于RCA文档修复GitHub Issue：

在带有GitHub远程仓库的本地Git仓库中工作
RCA文档位于
```
docs/issues/issue-$ARGUMENTS.md
```
已安装并认证GitHub CLI（可选，用于状态更新）

RCA Document to Reference

参考RCA文档

Read RCA:

docs/issues/issue-$ARGUMENTS.md

Optional - View GitHub issue for context:

bash

gh issue view $ARGUMENTS

阅读RCA：

docs/issues/issue-$ARGUMENTS.md

可选 - 查看GitHub Issue获取上下文：

bash

gh issue view $ARGUMENTS

Implementation Instructions

实施说明

1. Read and Understand RCA

1. 阅读并理解RCA

Read the ENTIRE RCA document thoroughly
Review the GitHub issue details (issue #$ARGUMENTS)
Understand the root cause
Review the proposed fix strategy
Note all files to modify
Review testing requirements

完整通读整个RCA文档
查看GitHub Issue详情（Issue #$ARGUMENTS）
理解根本原因
查看建议的修复策略
记录所有需要修改的文件
查看测试要求

2. Verify Current State — and check for drift

2. 验证当前状态——检查偏差

Before making changes:

Confirm the issue still exists.
Drift check: read each file the RCA names and compare against the RCA's "current code" snippets / line refs. If the code has changed materially since the RCA, stop — surface the drift and suggest re-running
```
piv-investigate-issue
```
for issue #$ARGUMENTS rather than implementing a stale plan.
Confirm the proposed fix still addresses the root cause — don't silently deviate.

在修改之前：

确认Issue仍然存在。
偏差检查： 读取RCA中提到的每个文件，与RCA里的「当前代码」片段/行号引用进行对比。如果自RCA生成以来代码发生了实质性变化，请停止操作——告知偏差情况，并建议重新运行
```
piv-investigate-issue
```
处理Issue #$ARGUMENTS，而非执行过时的修复计划。
确认建议的修复方案仍能解决根本原因——不要擅自偏离方案。

2b. Get on the right branch

2b. 切换到正确分支

In a worktree? Use it (it was created for this work).
On the base branch, clean tree? Create a fix branch —
```
git checkout -b fix/issue-$ARGUMENTS-<slug>
```
(detect the base with
```
git symbolic-ref refs/remotes/origin/HEAD
```
; never hardcode
```
main
```
).
Already on a feature/fix branch? Use it (warn if its name doesn't reference #$ARGUMENTS).
Dirty tree on the base branch? Stop — ask the user to commit or stash first.

是否在工作树中？ 使用该工作树（它是为此项工作创建的）。
在基础分支且工作区干净？ 创建修复分支——
```
git checkout -b fix/issue-$ARGUMENTS-<slug>
```
（通过
```
git symbolic-ref refs/remotes/origin/HEAD
```
检测基础分支；切勿硬编码
```
main
```
）。
已在功能/修复分支上？ 使用该分支（如果分支名称未引用#$ARGUMENTS则发出警告）。
基础分支工作区有未提交更改？ 停止操作——请用户先提交或暂存更改。

3. Implement the Fix

3. 实施修复

Following the "Proposed Fix" section of the RCA:

For each file to modify:

遵循RCA中的「建议修复」部分：

针对每个需要修改的文件：

a. Read the existing file

a. 读取现有文件

Understand current implementation
Locate the specific code mentioned in RCA

理解当前实现逻辑
定位RCA中提到的具体代码

b. Make the fix

b. 进行修复

Implement the change as described in RCA
Follow the fix strategy exactly
Maintain code style and conventions
Add comments if the fix is non-obvious

按照RCA中的描述实施更改
严格遵循修复策略
保持代码风格与规范一致
如果修复逻辑不明显，添加注释说明

c. Handle related changes

c. 处理相关更改

Update any related code affected by the fix
Ensure consistency across the codebase
Update imports if needed

Stay on plan: implement what the RCA specifies — don't refactor unrelated code or add unplanned "improvements." If you must deviate, note what changed and why, and surface it in the report (and the PR).

更新受修复影响的所有相关代码
确保代码库的一致性
必要时更新导入语句

严格按计划执行： 实施RCA中指定的内容——不要重构无关代码或添加未计划的「改进」。如果必须偏离计划，请记录变更内容及原因，并在报告（和PR）中说明。

4. Add/Update Tests

4. 添加/更新测试

Following the "Testing Requirements" from RCA:

Create test cases for:

Verify the fix resolves the issue
Test edge cases related to the bug
Ensure no regression in related functionality
Test any new code paths introduced

Test file location:

Follow project's test structure
Mirror the source file location
Use descriptive test names

Test implementation:

python

def test_issue_$ARGUMENTS_fix():
    """Test that issue #$ARGUMENTS is fixed."""
    # Arrange - set up the scenario that caused the bug
    # Act - execute the code that previously failed
    # Assert - verify it now works correctly

遵循RCA中的「测试要求」：

创建以下测试用例：

验证修复是否解决了Issue
测试与Bug相关的边缘情况
确保相关功能无回归
测试引入的所有新代码路径

测试文件位置：

遵循项目的测试结构
与源文件位置对应
使用描述性的测试名称

测试实现示例：

python

def test_issue_$ARGUMENTS_fix():
    """Test that issue #$ARGUMENTS is fixed."""
    # Arrange - 设置触发Bug的场景
    # Act - 执行之前失败的代码
    # Assert - 验证现在能正常工作

5. Run Validation

5. 执行验证

Execute validation commands from RCA:

bash

undefined

执行RCA中的验证命令：

bash

undefined

Run linters

运行代码检查工具

[from RCA validation commands]

[来自RCA的验证命令]

Run type checking

运行类型检查

[from RCA validation commands]

[来自RCA的验证命令]

Run tests

运行测试

[from RCA validation commands]


**If validation fails:**
- Fix the issues
- Re-run validation
- Don't proceed until all pass

[来自RCA的验证命令]


**如果验证失败：**
- 修复问题
- 重新执行验证
- 所有验证通过前不要继续

6. Verify Fix

6. 验证修复效果

Manually verify:

Follow reproduction steps from RCA
Confirm issue no longer occurs
Test edge cases
Check for unintended side effects

手动验证：

遵循RCA中的复现步骤
确认Issue不再出现
测试边缘情况
检查是否有意外副作用

7. Update Documentation

7. 更新文档

If needed:

Update code comments
Update API documentation
Update README if user-facing
Add notes about the fix

如有需要：

更新代码注释
更新API文档
如果涉及用户交互，更新README
添加关于修复的说明

Output Report

输出报告

Fix Implementation Summary

修复实施摘要

GitHub Issue #$ARGUMENTS: [Brief title]

Issue URL: [GitHub issue URL]

Root Cause (from RCA): [One-line summary of root cause]

GitHub Issue #$ARGUMENTS: [简短标题]

Issue链接: [GitHub Issue URL]

根本原因（来自RCA）: [根本原因的单行摘要]

Changes Made

已做更改

Files Modified:

[file-path]
- Change: [What was changed]
- Lines: [Line numbers]
[file-path]
- Change: [What was changed]
- Lines: [Line numbers]

修改的文件:

[文件路径]
- 更改内容: [具体修改了什么]
- 行号: [修改的行号]
[文件路径]
- 更改内容: [具体修改了什么]
- 行号: [修改的行号]

Tests Added

添加的测试

Test Files Created/Modified:

[test-file-path]
- Test cases: [List test functions added]

Test Coverage:

✅ Fix verification test
✅ Edge case tests
✅ Regression prevention tests

创建/修改的测试文件:

[测试文件路径]
- 测试用例: [添加的测试函数列表]

测试覆盖:

✅ 修复验证测试
✅ 边缘情况测试
✅ 回归预防测试

Validation Results

验证结果

bash

undefined

bash

undefined

Linter output

代码检查工具输出

[Show lint results]

[显示代码检查结果]

Type check output

类型检查输出

[Show type check results]

[显示类型检查结果]

Test output

测试输出

[Show test results - all passing]

undefined

[显示测试结果 - 全部通过]

undefined

Verification

效果验证

Manual Testing:

✅ Followed reproduction steps - issue resolved
✅ Tested edge cases - all pass
✅ No new issues introduced
✅ Original functionality preserved

手动测试:

✅ 执行复现步骤 - Issue已解决
✅ 测试边缘情况 - 全部通过
✅ 未引入新问题
✅ 原有功能保留

Deviations from the RCA

与RCA的偏差

[None — implemented as specified | List each deviation from the RCA + why]

[无——严格按指定实施 | 列出所有与RCA的偏差及原因]

Files Summary

文件摘要

Total Changes:

X files modified
Y files created (tests)
Z lines added
W lines removed

总更改统计:

修改了X个文件
创建了Y个文件（测试文件）
添加了Z行代码
删除了W行代码

Ready for Commit

准备提交

All changes complete and validated. Ready for the

piv-commit

skill.

Suggested commit message:

fix(scope): resolve GitHub issue #$ARGUMENTS - [brief description]

[Summary of what was fixed and how]

Fixes #$ARGUMENTS

Note: Using

Fixes #$ARGUMENTS

in the commit message will automatically close the GitHub issue when merged to the default branch.

所有更改已完成并通过验证。可使用

piv-commit

技能提交。

建议的提交信息:

fix(scope): resolve GitHub issue #$ARGUMENTS - [简短描述]

[修复内容及方式的摘要]

Fixes #$ARGUMENTS

注意: 在提交信息中使用

Fixes #$ARGUMENTS

，当提交合并到默认分支时会自动关闭该GitHub Issue。

Optional: Update GitHub Issue

可选：更新GitHub Issue

Add implementation comment to issue:

bash

gh issue comment $ARGUMENTS --body "Fix implemented in commit [commit-hash]. Ready for review."

Update issue labels (if needed):

bash

gh issue edit $ARGUMENTS --add-label "fixed" --remove-label "bug"

Close the issue (if not using auto-close via commit message):

bash

gh issue close $ARGUMENTS --comment "Fixed and merged."

在Issue中添加实施评论:

bash

gh issue comment $ARGUMENTS --body "Fix implemented in commit [commit-hash]. Ready for review."

更新Issue标签（如有需要）:

bash

gh issue edit $ARGUMENTS --add-label "fixed" --remove-label "bug"

关闭Issue（如果不使用提交信息自动关闭）:

bash

gh issue close $ARGUMENTS --comment "Fixed and merged."

Notes

注意事项

If the RCA document is missing or incomplete, request it be created first with the
```
piv-investigate-issue
```
skill for issue #$ARGUMENTS
If you discover the RCA analysis was incorrect, document findings and update the RCA
If additional issues are found during implementation, note them for separate GitHub issues and RCAs
Follow project coding standards exactly
Ensure all validation passes before declaring complete
The commit message
```
Fixes #$ARGUMENTS
```
will link the commit to the GitHub issue

如果RCA文档缺失或不完整，请先使用
```
piv-investigate-issue
```
技能为Issue #$ARGUMENTS生成RCA文档
如果发现RCA分析不正确，请记录发现并更新RCA
如果在实施过程中发现其他问题，请记录下来并创建单独的GitHub Issue和RCA
严格遵循项目编码规范
确保所有验证通过后再宣布完成
提交信息中的
```
Fixes #$ARGUMENTS
```
会将提交与GitHub Issue关联