issue-fixer

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Issue Fixer

Issue 修复工具

Overview

概述

This skill provides a comprehensive, systematic workflow for investigating and fixing issues with minimal impact. It ensures proper issue tracking, thorough root cause analysis, impact assessment, quality validation, and automated testing for all fixes.

该技能提供一套全面、系统化的工作流程，可在最小影响下调查并修复问题。它确保所有修复工作都包含规范的问题追踪、全面的根本原因分析、影响评估、质量验证以及自动化测试环节。

When to Use This Skill

适用场景

Invoke this skill when:

User reports a bug or unexpected behavior
Tests are failing and need investigation
Features are broken or not working as expected
User explicitly requests a fix for a specific issue
Error messages or exceptions need resolution

在以下场景中调用此技能：

用户报告bug或异常行为
测试失败且需要调查原因
功能故障或未按预期运行
用户明确要求修复特定问题
需要解决错误提示或异常问题

Core Workflow

核心工作流程

The issue-fixing process follows seven sequential phases:

Issue Registration - Track the issue in
```
.issues/opening.md
```
Investigation - Find all related code and identify root cause
Impact Assessment - Determine if it requires a simple fix or feature plan
Implementation - Apply minimal, surgical changes
Validation - Run quality checks and tests
E2E Testing - Create/update end-to-end tests for full-stack fixes
Finalization - Update issue status and generate summary

问题修复流程包含七个连续阶段：

问题登记 - 在
```
.issues/opening.md
```
中记录问题
调查分析 - 查找所有相关代码并确定根本原因
影响评估 - 判断问题只需简单修复还是需要制定功能规划
修复实施 - 进行最小化、精准的代码修改
验证环节 - 执行质量检查与测试
E2E测试 - 为全栈修复创建/更新端到端测试
收尾工作 - 更新问题状态并生成总结

Quick Start Decision Tree

快速启动决策树

User reports issue
    │
    ├─→ Is issue already tracked in .issues/opening.md?
    │   ├─→ Yes: Note issue number, proceed to Investigation
    │   └─→ No: Register new issue, proceed to Investigation
    │
    └─→ After investigation, what is the impact?
        ├─→ HIGH (6+ files, 200+ LOC, architecture changes, breaking changes)
        │   └─→ Create feature plan, suggest handoff to speckit.plan, STOP
        │
        └─→ LOW/MEDIUM (1-5 files, <200 LOC, no breaking changes)
            └─→ Proceed with implementation → validation → testing → finalization

User reports issue
    │
    ├─→ Is issue already tracked in .issues/opening.md?
    │   ├─→ Yes: Note issue number, proceed to Investigation
    │   └─→ No: Register new issue, proceed to Investigation
    │
    └─→ After investigation, what is the impact?
        ├─→ HIGH (6+ files, 200+ LOC, architecture changes, breaking changes)
        │   └─→ Create feature plan, suggest handoff to speckit.plan, STOP
        │
        └─→ LOW/MEDIUM (1-5 files, <200 LOC, no breaking changes)
            └─→ Proceed with implementation → validation → testing → finalization

Detailed Workflow

详细工作流程

For the complete step-by-step guide covering all seven phases, refer to:

references/workflow.md
- Comprehensive workflow with detailed instructions for each phase including:

Issue registration format and procedures
Code discovery and root cause analysis techniques
Impact assessment criteria and decision points
Implementation principles and patterns
Quality validation commands for backend and frontend
E2E testing guidelines and patterns
Issue finalization procedures

Load this reference when beginning an issue fix to understand the complete process.

如需了解涵盖所有七个阶段的完整分步指南，请参考：

references/workflow.md
- 包含各阶段详细说明的完整工作流程，内容包括：

问题登记的格式与流程
代码排查与根本原因分析技巧
影响评估的标准与决策节点
修复实施的原则与模式
前后端的质量验证命令
E2E测试的指南与模式
问题收尾的流程

开始修复问题前，请查阅此文档以了解完整流程。

Critical Principles

关键原则

Always follow these principles when fixing issues:

Minimal Changes - Modify only what's necessary to fix the issue
No Unrelated Changes - Don't fix other issues or refactor unrelated code
Preserve Working Code - Don't delete functioning code
Follow Existing Patterns - Match the project's architecture and style
Type Safety - Maintain or improve type annotations
Proper Error Handling - Add error handling if missing
Test Incrementally - Run checks after each file modification
Document Decisions - Add comments explaining non-obvious fixes

修复问题时请始终遵循以下原则：

最小化修改 - 仅修改修复问题所需的代码
不修改无关内容 - 不要修复其他问题或重构无关代码
保留可用代码 - 不要删除可正常运行的代码
遵循现有模式 - 与项目的架构和风格保持一致
类型安全 - 保持或优化类型注解
完善错误处理 - 若缺失则添加错误处理逻辑
增量测试 - 每次修改文件后执行检查
记录决策 - 为非直观的修复添加注释说明

Project Standards

项目规范

Always review and follow project-specific standards before making changes:

Backend:

.github/instructions/backend.instructions.md

Frontend:

.github/instructions/frontend.instructions.md

Python:

.github/instructions/python_standard.instructions.md

TypeScript:

.github/instructions/ts_standard.instructions.md

在修改代码前，请务必查阅并遵循项目特定规范：

后端：

.github/instructions/backend.instructions.md

前端：

.github/instructions/frontend.instructions.md

Python：

.github/instructions/python_standard.instructions.md

TypeScript：

.github/instructions/ts_standard.instructions.md

Quality Checks

质量检查

Backend (Python)

后端（Python）

bash

undefined

bash

undefined

Type checking (must pass with 0 errors)

python -m pyright app/

Formatting

ruff format app/

Linting

ruff check app/ --fix

Tests

pytest tests/ -v

undefined

pytest tests/ -v

undefined

Frontend (TypeScript)

前端（TypeScript）

bash

undefined

bash

undefined

Build (includes type check and lint)

cd frontend && npm run build

Tests (if available)

npm test

undefined

npm test

undefined

Resources

资源

references/workflow.md

Complete step-by-step guide for all seven phases of issue fixing, including:

Detailed instructions for each phase
Code discovery and analysis techniques
Impact assessment criteria
Implementation patterns
E2E testing guidelines
Example code snippets and templates

问题修复全七阶段的完整分步指南，内容包括：

各阶段的详细说明
代码排查与分析技巧
影响评估标准
修复实施模式
E2E测试指南
示例代码片段与模板