mirror of
https://github.com/azaion/satellite-provider.git
synced 2026-04-23 00:56:38 +00:00
Sync .cursor from detections
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -0,0 +1,126 @@
|
||||
---
|
||||
name: refactor
|
||||
description: |
|
||||
Structured 8-phase refactoring workflow with two input modes:
|
||||
Automatic (skill discovers issues) and Guided (input file with change list).
|
||||
Each run gets its own subfolder in _docs/04_refactoring/.
|
||||
Delegates code execution to the implement skill via task files in _docs/02_tasks/.
|
||||
Additional workflow modes: Targeted (skip discovery), Quick Assessment (phases 0-2 only).
|
||||
category: evolve
|
||||
tags: [refactoring, coupling, technical-debt, performance, testability]
|
||||
trigger_phrases: ["refactor", "refactoring", "improve code", "analyze coupling", "decoupling", "technical debt", "code quality"]
|
||||
disable-model-invocation: true
|
||||
---
|
||||
|
||||
# Structured Refactoring
|
||||
|
||||
Phase details live in `phases/` — read the relevant file before executing each phase.
|
||||
|
||||
## Core Principles
|
||||
|
||||
- **Preserve behavior first**: never refactor without a passing test suite (exception: testability runs, where the goal is making code testable)
|
||||
- **Measure before and after**: every change must be justified by metrics
|
||||
- **Small incremental changes**: commit frequently, never break tests
|
||||
- **Save immediately**: write artifacts to disk after each phase
|
||||
- **Delegate execution**: all code changes go through the implement skill via task files
|
||||
- **Ask, don't assume**: when scope or priorities are unclear, STOP and ask the user
|
||||
|
||||
## Context Resolution
|
||||
|
||||
Announce detected paths and input mode to user before proceeding.
|
||||
|
||||
**Fixed paths:**
|
||||
|
||||
| Path | Location |
|
||||
|------|----------|
|
||||
| PROBLEM_DIR | `_docs/00_problem/` |
|
||||
| SOLUTION_DIR | `_docs/01_solution/` |
|
||||
| COMPONENTS_DIR | `_docs/02_document/components/` |
|
||||
| DOCUMENT_DIR | `_docs/02_document/` |
|
||||
| TASKS_DIR | `_docs/02_tasks/` |
|
||||
| TASKS_TODO | `_docs/02_tasks/todo/` |
|
||||
| REFACTOR_DIR | `_docs/04_refactoring/` |
|
||||
| RUN_DIR | `REFACTOR_DIR/NN-[run-name]/` |
|
||||
|
||||
**Prereqs**: `problem.md` required, `acceptance_criteria.md` warn if absent.
|
||||
|
||||
**RUN_DIR resolution**: on start, scan REFACTOR_DIR for existing `NN-*` folders. Auto-increment the numeric prefix for the new run. The run name is derived from the invocation context (e.g., `01-testability-refactoring`, `02-coupling-refactoring`). If invoked with a guided input file, derive the name from the input file name or ask the user.
|
||||
|
||||
Create REFACTOR_DIR and RUN_DIR if missing. If a RUN_DIR with the same name already exists, ask user: **resume or start fresh?**
|
||||
|
||||
## Input Modes
|
||||
|
||||
| Mode | Trigger | Discovery source |
|
||||
|------|---------|-----------------|
|
||||
| Automatic | Default, no input file | Skill discovers issues from code analysis |
|
||||
| Guided | Input file provided (e.g., `/refactor @list-of-changes.md`) | Reads input file + scans code to form validated change list |
|
||||
|
||||
Both modes produce `RUN_DIR/list-of-changes.md` (template: `templates/list-of-changes.md`). Both modes then convert that file into task files in TASKS_DIR during Phase 2.
|
||||
|
||||
**Guided mode cleanup**: after `RUN_DIR/list-of-changes.md` is created from the input file, delete the original input file to avoid duplication.
|
||||
|
||||
## Workflow
|
||||
|
||||
| Phase | File | Summary | Gate |
|
||||
|-------|------|---------|------|
|
||||
| 0 | `phases/00-baseline.md` | Collect goals, create RUN_DIR, capture baseline metrics | BLOCKING: user confirms |
|
||||
| 1 | `phases/01-discovery.md` | Document components (scoped for guided mode), produce list-of-changes.md | BLOCKING: user confirms |
|
||||
| 2 | `phases/02-analysis.md` | Research improvements, produce roadmap, create epic, decompose into tasks in TASKS_DIR | BLOCKING: user confirms |
|
||||
| | | *Quick Assessment stops here* | |
|
||||
| 3 | `phases/03-safety-net.md` | Check existing tests or implement pre-refactoring tests (skip for testability runs) | GATE: all tests pass |
|
||||
| 4 | `phases/04-execution.md` | Delegate task execution to implement skill | GATE: implement completes |
|
||||
| 5 | `phases/05-test-sync.md` | Remove obsolete, update broken, add new tests | GATE: all tests pass |
|
||||
| 6 | `phases/06-verification.md` | Run full suite, compare metrics vs baseline | GATE: all pass, no regressions |
|
||||
| 7 | `phases/07-documentation.md` | Update `_docs/` to reflect refactored state | Skip if `_docs/02_document/` absent |
|
||||
|
||||
**Workflow mode detection:**
|
||||
- "quick assessment" / "just assess" → phases 0–2
|
||||
- "refactor [specific target]" → skip phase 1 if docs exist
|
||||
- Default → all phases
|
||||
|
||||
At the start of execution, create a TodoWrite with all applicable phases.
|
||||
|
||||
## Artifact Structure
|
||||
|
||||
All artifacts are written to RUN_DIR:
|
||||
|
||||
```
|
||||
baseline_metrics.md Phase 0
|
||||
discovery/components/[##]_[name].md Phase 1
|
||||
discovery/solution.md Phase 1
|
||||
discovery/system_flows.md Phase 1
|
||||
list-of-changes.md Phase 1
|
||||
analysis/research_findings.md Phase 2
|
||||
analysis/refactoring_roadmap.md Phase 2
|
||||
test_specs/[##]_[test_name].md Phase 3
|
||||
execution_log.md Phase 4
|
||||
test_sync/{obsolete_tests,updated_tests,new_tests}.md Phase 5
|
||||
verification_report.md Phase 6
|
||||
doc_update_log.md Phase 7
|
||||
FINAL_report.md after all phases
|
||||
```
|
||||
|
||||
Task files produced during Phase 2 go to TASKS_TODO (not RUN_DIR):
|
||||
```
|
||||
TASKS_TODO/[TRACKER-ID]_refactor_[short_name].md
|
||||
TASKS_DIR/_dependencies_table.md (appended)
|
||||
```
|
||||
|
||||
**Resumability**: match existing artifacts to phases above, resume from next incomplete phase.
|
||||
|
||||
## Final Report
|
||||
|
||||
After all phases complete, write `RUN_DIR/FINAL_report.md`:
|
||||
mode used (automatic/guided), input mode, phases executed, baseline vs final metrics, changes summary, remaining items, lessons learned.
|
||||
|
||||
## Escalation Rules
|
||||
|
||||
| Situation | Action |
|
||||
|-----------|--------|
|
||||
| Unclear scope or ambiguous criteria | **ASK user** |
|
||||
| Tests failing before refactoring | **ASK user** — fix tests or fix code? |
|
||||
| Risk of breaking external contracts | **ASK user** |
|
||||
| Performance vs readability trade-off | **ASK user** |
|
||||
| No test suite or CI exists | **WARN user**, suggest safety net first |
|
||||
| Security vulnerability found | **WARN user** immediately |
|
||||
| Implement skill reports failures | **ASK user** — review batch reports |
|
||||
Reference in New Issue
Block a user