bug-remediation-architect

name	bug-remediation-architect
description	Workflow for analyzing bug reports, tracing root causes, and generating structured bug-fix implementation plans with rollback strategies.
license	MIT

Bug Remediation Architect Skill

Overview

This skill outlines the diagnostic workflow to investigate reported bugs, identify root causes, and generate formal, executable implementation plans to fix them safely. It prioritizes Test-Driven Bug Fixing and rollback planning. This skill accompanies the @BugRemediationArchitect agent.

When to Use

• When investigating a reported bug or issue in the codebase.
• When generating a structured bug-fix plan in the /plan/ directory.

---

Phase 1: Bug Investigation & Root Cause Analysis Workflow

1. Information Gathering & Simulation: Read and understand the symptoms. Reproduce the bug if possible, or simulate the scenario by tracing the code logic using search and read tools.
2. Root Cause Identification: Pinpoint the exact file, function, and logic error causing the issue.
3. Determine Minimal Fix: Formulate a solution that fixes the root cause with the least amount of code changes. Consider edge cases and potential regressions.
4. Present Findings: Output your diagnosis in the chat using the following structured format (in Bahasa Indonesia):
   • Laporan Masalah (Issue Summary): A brief restatement of the bug.
   • Akar Masalah (Root Cause): Detailed technical explanation of why the bug occurs. Mention specific files and lines of code.
   • Strategi Perbaikan (Remediation Strategy): How you plan to fix it minimally.
5. Discuss Strategy: Ensure the user agrees with your diagnosis and proposed fix before moving to Phase 2.

---

Phase 2: Fix Plan Generation Workflow

1. Ask the user (in Bahasa Indonesia): "Saya telah menemukan akar masalahnya. Apakah Anda ingin saya membuat dokumen Implementation Plan resmi untuk memperbaiki bug ini?"
2. Filename: Use the naming convention bug-fix-YYYYMMDD-[short-description].md (e.g., bug-fix-20260603-auth-crash.md) and save it in the /plan/ directory.
3. Template: The file MUST strictly adhere to the template below, enforcing step-by-step execution, testing, rollback strategies, and mandatory approval checkpoints.

---

Mandatory Bug Fix Plan Template

---
goal: [Concise Title Describing the Bug Fix]
version: [Optional: e.g., 1.0, Date]
date_created: [YYYY-MM-DD]
last_updated: [Optional: YYYY-MM-DD]
owner: [Optional: Team/Individual responsible for this spec]
status: "Planned"
tags: ["bug-fix", "remediation", "patch"]
---

# Introduction

![Status: <status>](https://img.shields.io/badge/status-<status>-<status_color>)

[A short concise introduction to the bug being addressed, its impact, and the root cause that was identified during analysis.]

## 1. Requirements & Constraints (Fix Constraints)

[Explicitly list the constraints for this bug fix, ensuring no regressions are introduced.]

- **REQ-001**: The fix must resolve [Specific Issue].
- **CON-001**: The fix must not alter the existing public API response structure.
- **CON-002**: Backward compatibility must be maintained.

## 2. Implementation Steps

> **⚠️ EXECUTION DIRECTIVE FOR AI AGENTS:** 
> You MUST execute this plan phase by phase. You MUST run the specific testing/verification task at the end of each phase. After a phase is tested, you **MUST STOP AND WAIT** for the user's explicit approval before proceeding to the next phase.

### Implementation Phase 1: Test Writing (Test-Driven Bug Fixing)
- GOAL-001: Write a failing test that reproduces the exact bug described.

| Task     | Description                                                             | Completed | Date |
| -------- | ----------------------------------------------------------------------- | --------- | ---- |
| TASK-001 | Write unit/integration test to reproduce the bug                        |           |      |
| TASK-00X | **VERIFY**: Run the test. It MUST FAIL.                                 |           |      |
| TASK-00Y | **APPROVAL**: Wait for explicit user confirmation to proceed to Phase 2 |           |      |

### Implementation Phase 2: Minimal Root Cause Remediation
- GOAL-002: Implement the core logic fix in the production code without over-engineering.

| Task     | Description                                                  | Completed | Date |
| -------- | ------------------------------------------------------------ | --------- | ---- |
| TASK-002 | Apply the minimal fix to [Specific File/Function]            |           |      |
| TASK-003 | Clean up any adjacent code affected by the fix               |           |      |
| TASK-00X | **VERIFY**: Run the test from Phase 1. It MUST PASS.         |           |      |
| TASK-00Y | **APPROVAL**: Wait for explicit user confirmation to proceed |           |      |

## 3. Rollback Strategy

[Describe the exact steps to revert this fix if it causes unexpected issues in production or breaks related systems.]

- **RBCK-001**: Step 1 to revert changes.
- **RBCK-002**: Step 2 to restore previous state.

## 4. Dependencies

[List any dependencies that need to be updated as part of this fix.]

- **DEP-001**: Dependency 1

## 5. Files Affected

[List all files that will be modified to fix this bug.]

- **FILE-001**: Description of file 1

## 6. Testing Strategy & Edge Cases

[Describe how this bug will be prevented from recurring in the future and note any specific edge cases considered during the fix.]

- **TEST-001**: Description of test strategy

## 7. Risks & Assumptions

[List any risks related to this fix, such as potential side effects on other modules.]

- **RISK-001**: Risk 1