diagnose-plan-implement-safe

name	diagnose-plan-implement-safe
description	Reviews affected files and issues first, creates a scoped implementation plan, then executes changes in phases with tests between phases while avoiding unrelated code or behavior changes. Use when implementing features, fixing issues, or making multi-step code changes safely.

Diagnose, Plan, Implement Safely

Purpose

Use this workflow to make reliable, low-risk code changes:

• inspect first
• plan with explicit scope
• implement in phases
• run tests between phases
• avoid unrelated modifications

Workflow

Phase 1: Diagnose and Scope

1. Identify the requested feature or fix and restate the exact goal.
2. Inspect only relevant code paths first:
   • files directly related to the feature
   • upstream/downstream callers
   • existing tests tied to the behavior
3. Detect the concrete issue (if any) before editing:
   • root cause
   • impacted components
   • regression risk areas
4. Build an affected-file inventory with status:
   • modify: existing files that must change
   • add: new files required
   • verify-only: files/tests to read or run without editing

Do not edit files in this phase.

Phase 2: Plan Before Coding

Create a short plan containing:

1. Goal and non-goals.
2. Ordered implementation phases.
3. File-level change list per phase (modify / add).
4. Validation strategy per phase (tests, lint, smoke checks).
5. Risk notes and rollback points.

Keep the plan tightly scoped to the requested feature.

Phase 3: Implement Phase by Phase

For each phase:

1. Apply only the planned file changes for that phase.
2. Keep behavior unchanged outside the requested scope.
3. Run relevant tests before continuing:
   • start with targeted tests
   • run broader tests when phase boundaries are crossed
4. If tests fail:
   • fix the failure before moving to the next phase
   • update the plan only when needed

Do not continue to the next phase while current-phase tests are failing.

Phase 4: Final Verification

Before completion:

1. Re-check changed files for unrelated edits.
2. Confirm no non-requested behavior changes were introduced.
3. Run final validation appropriate to scope.
4. Summarize:
   • what changed
   • which files were modified/added
   • which tests were run and results
   • remaining risks (if any)

Guardrails

• Never modify unrelated features, flows, or styling unless explicitly requested.
• Prefer minimal, surgical edits over broad refactors.
• Preserve existing behavior for untouched features.
• Keep naming, structure, and conventions consistent with the codebase.
• If scope expands, pause and request confirmation before adding extra work.

Output Template

Use this structure when reporting work:

## Diagnosis
- Goal:
- Root cause:
- Affected files:
  - modify:
  - add:
  - verify-only:

## Plan
- Phase 1:
- Phase 2:
- Validation per phase:

## Implementation Progress
- Phase 1 changes:
- Phase 1 test results:
- Phase 2 changes:
- Phase 2 test results:

## Final Verification
- Unrelated changes check:
- Final test results:
- Residual risks: