complete-refactor-plan

name: complete-refactor-plan description: Guide for completing and archiving refactoring plans in the torrust-tracker-deployer project. Covers moving entries from active to completed, updating documentation, and cleanup procedures. Use when finishing refactorings, archiving plans, or marking refactor work as done. Triggers on "complete refactor", "finish refactor plan", "archive refactor", "mark refactor done", or "refactor cleanup". metadata: author: torrust version: "1.0"

Completing Refactoring Plans

This skill guides you through the completion and cleanup process for refactoring plans in the Torrust Tracker Deployer project.

Quick Reference

# 1. Verify all proposals are completed
# 2. Move entry from active-refactorings.md to completed-refactorings.md
# 3. Delete the plan document from docs/refactors/plans/
# 4. Commit changes

When to Complete a Refactor

Complete a refactor when:

✅ All active proposals are implemented and merged
✅ All tests pass
✅ All linters pass
✅ Documentation is updated
✅ Changes are merged to main branch

Completion Workflow

Step 1: Verify Completion Criteria

Check the plan document's completion criteria:

### Completion Criteria

- [x] All active proposals implemented
- [x] All tests passing
- [x] All linters passing
- [x] Documentation updated
- [x] Code reviewed and approved
- [x] Changes merged to main branch

CRITICAL: All checkboxes must be checked before proceeding.

Step 2: Gather Completion Information

From the refactoring plan document, collect:

Plan title - The descriptive name of the refactoring
Target area - Brief description of what was refactored
Creation date - When the plan was created
Completion date - Today's date
Key details - Phases completed, final commit hash, related issues/PRs
Notable outcomes - Lines changed, files affected, improvements gained

Step 3: Update completed-refactorings.md

Edit docs/refactors/completed-refactorings.md and add a new row at the top of the table:

| Document               | Completed    | Target                   | Notes                                                                                          |
| ---------------------- | ------------ | ------------------------ | ---------------------------------------------------------------------------------------------- |
| Your Refactoring Title | MMM DD, YYYY | Brief target description | See git history at `docs/refactors/plans/your-file.md` - Key details (phases, commits, issues) |
| [Previous entries...]  | ...          | ...                      | ...                                                                                            |

Format Guidelines:

Document: Plain text title (no link needed - file will be deleted)
Completed: Month DD, YYYY format (e.g., "Feb 11, 2026")
Target: Brief description of what was refactored (1-10 words)
Notes: Comprehensive summary including:
- Git history reference: See git history at \docs/refactors/plans/{filename}.md``
- Number of phases completed
- Final commit hash (8 characters)
- Related issue or PR numbers
- Key metrics (files changed, lines changed, improvements)

Example Entry:

| Extract Template Rendering Services | Feb 10, 2026 | Eliminate rendering duplication | See git history at `docs/refactors/plans/extract-template-rendering-services.md` - Extracted template rendering logic into shared application-layer services for all 8 template types, eliminating duplication between render command and Steps (5 phases completed, final commit 463e7933) |

Step 4: Remove from active-refactorings.md

Edit docs/refactors/active-refactorings.md and delete the entire row for the completed refactoring:

Before:

| Document                               | Status         | Issue | Target             | Created    |
| -------------------------------------- | -------------- | ----- | ------------------ | ---------- |
| [Your Refactoring](plans/your-file.md) | 🚧 In Progress | TBD   | Target description | 2026-02-01 |
| [Other active refactoring](plans/...)  | 📋 Planning    | TBD   | ...                | ...        |

After:

| Document                              | Status      | Issue | Target | Created |
| ------------------------------------- | ----------- | ----- | ------ | ------- |
| [Other active refactoring](plans/...) | 📋 Planning | TBD   | ...    | ...     |

Step 5: Delete the Plan Document

Remove the detailed plan document from the repository:

git rm docs/refactors/plans/your-refactoring-file.md

Why delete the plan?

The work is now in git history (commits, PRs)
Completed plans are indexed in completed-refactorings.md
Historical plan can be recovered from git history if needed
Keeps the plans/ directory focused on active work

Exception: If the plan has ongoing reference value or contains unique insights not captured elsewhere, you may choose to keep it, but this is rare.

Step 6: Commit the Changes

Stage and commit all changes:

# Stage the updated index files
git add docs/refactors/active-refactorings.md docs/refactors/completed-refactorings.md

# Commit with conventional format
git commit -m "docs: complete [refactoring-name] refactor plan"

Example commit messages:

git commit -m "docs: complete extract-template-rendering-services refactor plan"
git commit -m "docs: complete simplify-error-handling refactor plan"
git commit -m "docs: complete ssh-client-improvements refactor plan"

Completion Entry Format

Standard Entry Template

