mirror of
https://github.com/azaion/ai-training.git
synced 2026-04-22 11:16:35 +00:00
Update test results directory structure and enhance Docker configurations
- Modified `.gitignore` to reflect the new path for test results. - Updated `docker-compose.test.yml` to mount the correct test results directory. - Adjusted `Dockerfile.test` to set the `PYTHONPATH` and ensure test results are saved in the updated location. - Added `boto3` and `netron` to `requirements-test.txt` to support new functionalities. - Updated `pytest.ini` to include the new `pythonpath` for test discovery. These changes streamline the testing process and ensure compatibility with the updated directory structure.
This commit is contained in:
Oleksandr Bezdieniezhnykh
@@ -1,11 +1,13 @@
|
||||
---
|
||||
name: refactor
|
||||
description: |
|
||||
Structured 9-phase refactoring workflow with three execution modes:
|
||||
Full (all phases), Targeted (skip discovery), Quick Assessment (phases 0-2 only).
|
||||
Supports project mode (_docs/) and standalone mode (@file.md).
|
||||
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, hardening]
|
||||
tags: [refactoring, coupling, technical-debt, performance, testability]
|
||||
trigger_phrases: ["refactor", "refactoring", "improve code", "analyze coupling", "decoupling", "technical debt", "code quality"]
|
||||
disable-model-invocation: true
|
||||
---
|
||||
@@ -16,43 +18,61 @@ Phase details live in `phases/` — read the relevant file before executing each
|
||||
|
||||
## Core Principles
|
||||
|
||||
- **Preserve behavior first**: never refactor without a passing test suite
|
||||
- **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
|
||||
|
||||
Determine operating mode before any other logic runs. Announce detected mode and paths to user.
|
||||
Announce detected paths and input mode to user before proceeding.
|
||||
|
||||
| | Project mode (default) | Standalone mode (`/refactor @file.md`) |
|
||||
|---|---|---|
|
||||
| PROBLEM_DIR | `_docs/00_problem/` | N/A |
|
||||
| SOLUTION_DIR | `_docs/01_solution/` | N/A |
|
||||
| COMPONENTS_DIR | `_docs/02_document/components/` | N/A |
|
||||
| DOCUMENT_DIR | `_docs/02_document/` | N/A |
|
||||
| REFACTOR_DIR | `_docs/04_refactoring/` | `_standalone/refactoring/` |
|
||||
| Prereqs | `problem.md` required, `acceptance_criteria.md` warn if absent | INPUT_FILE must exist and be non-empty |
|
||||
**Fixed paths:**
|
||||
|
||||
Create REFACTOR_DIR if missing. If it already has artifacts, ask user: **resume or start fresh?**
|
||||
| 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/` |
|
||||
| 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, capture baseline metrics | BLOCKING: user confirms |
|
||||
| 1 | `phases/01-discovery.md` | Document components, synthesize solution | BLOCKING: user confirms |
|
||||
| 2 | `phases/02-analysis.md` | Research improvements, produce roadmap | BLOCKING: user confirms |
|
||||
| 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` | Design and implement pre-refactoring tests | GATE: all tests pass |
|
||||
| 4 | `phases/04-execution.md` | Analyze coupling, execute decoupling | BLOCKING: user confirms |
|
||||
| 5 | `phases/05-hardening.md` | Technical debt, performance, security | Optional: user picks tracks |
|
||||
| 6 | `phases/06-test-sync.md` | Remove obsolete, update broken, add new tests | GATE: all tests pass |
|
||||
| 7 | `phases/07-verification.md` | Run full suite, compare metrics vs baseline | GATE: all pass, no regressions |
|
||||
| 8 | `phases/08-documentation.md` | Update `_docs/` to reflect refactored state | Skip in standalone mode |
|
||||
| 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 |
|
||||
|
||||
**Mode detection:**
|
||||
**Workflow mode detection:**
|
||||
- "quick assessment" / "just assess" → phases 0–2
|
||||
- "refactor [specific target]" → skip phase 1 if docs exist
|
||||
- Default → all phases
|
||||
@@ -61,31 +81,36 @@ At the start of execution, create a TodoWrite with all applicable phases.
|
||||
|
||||
## Artifact Structure
|
||||
|
||||
All artifacts are written to REFACTOR_DIR:
|
||||
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
|
||||
coupling_analysis.md Phase 4
|
||||
execution_log.md Phase 4
|
||||
hardening/{technical_debt,performance,security}.md Phase 5
|
||||
test_sync/{obsolete_tests,updated_tests,new_tests}.md Phase 6
|
||||
verification_report.md Phase 7
|
||||
doc_update_log.md Phase 8
|
||||
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_DIR (not RUN_DIR):
|
||||
```
|
||||
TASKS_DIR/[JIRA-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 `REFACTOR_DIR/FINAL_report.md`:
|
||||
mode used, phases executed, baseline vs final metrics, changes summary, remaining items, lessons learned.
|
||||
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
|
||||
|
||||
@@ -97,3 +122,4 @@ mode used, phases executed, baseline vs final metrics, changes summary, remainin
|
||||
| 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 |
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Phase 0: Context & Baseline
|
||||
|
||||
**Role**: Software engineer preparing for refactoring
|
||||
**Goal**: Collect refactoring goals and capture baseline metrics
|
||||
**Goal**: Collect refactoring goals, create run directory, capture baseline metrics
|
||||
**Constraints**: Measurement only — no code changes
|
||||
|
||||
## 0a. Collect Goals
|
||||
@@ -14,7 +14,18 @@ If PROBLEM_DIR files do not yet exist, help the user create them:
|
||||
|
||||
Store in PROBLEM_DIR.
|
||||
|
||||
## 0b. Capture Baseline
|
||||
## 0b. Create RUN_DIR
|
||||
|
||||
1. Scan REFACTOR_DIR for existing `NN-*` folders
|
||||
2. Auto-increment the numeric prefix (e.g., if `01-testability-refactoring` exists, next is `02-...`)
|
||||
3. Determine the run name:
|
||||
- If guided mode with input file: derive from input file name or context (e.g., `01-testability-refactoring`)
|
||||
- If automatic mode: ask user for a short run name, or derive from goals (e.g., `01-coupling-refactoring`)
|
||||
4. Create `REFACTOR_DIR/NN-[run-name]/` — this is RUN_DIR for the rest of the workflow
|
||||
|
||||
Announce RUN_DIR path to user.
|
||||
|
||||
## 0c. Capture Baseline
|
||||
|
||||
1. Read problem description and acceptance criteria
|
||||
2. Measure current system metrics using project-appropriate tools:
|
||||
@@ -31,10 +42,11 @@ Store in PROBLEM_DIR.
|
||||
3. Create functionality inventory: all features/endpoints with status and coverage
|
||||
|
||||
**Self-verification**:
|
||||
- [ ] RUN_DIR created with correct auto-incremented prefix
|
||||
- [ ] All metric categories measured (or noted as N/A with reason)
|
||||
- [ ] Functionality inventory is complete
|
||||
- [ ] Measurements are reproducible
|
||||
|
||||
**Save action**: Write `REFACTOR_DIR/baseline_metrics.md`
|
||||
**Save action**: Write `RUN_DIR/baseline_metrics.md`
|
||||
|
||||
**BLOCKING**: Present baseline summary to user. Do NOT proceed until user confirms.
|
||||
|
||||
@@ -1,12 +1,61 @@
|
||||
# Phase 1: Discovery
|
||||
|
||||
**Role**: Principal software architect
|
||||
**Goal**: Generate documentation from existing code and form solution description
|
||||
**Constraints**: Document what exists, not what should be. No code changes.
|
||||
**Goal**: Analyze existing code and produce `RUN_DIR/list-of-changes.md`
|
||||
**Constraints**: Document what exists, identify what needs to change. No code changes.
|
||||
|
||||
**Skip condition** (Targeted mode): If `COMPONENTS_DIR` and `SOLUTION_DIR` already contain documentation for the target area, skip to Phase 2. Ask user to confirm skip.
|
||||
|
||||
## 1a. Document Components
|
||||
## Mode Branch
|
||||
|
||||
Determine the input mode set during Context Resolution (see SKILL.md):
|
||||
|
||||
- **Guided mode**: input file provided → start with 1g below
|
||||
- **Automatic mode**: no input file → start with 1a below
|
||||
|
||||
---
|
||||
|
||||
## Guided Mode
|
||||
|
||||
### 1g. Read and Validate Input File
|
||||
|
||||
1. Read the provided input file (e.g., `list-of-changes.md` from the autopilot testability revision step or user-provided file)
|
||||
2. Extract file paths, problem descriptions, and proposed changes from each entry
|
||||
3. For each entry, verify against actual codebase:
|
||||
- Referenced files exist
|
||||
- Described problems are accurate (read the code, confirm the issue)
|
||||
- Proposed changes are feasible
|
||||
4. Flag any entries that reference nonexistent files or describe inaccurate problems — ASK user
|
||||
|
||||
### 1h. Scoped Component Analysis
|
||||
|
||||
For each file/area referenced in the input file:
|
||||
|
||||
1. Analyze the specific modules and their immediate dependencies
|
||||
2. Document component structure, interfaces, and coupling points relevant to the proposed changes
|
||||
3. Identify additional issues not in the input file but discovered during analysis of the same areas
|
||||
|
||||
Write per-component to `RUN_DIR/discovery/components/[##]_[name].md` (same format as automatic mode, but scoped to affected areas only).
|
||||
|
||||
### 1i. Produce List of Changes
|
||||
|
||||
1. Start from the validated input file entries
|
||||
2. Enrich each entry with:
|
||||
- Exact file paths confirmed from code
|
||||
- Risk assessment (low/medium/high)
|
||||
- Dependencies between changes
|
||||
3. Add any additional issues discovered during scoped analysis (1h)
|
||||
4. Write `RUN_DIR/list-of-changes.md` using `templates/list-of-changes.md` format
|
||||
- Set **Mode**: `guided`
|
||||
- Set **Source**: path to the original input file
|
||||
|
||||
Skip to **Save action** below.
|
||||
|
||||
---
|
||||
|
||||
## Automatic Mode
|
||||
|
||||
### 1a. Document Components
|
||||
|
||||
For each component in the codebase:
|
||||
|
||||
@@ -14,33 +63,57 @@ For each component in the codebase:
|
||||
2. Go file by file, analyze each method
|
||||
3. Analyze connections between components
|
||||
|
||||
Write per component to `REFACTOR_DIR/discovery/components/[##]_[name].md`:
|
||||
Write per component to `RUN_DIR/discovery/components/[##]_[name].md`:
|
||||
- Purpose and architectural patterns
|
||||
- Mermaid diagrams for logic flows
|
||||
- API reference table (name, description, input, output)
|
||||
- Implementation details: algorithmic complexity, state management, dependencies
|
||||
- Caveats, edge cases, known limitations
|
||||
|
||||
## 1b. Synthesize Solution & Flows
|
||||
### 1b. Synthesize Solution & Flows
|
||||
|
||||
1. Review all generated component documentation
|
||||
2. Synthesize into a cohesive solution description
|
||||
3. Create flow diagrams showing component interactions
|
||||
|
||||
Write:
|
||||
- `REFACTOR_DIR/discovery/solution.md` — product description, component overview, interaction diagram
|
||||
- `REFACTOR_DIR/discovery/system_flows.md` — Mermaid flowcharts per major use case
|
||||
- `RUN_DIR/discovery/solution.md` — product description, component overview, interaction diagram
|
||||
- `RUN_DIR/discovery/system_flows.md` — Mermaid flowcharts per major use case
|
||||
|
||||
Also copy to project standard locations if in project mode:
|
||||
Also copy to project standard locations:
|
||||
- `SOLUTION_DIR/solution.md`
|
||||
- `DOCUMENT_DIR/system_flows.md`
|
||||
|
||||
### 1c. Produce List of Changes
|
||||
|
||||
From the component analysis and solution synthesis, identify all issues that need refactoring:
|
||||
|
||||
1. Hardcoded values (paths, config, magic numbers)
|
||||
2. Tight coupling between components
|
||||
3. Missing dependency injection / non-configurable parameters
|
||||
4. Global mutable state
|
||||
5. Code duplication
|
||||
6. Missing error handling
|
||||
7. Testability blockers (code that cannot be exercised in isolation)
|
||||
8. Security concerns
|
||||
9. Performance bottlenecks
|
||||
|
||||
Write `RUN_DIR/list-of-changes.md` using `templates/list-of-changes.md` format:
|
||||
- Set **Mode**: `automatic`
|
||||
- Set **Source**: `self-discovered`
|
||||
|
||||
---
|
||||
|
||||
## Save action (both modes)
|
||||
|
||||
Write all discovery artifacts to RUN_DIR.
|
||||
|
||||
**Self-verification**:
|
||||
- [ ] Every component in the codebase is documented
|
||||
- [ ] Solution description covers all components
|
||||
- [ ] Flow diagrams cover all major use cases
|
||||
- [ ] Every referenced file in list-of-changes.md exists in the codebase
|
||||
- [ ] Each change entry has file paths, problem, change description, risk, and dependencies
|
||||
- [ ] Component documentation covers all areas affected by the changes
|
||||
- [ ] In guided mode: all input file entries are validated or flagged
|
||||
- [ ] In automatic mode: solution description covers all components
|
||||
- [ ] Mermaid diagrams are syntactically correct
|
||||
|
||||
**Save action**: Write discovery artifacts
|
||||
|
||||
**BLOCKING**: Present discovery summary to user. Do NOT proceed until user confirms documentation accuracy.
|
||||
**BLOCKING**: Present discovery summary and list-of-changes.md to user. Do NOT proceed until user confirms documentation accuracy and change list completeness.
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Phase 2: Analysis
|
||||
# Phase 2: Analysis & Task Decomposition
|
||||
|
||||
**Role**: Researcher and software architect
|
||||
**Goal**: Research improvements and produce a refactoring roadmap
|
||||
**Constraints**: Analysis only — no code changes
|
||||
**Role**: Researcher, software architect, and task planner
|
||||
**Goal**: Research improvements, produce a refactoring roadmap, and decompose into implementable tasks
|
||||
**Constraints**: Analysis and planning only — no code changes
|
||||
|
||||
## 2a. Deep Research
|
||||
|
||||
@@ -11,31 +11,84 @@
|
||||
3. Identify what could be done differently
|
||||
4. Suggest improvements based on state-of-the-art practices
|
||||
|
||||
Write `REFACTOR_DIR/analysis/research_findings.md`:
|
||||
Write `RUN_DIR/analysis/research_findings.md`:
|
||||
- Current state analysis: patterns used, strengths, weaknesses
|
||||
- Alternative approaches per component: current vs alternative, pros/cons, migration effort
|
||||
- Prioritized recommendations: quick wins + strategic improvements
|
||||
|
||||
## 2b. Solution Assessment
|
||||
## 2b. Solution Assessment & Hardening Tracks
|
||||
|
||||
1. Assess current implementation against acceptance criteria
|
||||
2. Identify weak points in codebase, map to specific code areas
|
||||
3. Perform gap analysis: acceptance criteria vs current state
|
||||
4. Prioritize changes by impact and effort
|
||||
|
||||
Write `REFACTOR_DIR/analysis/refactoring_roadmap.md`:
|
||||
Present optional hardening tracks for user to include in the roadmap:
|
||||
|
||||
```
|
||||
══════════════════════════════════════
|
||||
DECISION REQUIRED: Include hardening tracks?
|
||||
══════════════════════════════════════
|
||||
A) Technical Debt — identify and address design/code/test debt
|
||||
B) Performance Optimization — profile, identify bottlenecks, optimize
|
||||
C) Security Review — OWASP Top 10, auth, encryption, input validation
|
||||
D) All of the above
|
||||
E) None — proceed with structural refactoring only
|
||||
══════════════════════════════════════
|
||||
```
|
||||
|
||||
For each selected track, add entries to `RUN_DIR/list-of-changes.md` (append to the file produced in Phase 1):
|
||||
- **Track A**: tech debt items with location, impact, effort
|
||||
- **Track B**: performance bottlenecks with profiling data
|
||||
- **Track C**: security findings with severity and fix description
|
||||
|
||||
Write `RUN_DIR/analysis/refactoring_roadmap.md`:
|
||||
- Weak points assessment: location, description, impact, proposed solution
|
||||
- Gap analysis: what's missing, what needs improvement
|
||||
- Phased roadmap: Phase 1 (critical fixes), Phase 2 (major improvements), Phase 3 (enhancements)
|
||||
- Selected hardening tracks and their items
|
||||
|
||||
## 2c. Create Epic
|
||||
|
||||
Create a Jira/ADO epic for this refactoring run:
|
||||
|
||||
1. Epic name: the RUN_DIR name (e.g., `01-testability-refactoring`)
|
||||
2. Create the epic via configured tracker MCP
|
||||
3. Record the Epic ID — all tasks in 2d will be linked under this epic
|
||||
4. If tracker unavailable, use `PENDING` placeholder and note for later
|
||||
|
||||
## 2d. Task Decomposition
|
||||
|
||||
Convert the finalized `RUN_DIR/list-of-changes.md` into implementable task files.
|
||||
|
||||
1. Read `RUN_DIR/list-of-changes.md`
|
||||
2. For each change entry (or group of related entries), create an atomic task file in TASKS_DIR:
|
||||
- Use the standard task template format (`.cursor/skills/decompose/templates/task.md`)
|
||||
- File naming: `[##]_refactor_[short_name].md` (temporary numeric prefix)
|
||||
- **Task**: `PENDING_refactor_[short_name]`
|
||||
- **Description**: derived from the change entry's Problem + Change fields
|
||||
- **Complexity**: estimate 1-5 points; split into multiple tasks if >5
|
||||
- **Dependencies**: map change-level dependencies (C01, C02) to task-level Jira IDs
|
||||
- **Component**: from the change entry's File(s) field
|
||||
- **Epic**: the epic created in 2c
|
||||
- **Acceptance Criteria**: derived from the change entry — verify the problem is resolved
|
||||
3. Create Jira/ADO ticket for each task under the epic from 2c
|
||||
4. Rename each file to `[JIRA-ID]_refactor_[short_name].md` after ticket creation
|
||||
5. Update or append to `TASKS_DIR/_dependencies_table.md` with the refactoring tasks
|
||||
|
||||
**Self-verification**:
|
||||
- [ ] All acceptance criteria are addressed in gap analysis
|
||||
- [ ] Recommendations are grounded in actual code, not abstract
|
||||
- [ ] Roadmap phases are prioritized by impact
|
||||
- [ ] Quick wins are identified separately
|
||||
- [ ] Epic created and all tasks linked to it
|
||||
- [ ] Every entry in list-of-changes.md has a corresponding task file in TASKS_DIR
|
||||
- [ ] No task exceeds 5 complexity points
|
||||
- [ ] Task dependencies are consistent (no circular dependencies)
|
||||
- [ ] `_dependencies_table.md` includes all refactoring tasks
|
||||
- [ ] Every task has a Jira ticket (or PENDING placeholder)
|
||||
|
||||
**Save action**: Write analysis artifacts
|
||||
**Save action**: Write analysis artifacts to RUN_DIR, task files to TASKS_DIR
|
||||
|
||||
**BLOCKING**: Present refactoring roadmap to user. Do NOT proceed until user confirms.
|
||||
**BLOCKING**: Present refactoring roadmap and task list to user. Do NOT proceed until user confirms.
|
||||
|
||||
**Quick Assessment mode stops here.** Present final summary and write `FINAL_report.md` with phases 0-2 content.
|
||||
|
||||
@@ -1,23 +1,45 @@
|
||||
# Phase 3: Safety Net
|
||||
|
||||
**Role**: QA engineer and developer
|
||||
**Goal**: Design and implement tests that capture current behavior before refactoring
|
||||
**Goal**: Ensure tests exist that capture current behavior before refactoring
|
||||
**Constraints**: Tests must all pass on the current codebase before proceeding
|
||||
|
||||
## 3a. Design Test Specs
|
||||
## Skip Condition: Testability Refactoring
|
||||
|
||||
Coverage requirements (must meet before refactoring — see `.cursor/rules/cursor-meta.mdc` Quality Thresholds):
|
||||
- Minimum overall coverage: 75%
|
||||
- Critical path coverage: 90%
|
||||
- All public APIs must have blackbox tests
|
||||
- All error handling paths must be tested
|
||||
If the current run name contains `testability` (e.g., `01-testability-refactoring`), **skip Phase 3 entirely**. The purpose of a testability run is to make the code testable so that tests can be written afterward. Announce the skip and proceed to Phase 4.
|
||||
|
||||
For each critical area, write test specs to `REFACTOR_DIR/test_specs/[##]_[test_name].md`:
|
||||
## 3a. Check Existing Tests
|
||||
|
||||
Before designing or implementing any new tests, check what already exists:
|
||||
|
||||
1. Scan the project for existing test files (unit tests, integration tests, blackbox tests)
|
||||
2. Run the existing test suite — record pass/fail counts
|
||||
3. Measure current coverage against the areas being refactored (from `RUN_DIR/list-of-changes.md` file paths)
|
||||
4. Assess coverage against thresholds:
|
||||
- Minimum overall coverage: 75%
|
||||
- Critical path coverage: 90%
|
||||
- All public APIs must have blackbox tests
|
||||
- All error handling paths must be tested
|
||||
|
||||
If existing tests meet all thresholds for the refactoring areas:
|
||||
- Document the existing coverage in `RUN_DIR/test_specs/existing_coverage.md`
|
||||
- Skip to the GATE check below
|
||||
|
||||
If existing tests partially cover the refactoring areas:
|
||||
- Document what is covered and what gaps remain
|
||||
- Proceed to 3b only for the uncovered areas
|
||||
|
||||
If no relevant tests exist:
|
||||
- Proceed to 3b for full test design
|
||||
|
||||
## 3b. Design Test Specs (for uncovered areas only)
|
||||
|
||||
For each uncovered critical area, write test specs to `RUN_DIR/test_specs/[##]_[test_name].md`:
|
||||
- Blackbox tests: summary, current behavior, input data, expected result, max expected time
|
||||
- Acceptance tests: summary, preconditions, steps with expected results
|
||||
- Coverage analysis: current %, target %, uncovered critical paths
|
||||
|
||||
## 3b. Implement Tests
|
||||
## 3c. Implement Tests (for uncovered areas only)
|
||||
|
||||
1. Set up test environment and infrastructure if not exists
|
||||
2. Implement each test from specs
|
||||
@@ -25,11 +47,11 @@ For each critical area, write test specs to `REFACTOR_DIR/test_specs/[##]_[test_
|
||||
4. Document any discovered issues
|
||||
|
||||
**Self-verification**:
|
||||
- [ ] Coverage requirements met (75% overall, 90% critical paths)
|
||||
- [ ] Coverage requirements met (75% overall, 90% critical paths) across existing + new tests
|
||||
- [ ] All tests pass on current codebase
|
||||
- [ ] All public APIs have blackbox tests
|
||||
- [ ] All public APIs in refactoring scope have blackbox tests
|
||||
- [ ] Test data fixtures are configured
|
||||
|
||||
**Save action**: Write test specs; implemented tests go into the project's test folder
|
||||
**Save action**: Write test specs to RUN_DIR; implemented tests go into the project's test folder
|
||||
|
||||
**GATE (BLOCKING)**: ALL tests must pass before proceeding to Phase 4. If tests fail, fix the tests (not the code) or ask user for guidance. Do NOT proceed to Phase 4 with failing tests.
|
||||
|
||||
@@ -1,45 +1,63 @@
|
||||
# Phase 4: Execution
|
||||
|
||||
**Role**: Software architect and developer
|
||||
**Goal**: Analyze coupling and execute decoupling changes
|
||||
**Constraints**: Small incremental changes; tests must stay green after every change
|
||||
**Role**: Orchestrator
|
||||
**Goal**: Execute all refactoring tasks by delegating to the implement skill
|
||||
**Constraints**: No inline code changes — all implementation goes through the implement skill's batching and review pipeline
|
||||
|
||||
## 4a. Analyze Coupling
|
||||
## 4a. Pre-Flight Checks
|
||||
|
||||
1. Analyze coupling between components/modules
|
||||
2. Map dependencies (direct and transitive)
|
||||
3. Identify circular dependencies
|
||||
4. Form decoupling strategy
|
||||
1. Verify refactoring task files exist in TASKS_DIR (created during Phase 2d):
|
||||
- All `[JIRA-ID]_refactor_*.md` files are present
|
||||
- Each task file has valid header fields (Task, Name, Description, Complexity, Dependencies)
|
||||
2. Verify `TASKS_DIR/_dependencies_table.md` includes the refactoring tasks
|
||||
3. Verify all tests pass (safety net from Phase 3 is green)
|
||||
4. If any check fails, go back to the relevant phase to fix
|
||||
|
||||
Write `REFACTOR_DIR/coupling_analysis.md`:
|
||||
- Dependency graph (Mermaid)
|
||||
- Coupling metrics per component
|
||||
- Problem areas: components involved, coupling type, severity, impact
|
||||
- Decoupling strategy: priority order, proposed interfaces/abstractions, effort estimates
|
||||
## 4b. Delegate to Implement Skill
|
||||
|
||||
**BLOCKING**: Present coupling analysis to user. Do NOT proceed until user confirms strategy.
|
||||
Read and execute `.cursor/skills/implement/SKILL.md`.
|
||||
|
||||
## 4b. Execute Decoupling
|
||||
The implement skill will:
|
||||
1. Parse task files and dependency graph from TASKS_DIR
|
||||
2. Detect already-completed tasks (skip non-refactoring tasks from prior workflow steps)
|
||||
3. Compute execution batches for the refactoring tasks
|
||||
4. Launch implementer subagents (up to 4 in parallel)
|
||||
5. Run code review after each batch
|
||||
6. Commit and push per batch
|
||||
7. Update Jira/ADO ticket status
|
||||
|
||||
For each change in the decoupling strategy:
|
||||
Do NOT modify, skip, or abbreviate any part of the implement skill's workflow. The refactor skill is delegating execution, not optimizing it.
|
||||
|
||||
1. Implement the change
|
||||
2. Run blackbox tests
|
||||
3. Fix any failures
|
||||
4. Commit with descriptive message
|
||||
## 4c. Capture Results
|
||||
|
||||
Address code smells encountered: long methods, large classes, duplicate code, dead code, magic numbers.
|
||||
After the implement skill completes:
|
||||
|
||||
Write `REFACTOR_DIR/execution_log.md`:
|
||||
- Change description, files affected, test status per change
|
||||
- Before/after metrics comparison against baseline
|
||||
1. Read batch reports from `_docs/03_implementation/batch_*_report.md`
|
||||
2. Read `_docs/03_implementation/FINAL_implementation_report.md`
|
||||
3. Write `RUN_DIR/execution_log.md` summarizing:
|
||||
- Total tasks executed
|
||||
- Batches completed
|
||||
- Code review verdicts per batch
|
||||
- Files modified (aggregate list)
|
||||
- Any blocked or failed tasks
|
||||
- Links to batch reports
|
||||
|
||||
## 4d. Update Task Statuses
|
||||
|
||||
For each successfully completed refactoring task:
|
||||
|
||||
1. Transition the Jira/ADO ticket status to **Done** via the configured tracker MCP
|
||||
2. If tracker unavailable, note the pending status transitions in `RUN_DIR/execution_log.md`
|
||||
|
||||
For any failed or blocked tasks, leave their status as-is (the implement skill already set them to In Testing or blocked).
|
||||
|
||||
**Self-verification**:
|
||||
- [ ] All refactoring tasks show as completed in batch reports
|
||||
- [ ] All completed tasks have Jira/ADO status set to Done
|
||||
- [ ] All tests still pass after execution
|
||||
- [ ] No circular dependencies remain (or reduced per plan)
|
||||
- [ ] Code smells addressed
|
||||
- [ ] Metrics improved compared to baseline
|
||||
- [ ] No tasks remain in blocked or failed state (or user has acknowledged them)
|
||||
- [ ] `RUN_DIR/execution_log.md` written with links to batch reports
|
||||
|
||||
**Save action**: Write execution artifacts
|
||||
**Save action**: Write `RUN_DIR/execution_log.md`
|
||||
|
||||
**BLOCKING**: Present execution summary to user. Do NOT proceed until user confirms.
|
||||
**GATE**: All refactoring tasks must be implemented. If any tasks failed, present the failures to the user and ask for guidance before proceeding to Phase 5.
|
||||
|
||||
@@ -1,51 +0,0 @@
|
||||
# Phase 5: Hardening (Optional, Parallel Tracks)
|
||||
|
||||
**Role**: Varies per track
|
||||
**Goal**: Address technical debt, performance, and security
|
||||
**Constraints**: Each track is optional; user picks which to run
|
||||
|
||||
Present the three tracks and let user choose which to execute:
|
||||
|
||||
## Track A: Technical Debt
|
||||
|
||||
**Role**: Technical debt analyst
|
||||
|
||||
1. Identify and categorize debt items: design, code, test, documentation
|
||||
2. Assess each: location, description, impact, effort, interest (cost of not fixing)
|
||||
3. Prioritize: quick wins → strategic debt → tolerable debt
|
||||
4. Create actionable plan with prevention measures
|
||||
|
||||
Write `REFACTOR_DIR/hardening/technical_debt.md`
|
||||
|
||||
## Track B: Performance Optimization
|
||||
|
||||
**Role**: Performance engineer
|
||||
|
||||
1. Profile current performance, identify bottlenecks
|
||||
2. For each bottleneck: location, symptom, root cause, impact
|
||||
3. Propose optimizations with expected improvement and risk
|
||||
4. Implement one at a time, benchmark after each change
|
||||
5. Verify tests still pass
|
||||
|
||||
Write `REFACTOR_DIR/hardening/performance.md` with before/after benchmarks
|
||||
|
||||
## Track C: Security Review
|
||||
|
||||
**Role**: Security engineer
|
||||
|
||||
1. Review code against OWASP Top 10
|
||||
2. Verify security requirements from `security_approach.md` are met
|
||||
3. Check: authentication, authorization, input validation, output encoding, encryption, logging
|
||||
|
||||
Write `REFACTOR_DIR/hardening/security.md`:
|
||||
- Vulnerability assessment: location, type, severity, exploit scenario, fix
|
||||
- Security controls review
|
||||
- Compliance check against `security_approach.md`
|
||||
- Recommendations: critical fixes, improvements, hardening
|
||||
|
||||
**Self-verification** (per track):
|
||||
- [ ] All findings are grounded in actual code
|
||||
- [ ] Recommendations are actionable with effort estimates
|
||||
- [ ] All tests still pass after any changes
|
||||
|
||||
**Save action**: Write hardening artifacts
|
||||
+12
-10
@@ -1,20 +1,22 @@
|
||||
# Phase 6: Test Synchronization
|
||||
# Phase 5: Test Synchronization
|
||||
|
||||
**Role**: QA engineer and developer
|
||||
**Goal**: Reconcile the test suite with the refactored codebase — remove obsolete tests, update broken tests, add tests for new code
|
||||
**Constraints**: All tests must pass at the end of this phase. Do not change production code here — only tests.
|
||||
|
||||
## 6a. Identify Obsolete Tests
|
||||
**Skip condition**: If the run name contains `testability`, skip Phase 5 entirely — no test suite exists yet to synchronize. Proceed directly to Phase 6.
|
||||
|
||||
## 5a. Identify Obsolete Tests
|
||||
|
||||
1. Compare the pre-refactoring codebase structure (from Phase 0 inventory) with the current state
|
||||
2. Find tests that reference removed functions, classes, modules, or endpoints
|
||||
3. Find tests that duplicate coverage due to merged/consolidated code
|
||||
4. Decide per test: **delete** (functionality removed) or **merge** (duplicates)
|
||||
|
||||
Write `REFACTOR_DIR/test_sync/obsolete_tests.md`:
|
||||
Write `RUN_DIR/test_sync/obsolete_tests.md`:
|
||||
- Test file, test name, reason (target removed / target merged / duplicate coverage), action taken (deleted / merged into)
|
||||
|
||||
## 6b. Update Existing Tests
|
||||
## 5b. Update Existing Tests
|
||||
|
||||
1. Run the full test suite — collect failures and errors
|
||||
2. For each failing test, determine the cause:
|
||||
@@ -24,28 +26,28 @@ Write `REFACTOR_DIR/test_sync/obsolete_tests.md`:
|
||||
- Changed data structures → update fixtures and assertions
|
||||
3. Fix each test, re-run to confirm it passes
|
||||
|
||||
Write `REFACTOR_DIR/test_sync/updated_tests.md`:
|
||||
Write `RUN_DIR/test_sync/updated_tests.md`:
|
||||
- Test file, test name, change type (import path / signature / assertion / fixture), description of update
|
||||
|
||||
## 6c. Add New Tests
|
||||
## 5c. Add New Tests
|
||||
|
||||
1. Identify new code introduced during Phases 4–5 that lacks test coverage:
|
||||
1. Identify new code introduced during Phase 4 that lacks test coverage:
|
||||
- New public functions, classes, or modules
|
||||
- New interfaces or abstractions introduced during decoupling
|
||||
- New error handling paths
|
||||
2. Write tests following the same patterns and conventions as the existing test suite
|
||||
3. Ensure coverage targets from Phase 3 are maintained or improved
|
||||
|
||||
Write `REFACTOR_DIR/test_sync/new_tests.md`:
|
||||
Write `RUN_DIR/test_sync/new_tests.md`:
|
||||
- Test file, test name, target function/module, coverage type (unit / integration / blackbox)
|
||||
|
||||
**Self-verification**:
|
||||
- [ ] All obsolete tests removed or merged
|
||||
- [ ] All pre-existing tests pass after updates
|
||||
- [ ] New code from Phases 4–5 has test coverage
|
||||
- [ ] New code from Phase 4 has test coverage
|
||||
- [ ] Overall coverage meets or exceeds Phase 3 baseline (75% overall, 90% critical paths)
|
||||
- [ ] No tests reference removed or renamed code
|
||||
|
||||
**Save action**: Write test_sync artifacts; implemented tests go into the project's test folder
|
||||
|
||||
**GATE (BLOCKING)**: ALL tests must pass before proceeding to Phase 7. If tests fail, fix the tests or ask user for guidance.
|
||||
**GATE (BLOCKING)**: ALL tests must pass before proceeding to Phase 6. If tests fail, fix the tests or ask user for guidance.
|
||||
+12
-10
@@ -1,20 +1,22 @@
|
||||
# Phase 7: Final Verification
|
||||
# Phase 6: Final Verification
|
||||
|
||||
**Role**: QA engineer
|
||||
**Goal**: Run all tests end-to-end, compare final metrics against baseline, and confirm the refactoring succeeded
|
||||
**Constraints**: No code changes. If failures are found, go back to the appropriate phase (4/5/6) to fix before retrying.
|
||||
**Constraints**: No code changes. If failures are found, go back to the appropriate phase (4/5) to fix before retrying.
|
||||
|
||||
## 7a. Run Full Test Suite
|
||||
**Skip condition**: If the run name contains `testability`, skip Phase 6 entirely — no test suite exists yet to verify against. Proceed directly to Phase 7.
|
||||
|
||||
## 6a. Run Full Test Suite
|
||||
|
||||
1. Run unit tests, integration tests, and blackbox tests
|
||||
2. Run acceptance tests derived from `acceptance_criteria.md`
|
||||
3. Record pass/fail counts and any failures
|
||||
|
||||
If any test fails:
|
||||
- Determine whether the failure is a test issue (→ return to Phase 6) or a code issue (→ return to Phase 4/5)
|
||||
- Determine whether the failure is a test issue (→ return to Phase 5) or a code issue (→ return to Phase 4)
|
||||
- Do NOT proceed until all tests pass
|
||||
|
||||
## 7b. Capture Final Metrics
|
||||
## 6b. Capture Final Metrics
|
||||
|
||||
Re-measure all metrics from Phase 0 baseline using the same tools:
|
||||
|
||||
@@ -27,14 +29,14 @@ Re-measure all metrics from Phase 0 baseline using the same tools:
|
||||
| **Dependencies** | Total count, outdated, security vulnerabilities |
|
||||
| **Build** | Build time, test execution time, deployment time |
|
||||
|
||||
## 7c. Compare Against Baseline
|
||||
## 6c. Compare Against Baseline
|
||||
|
||||
1. Read `REFACTOR_DIR/baseline_metrics.md`
|
||||
1. Read `RUN_DIR/baseline_metrics.md`
|
||||
2. Produce a side-by-side comparison: baseline vs final for every metric
|
||||
3. Flag any regressions (metrics that got worse)
|
||||
4. Verify acceptance criteria are met
|
||||
|
||||
Write `REFACTOR_DIR/verification_report.md`:
|
||||
Write `RUN_DIR/verification_report.md`:
|
||||
- Test results summary: total, passed, failed, skipped
|
||||
- Metric comparison table: metric, baseline value, final value, delta, status (improved / unchanged / regressed)
|
||||
- Acceptance criteria checklist: criterion, status (met / not met), evidence
|
||||
@@ -46,6 +48,6 @@ Write `REFACTOR_DIR/verification_report.md`:
|
||||
- [ ] No critical metric regressions
|
||||
- [ ] Metrics are captured with the same tools/methodology as Phase 0
|
||||
|
||||
**Save action**: Write `REFACTOR_DIR/verification_report.md`
|
||||
**Save action**: Write `RUN_DIR/verification_report.md`
|
||||
|
||||
**GATE (BLOCKING)**: All tests must pass and no critical regressions. Present verification report to user. Do NOT proceed to Phase 8 until user confirms.
|
||||
**GATE (BLOCKING)**: All tests must pass and no critical regressions. Present verification report to user. Do NOT proceed to Phase 7 until user confirms.
|
||||
+12
-13
@@ -1,36 +1,35 @@
|
||||
# Phase 8: Documentation Update
|
||||
# Phase 7: Documentation Update
|
||||
|
||||
**Role**: Technical writer
|
||||
**Goal**: Update existing `_docs/` artifacts to reflect all changes made during refactoring
|
||||
**Constraints**: Documentation only — no code changes. Only update docs that are affected by refactoring changes.
|
||||
|
||||
**Skip condition**: If no `_docs/02_document/` directory exists (standalone mode), skip this phase entirely.
|
||||
**Skip condition**: If no `_docs/02_document/` directory exists, skip this phase entirely.
|
||||
|
||||
## 8a. Identify Affected Documentation
|
||||
## 7a. Identify Affected Documentation
|
||||
|
||||
1. Review `REFACTOR_DIR/execution_log.md` to list all files changed during Phase 4
|
||||
2. Review any hardening changes from Phase 5
|
||||
3. Review test changes from Phase 6
|
||||
4. Map changed files to their corresponding module docs in `_docs/02_document/modules/`
|
||||
5. Map changed modules to their parent component docs in `_docs/02_document/components/`
|
||||
6. Determine if system-level docs need updates (`architecture.md`, `system-flows.md`, `data_model.md`)
|
||||
7. Determine if test documentation needs updates (`_docs/02_document/tests/`)
|
||||
1. Review `RUN_DIR/execution_log.md` to list all files changed during Phase 4
|
||||
2. Review test changes from Phase 5
|
||||
3. Map changed files to their corresponding module docs in `_docs/02_document/modules/`
|
||||
4. Map changed modules to their parent component docs in `_docs/02_document/components/`
|
||||
5. Determine if system-level docs need updates (`architecture.md`, `system-flows.md`, `data_model.md`)
|
||||
6. Determine if test documentation needs updates (`_docs/02_document/tests/`)
|
||||
|
||||
## 8b. Update Module Documentation
|
||||
## 7b. Update Module Documentation
|
||||
|
||||
For each module doc affected by refactoring changes:
|
||||
1. Re-read the current source file
|
||||
2. Update the module doc to reflect new/changed interfaces, dependencies, internal logic
|
||||
3. Remove documentation for deleted code; add documentation for new code
|
||||
|
||||
## 8c. Update Component Documentation
|
||||
## 7c. Update Component Documentation
|
||||
|
||||
For each component doc affected:
|
||||
1. Re-read the updated module docs within the component
|
||||
2. Update inter-module interfaces, dependency graphs, caveats
|
||||
3. Update the component relationship diagram if component boundaries changed
|
||||
|
||||
## 8d. Update System-Level Documentation
|
||||
## 7d. Update System-Level Documentation
|
||||
|
||||
If structural changes were made (new modules, removed modules, changed interfaces):
|
||||
1. Update `_docs/02_document/architecture.md` if architecture changed
|
||||
@@ -0,0 +1,49 @@
|
||||
# List of Changes Template
|
||||
|
||||
Save as `RUN_DIR/list-of-changes.md`. Produced during Phase 1 (Discovery).
|
||||
|
||||
---
|
||||
|
||||
```markdown
|
||||
# List of Changes
|
||||
|
||||
**Run**: [NN-run-name]
|
||||
**Mode**: [automatic | guided]
|
||||
**Source**: [self-discovered | path/to/input-file.md]
|
||||
**Date**: [YYYY-MM-DD]
|
||||
|
||||
## Summary
|
||||
|
||||
[1-2 sentence overview of what this refactoring run addresses]
|
||||
|
||||
## Changes
|
||||
|
||||
### C01: [Short Title]
|
||||
- **File(s)**: [file paths, comma-separated]
|
||||
- **Problem**: [what makes this problematic / untestable / coupled]
|
||||
- **Change**: [what to do — behavioral description, not implementation steps]
|
||||
- **Rationale**: [why this change is needed]
|
||||
- **Risk**: [low | medium | high]
|
||||
- **Dependencies**: [other change IDs this depends on, or "None"]
|
||||
|
||||
### C02: [Short Title]
|
||||
- **File(s)**: [file paths]
|
||||
- **Problem**: [description]
|
||||
- **Change**: [description]
|
||||
- **Rationale**: [description]
|
||||
- **Risk**: [low | medium | high]
|
||||
- **Dependencies**: [C01, or "None"]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Change IDs** use format `C##` (C01, C02, ...) — sequential within the run
|
||||
- Each change should map to one atomic task (1-5 complexity points); split if larger
|
||||
- **File(s)** must reference actual files verified to exist in the codebase
|
||||
- **Problem** describes the current state, not the desired state
|
||||
- **Change** describes what the system should do differently — behavioral, not prescriptive
|
||||
- **Dependencies** reference other change IDs within this list; cross-run dependencies use Jira IDs
|
||||
- In guided mode, the input file entries are validated against actual code and enriched with file paths, risk, and dependencies before writing
|
||||
- In automatic mode, entries are derived from Phase 1 component analysis and Phase 2 research findings
|
||||
Reference in New Issue
Block a user