| [Refactoring Title] | [Month DD, YYYY] | [Brief Target] | See git history at `docs/refactors/plans/[filename].md` - [Key accomplishments, phases, commits, issues] |

Components Explained

1. Refactoring Title

Plain text (no markdown link)
Same as the H1 heading in the plan document
Example: "Extract Template Rendering Services"

2. Completed Date

Format: "Month DD, YYYY"
Use three-letter month abbreviation
Example: "Feb 11, 2026"

3. Brief Target

1-10 words describing what was refactored
Action-oriented when possible
Examples:
- "Eliminate rendering duplication"
- "Split 562-line file into focused submodule"
- "Move topology rules to domain"

4. Notes

Always start with: See git history at \docs/refactors/plans/{filename}.md``
Include:
- Summary of what was accomplished
- Number of phases completed (e.g., "5 phases completed")
- Final commit hash (8 characters, e.g., "final commit 463e7933")
- Related issue or PR numbers (e.g., "Issue #243" or "PR #319")
- Key metrics if significant (files affected, lines changed)
- Special notes (e.g., "superseded by...", "4 postponed", "Epic #287")

Real-World Examples

Simple Refactoring:

| Rename Test Functions to Follow Conventions | Dec 12, 2025 | All test functions with `test_` prefix (21 files) | See git history at `docs/refactors/plans/rename-test-functions-to-follow-conventions.md` - Renamed 93 test functions and 14 helper functions across 20 files to follow behavior-driven naming conventions (21 proposals, all completed), PR #228 |

Complex Refactoring with Epic:

| Docker Compose Topology Domain Model | Jan 26, 2026 | Move topology rules to domain, derive volumes/networks | See git history at `docs/refactors/plans/docker-compose-topology-domain-model.md` - Moved all Docker Compose topology decisions to domain layer with Network/Service enums and DockerComposeTopology aggregate (Epic #287, 8 proposals) |

Refactoring with Postponed Work:

| Command Code Quality Improvements | Dec 3, 2025 | `ProvisionCommand`, `ConfigureCommand` | See git history at `docs/refactors/plans/command-code-quality-improvements.md` - API simplification, state persistence, clock injection, trace writing, and test builders (5 of 9 proposals completed, 4 postponed for future work) |

Superseded Refactoring:

| User Output Architecture Improvements | Nov 13, 2025 | `src/presentation/views/` (formerly `user_output`) | See git history at `docs/refactors/plans/user-output-architecture-improvements.md` - Superseded by Presentation Layer Reorganization which renamed user_output to views and integrated it into four-layer MVC architecture |

Best Practices

Documentation Quality

✅ Do:

Provide complete git history reference
Include all relevant issue/PR numbers
Document key metrics and outcomes
Note if work was postponed or superseded
Use consistent date format (MMM DD, YYYY)
Add entry at the top of the completed table

❌ Don't:

Link to deleted files
Skip the git history reference
Use vague descriptions
Forget to remove from active-refactorings.md
Delete plan without updating indexes

Timing

Complete the refactor when:

All code is merged to main
Documentation is updated
Tests and linters pass
No pending PRs related to the refactor

Don't complete prematurely:

If proposals are still in review
If documentation updates are pending
If related issues are still open
If follow-up work is planned soon

Special Cases

Paused Refactoring

If a refactoring is paused, update the status in active-refactorings.md:

| Document                          | Status    | Issue | Target | Created    |
| --------------------------------- | --------- | ----- | ------ | ---------- |
| [Your Refactoring](plans/file.md) | ⏸️ Paused | TBD   | ...    | 2026-02-01 |

Don't move to completed until actually finished.

Cancelled Refactoring

If a refactoring is cancelled:

Update status in active-refactorings.md to ❌ Cancelled
Add note explaining why (superseded, no longer needed, etc.)
Delete the plan document
Optionally move to completed-refactorings.md with cancellation note

Partial Completion

If only some proposals were completed:

Document which proposals were completed
Note which were postponed or discarded
Consider if remaining work should be a new separate plan
Example: "5 of 9 proposals completed, 4 postponed for future work"

Verification Checklist

Before completing a refactor, verify:

All active proposals are implemented and merged
All tests pass (cargo test)
All linters pass (cargo run --bin linter all)
E2E tests pass (if applicable)
Documentation is updated
Related issues/PRs are closed or merged
Entry added to completed-refactorings.md at the top
Entry removed from active-refactorings.md
Plan document deleted (or archived if keeping)
Changes committed with conventional commit message

Key Reminders

Verify all completion criteria before proceeding
Add entry at the top of completed-refactorings.md
Include git history reference in notes
Remove from active-refactorings.md completely
Delete the plan document from plans/
Use conventional commit message for changes
Document key outcomes (phases, commits, issues, metrics)