Refactor Backlog and Roadmap

Transform the migration plan into actionable deliverables: a prioritized task backlog, a milestone-based roadmap with Gantt visualization, and architecture decision records (RFCs) for all major decisions. This is the final skill in the brownfield pipeline, producing the artifacts that engineering teams use to execute the migration.

When to Use This Skill

• After completing Migration Strategy to generate executable work items
• When engineering teams need a concrete task backlog to begin refactoring
• When management needs a visual roadmap with milestones and progress tracking
• When major architecture decisions need formal documentation for team alignment
• As the final output of the brownfield analysis pipeline

Pipeline Position

[MIGRATION_PLAN.md + ARCH_GAPS_AND_RISKS.md + TO_BE_ARCHITECTURE.md] --> **REFACTOR BACKLOG & ROADMAP** --> [REFACTOR_TASKS.md + ROADMAP.md + RFC_LIST.md]

Input: MIGRATION_PLAN.md, ARCH_GAPS_AND_RISKS.md, TO_BE_ARCHITECTURE.md Output: REFACTOR_TASKS.md, ROADMAP.md, and RFC_LIST.md written to artifacts directory

Artifact Template

All three output artifacts follow the standard artifact template:

# [ARTIFACT TITLE]
## Summary
## Inputs
## Outputs
## Assumptions
## Open Questions
## Main Content
## Acceptance Criteria

Process

Step 1: Read Upstream Artifacts

1. Read MIGRATION_PLAN.md to understand:
   • Phase structure (PHASE-NNNN) with changes (CHG-NNNN)
   • Validation gates (GATE-NNNN) with criteria
   • Risk mitigations per phase
   • Timeline estimates and dependencies
2. Read ARCH_GAPS_AND_RISKS.md to understand:
   • Gap inventory (GAP-NNNN) with priorities and categories
   • Risk registry (RISK-NNNN) with severities
   • Hotspot analysis (most impacted files/components)
3. Read TO_BE_ARCHITECTURE.md to understand:
   • Target components (TCOMP-NNNN)
   • Technology decisions (TDEC-NNNN)
   • Interface contracts (IFACE-NNNN)
   • Architecture principles (PRINC-NNNN)

Step 2: Generate Refactor Tasks

Decompose each migration phase change into concrete, actionable engineering tasks.

1. For each CHG-NNNN in each PHASE-NNNN, generate one or more tasks:

   • Break large changes into subtasks that can be independently code-reviewed
   • Each task should be completable in 1-5 days by one engineer
   • Include both implementation tasks and validation/testing tasks

2. Task format:

### TASK-0001: [Task Title]
- **Phase**: PHASE-NNNN
- **Priority**: P0 | P1 | P2
- **Type**: Implementation | Refactor | Test | Migration | Configuration | Documentation | Validation
- **Effort**: XS (< 2h) | S (2-8h) | M (1-3d) | L (3-5d) | XL (5-10d)
- **Description**: [What needs to be done, specifically]
- **Addresses**: [GAP-NNNN and/or RISK-NNNN that this task resolves or mitigates]
- **Dependencies**: [TASK-NNNN IDs that must complete before this task, or "None"]
- **Component**: [TCOMP-NNNN or COMP-NNNN affected]
- **Acceptance Criteria**:
  - [ ] [Specific, verifiable criterion]
  - [ ] [Additional criterion]
- **Testing Requirements**:
  - [ ] [Unit tests for new/changed code]
  - [ ] [Integration tests for interface changes]
  - [ ] [Regression tests for preserved behavior]
- **Rollback Notes**: [How to undo this task if needed]

3. Task categories to generate for each phase change:

   • Preparation tasks: Set up feature flags, create abstraction layers, add monitoring
   • Implementation tasks: Write new code, refactor existing code, introduce new patterns
   • Data tasks: Schema migrations, data transformations, backfill scripts
   • Test tasks: Write tests for new behavior, update tests for changed behavior, add regression tests
   • Validation tasks: Run validation gate checks, performance benchmarks, security scans
   • Cleanup tasks: Remove old code paths, update documentation, close feature flags

4. Assign TASK-NNNN IDs: Sort all tasks first by PHASE-NNNN (numerically), then by priority (P0 first), then alphabetically by task title. Assign sequential four-digit numbers starting at 0001.

Step 3: Build Task Dependency Graph

Map dependencies between tasks to enable parallel execution where possible.

1. Identify dependencies:

   • Tasks within the same phase may have internal dependencies
   • Tasks in later phases depend on gate-passing tasks in earlier phases
   • Validation tasks depend on their corresponding implementation tasks
   • Cleanup tasks depend on validation tasks

2. Dependency diagram:

```mermaid
graph TD
    TASK-0001[Introduce repository interface] --> TASK-0003[Implement repository for User]
    TASK-0001 --> TASK-0004[Implement repository for Order]
    TASK-0002[Add validation middleware] --> TASK-0005[Apply validation to user routes]
    TASK-0003 --> TASK-0006[Integration tests for User repo]
    TASK-0004 --> TASK-0007[Integration tests for Order repo]
    TASK-0006 --> TASK-0008[GATE-0001 validation]
    TASK-0007 --> TASK-0008
    TASK-0005 --> TASK-0008

3. **Identify parallelizable task groups**: Tasks with no mutual dependencies that can be worked on simultaneously

### Step 4: Build Roadmap with Milestones

Create a milestone-based roadmap that maps phases to calendar time.

1. **Define milestones**:
```markdown
### MS-0001: [Milestone Title]
- **Phase**: PHASE-NNNN
- **Target Date**: [Date or relative offset]
- **Gate**: GATE-NNNN
- **Description**: [What this milestone represents]
- **Success Criteria**:
  - [ ] [Specific criterion]
  - [ ] [Additional criterion]
- **Tasks Included**: [TASK-NNNN list]
- **Dependencies**: [MS-NNNN IDs that must complete first, or "None"]
- **Risk Factors**: [What could delay this milestone]

2. Assign MS-NNNN IDs: Sort milestones by target date (earliest first), then alphabetically by title for same-date milestones. Assign sequentially starting at 0001.

3. Gantt chart:

```mermaid
gantt
    title Refactoring Roadmap
    dateFormat  YYYY-MM-DD

    section Phase 1: Foundation
    TASK-0001: Introduce repository interface    :t1, 2026-03-01, 3d
    TASK-0002: Add validation middleware         :t2, 2026-03-01, 2d
    TASK-0003: Implement User repository         :t3, after t1, 3d
    TASK-0004: Implement Order repository        :t4, after t1, 3d
    TASK-0005: Apply validation to user routes   :t5, after t2, 2d
    TASK-0006: Integration tests (User)          :t6, after t3, 2d
    TASK-0007: Integration tests (Order)         :t7, after t4, 2d
    MS-0001: Foundation Complete                 :milestone, m1, after t6 t7 t5, 0d

    section Phase 2: Security
    TASK-0008: Implement auth service            :t8, after m1, 5d
    TASK-0009: Rotate secrets to vault           :t9, after m1, 3d
    MS-0002: Security Hardened                   :milestone, m2, after t8 t9, 0d

4. **Progress tracking table**:
```markdown
| MS ID | Phase | Title | Target Date | Status | Tasks Total | Tasks Done | % |
|-------|-------|-------|-------------|--------|-------------|-----------|---|
| MS-0001 | PHASE-0001 | Foundation Complete | 2026-03-14 | Not Started | 7 | 0 | 0% |
| MS-0002 | PHASE-0002 | Security Hardened | 2026-03-21 | Not Started | 4 | 0 | 0% |

Step 5: Create Architecture Decision Records (RFCs)

Document major architecture decisions as formal RFCs.

1. Identify RFC-worthy decisions: Every TDEC-NNNN from the target architecture, plus any significant migration approach decisions

2. RFC format:

### RFC-0001: [Decision Title]
- **Status**: Proposed | Accepted | Rejected | Superseded
- **Date**: [Date proposed]
- **Decision Makers**: [Roles/stakeholders involved]
- **Related**: [TDEC-NNNN, PRINC-NNNN, GAP-NNNN, RISK-NNNN]

#### Context
[What situation necessitates this decision? What problem are we solving?]
> [Evidence from gap analysis or codebase] [ARCH_GAPS: GAP-NNNN]

#### Decision
[What is the decision? State it clearly and specifically.]

#### Alternatives Considered
| Alternative | Description | Pros | Cons |
|------------|-------------|------|------|
| [Option A] | [Brief description] | [Advantages] | [Disadvantages] |
| [Option B] | [Brief description] | [Advantages] | [Disadvantages] |
| **[Chosen]** | **[Brief description]** | **[Advantages]** | **[Disadvantages]** |

#### Consequences
**Positive**:
- [Benefit 1]
- [Benefit 2]

**Negative**:
- [Trade-off 1]
- [Trade-off 2]

**Neutral**:
- [Side effect that is neither clearly positive nor negative]

#### Implementation Notes
- [Key implementation consideration]
- [Migration phase where this applies]: PHASE-NNNN
- [Tasks that implement this decision]: TASK-NNNN

#### Reversibility
- **Level**: High | Medium | Low
- **Reversal Cost**: [What it would take to undo this decision]
- **Time Window**: [How long before reversal becomes impractical]

3. Assign RFC-NNNN IDs: Sort all RFCs alphabetically by decision title, assign sequentially starting at 0001

Step 6: Build Cross-Reference Index

Create a master index linking all artifact IDs across the entire brownfield pipeline.

1. Task traceability matrix:

| TASK ID | Phase | GAP/RISK | TCOMP | TDEC | RFC | Milestone |
|---------|-------|----------|-------|------|-----|-----------|
| TASK-0001 | PHASE-0001 | GAP-0001 | TCOMP-0004 | TDEC-0002 | RFC-0003 | MS-0001 |

2. Completeness check: Ensure every GAP-NNNN and RISK-NNNN has at least one TASK-NNNN addressing it

Step 7: Compile All Three Artifacts

Write the three output artifacts.

7a: REFACTOR_TASKS.md

1. Write following the template
2. Verify tasks cover all CHG entries from MIGRATION_PLAN.md
3. Verify task dependencies form a valid DAG
4. Include task dependency diagram and summary statistics

7b: ROADMAP.md

1. Write following the template
2. Verify milestones cover all phases
3. Verify Gantt chart reflects task dependencies
4. Include progress tracking table (initialized at 0%)

7c: RFC_LIST.md

1. Write following the template
2. Verify every TDEC-NNNN has a corresponding RFC
3. Verify alternatives are documented for each RFC
4. Include RFC summary table and cross-reference index

Output Format

REFACTOR_TASKS.md Structure

# Refactor Tasks: [Project Name]

## Summary
[Total tasks, breakdown by phase, breakdown by priority, estimated total effort]

## Inputs
- MIGRATION_PLAN.md
- ARCH_GAPS_AND_RISKS.md

## Outputs
- REFACTOR_TASKS.md (this document)

## Assumptions
- [ASM-NNNN]: [Assumption]

## Open Questions
- [OQ-NNNN]: [Question]

## Main Content

### Task Summary
| Phase | P0 Tasks | P1 Tasks | P2 Tasks | Total | Est. Effort |
|-------|----------|----------|----------|-------|-------------|

### Task Inventory

#### PHASE-0001: [Title]
[TASK-NNNN entries sorted by priority then title]

#### PHASE-0002: [Title]
[TASK-NNNN entries]

### Task Dependency Graph
```mermaid
[Dependency diagram]

Parallelization Opportunities

Group	Tasks	Can Start After	Est. Duration

Gap/Risk Coverage

GAP/RISK ID	Tasks Addressing	Status

Acceptance Criteria

• Every CHG-NNNN from migration plan has at least one task
• Every GAP-NNNN has at least one task addressing it
• Every RISK-NNNN has at least one mitigation task
• Task dependencies form valid DAG
• Every task has acceptance criteria and testing requirements
• Effort estimates provided for all tasks

### ROADMAP.md Structure

```markdown
# Roadmap: [Project Name]

## Summary
[Number of milestones, total timeline, key phases]

## Inputs
- MIGRATION_PLAN.md
- REFACTOR_TASKS.md

## Outputs
- ROADMAP.md (this document)

## Assumptions
- [ASM-NNNN]: [Assumption]

## Open Questions
- [OQ-NNNN]: [Question]

## Main Content

### Milestone Overview
| MS ID | Phase | Title | Target | Gate | Tasks | Status |
|-------|-------|-------|--------|------|-------|--------|

### Milestone Details
[MS-NNNN entries with full detail]

### Timeline
```mermaid
gantt
[Gantt chart with tasks and milestones]

Progress Tracking

MS ID	Tasks Total	Tasks Done	% Complete	On Track

Critical Path

[Longest dependency chain that determines minimum timeline]

graph LR
[Critical path diagram highlighting blocking tasks]

Risk to Timeline

Risk	Impact on Timeline	Mitigation

Acceptance Criteria

• Every phase has at least one milestone
• Gantt chart reflects task dependencies accurately
• Critical path identified
• Progress tracking initialized
• Timeline risks documented

### RFC_LIST.md Structure

```markdown
# Architecture Decision Records: [Project Name]

## Summary
[Number of RFCs, breakdown by status, key decisions]

## Inputs
- TO_BE_ARCHITECTURE.md
- MIGRATION_PLAN.md
- ARCH_GAPS_AND_RISKS.md

## Outputs
- RFC_LIST.md (this document)

## Assumptions
- [ASM-NNNN]: [Assumption]

## Open Questions
- [OQ-NNNN]: [Question]

## Main Content

### RFC Summary
| RFC ID | Title | Status | Category | Reversibility | Related TDEC |
|--------|-------|--------|----------|---------------|-------------|

### Architecture Decision Records
[RFC-NNNN entries with full detail]

### Decision Dependency Map
```mermaid
graph TD
[Which decisions depend on or constrain other decisions]

Cross-Reference Index

RFC ID	Gaps Addressed	Risks Mitigated	Tasks	Phase

Acceptance Criteria

• Every TDEC-NNNN from target architecture has an RFC
• Every RFC documents at least 2 alternatives considered
• Consequences (positive, negative, neutral) documented for each RFC
• Reversibility assessed for each decision
• Implementation notes reference specific phases and tasks

**Output paths**:
- `artifacts/brownfield/<project_name>/REFACTOR_TASKS.md`
- `artifacts/brownfield/<project_name>/ROADMAP.md`
- `artifacts/brownfield/<project_name>/RFC_LIST.md`

**Templates**:
- `${CLAUDE_PLUGIN_ROOT}/reference/templates/REFACTOR_TASKS.template.md`
- `${CLAUDE_PLUGIN_ROOT}/reference/templates/ROADMAP.template.md`
- `${CLAUDE_PLUGIN_ROOT}/reference/templates/RFC_LIST.template.md`

## Determinism Rules

These rules ensure reproducible output regardless of when or how many times the skill is invoked on the same inputs.

1. **TASK-NNNN IDs**: Sort by PHASE (numerically), then by priority (P0 first), then alphabetically by task title (case-insensitive). Assign sequential four-digit numbers starting at 0001 globally across all phases.
2. **MS-NNNN IDs**: Sort by target date (earliest first), then alphabetically by title for same-date milestones. Assign sequentially starting at 0001.
3. **RFC-NNNN IDs**: Sort alphabetically by decision title (case-insensitive). Assign sequentially starting at 0001.
4. **Task summary table rows**: Sort by Phase ID numerically
5. **Milestone overview rows**: Sort by MS-NNNN ID numerically
6. **RFC summary rows**: Sort by RFC-NNNN ID numerically
7. **Alternatives table rows**: Sort alphabetically by alternative name; chosen alternative bolded
8. **Cross-reference rows**: Sort by primary ID (TASK, MS, or RFC) numerically
9. **Sections**: Always in template order, never reordered
10. **No timestamps**: Do not include generation timestamps in artifact body (Gantt chart dates are planning estimates, not generation timestamps)
11. **Gantt task IDs**: Use lowercase `t` prefix with sequential numbers matching TASK-NNNN where possible
12. **Progress tracking**: Initialize all tasks at 0% / Not Started

## Evidence Citation Rules

Refactor backlog and roadmap reference upstream artifacts throughout.

**Format for upstream references**: `[ARTIFACT_NAME: ID]` (e.g., `[MIGRATION: PHASE-0001]`, `[ARCH_GAPS: GAP-0003]`, `[TO_BE: TCOMP-0004]`, `[TO_BE: TDEC-0001]`)

**Examples**:
```markdown
> This task implements the repository pattern defined in [TO_BE: TCOMP-0004] to address [ARCH_GAPS: GAP-0001]
> Milestone MS-0001 corresponds to passing [MIGRATION: GATE-0001] at the end of [MIGRATION: PHASE-0001]
> This RFC documents the decision recorded in [TO_BE: TDEC-0002] motivated by [ARCH_GAPS: GAP-0005, RISK-0003]

Rules:

• Every TASK must reference the GAP/RISK it addresses
• Every TASK must reference the PHASE it belongs to
• Every MS must reference the GATE it validates
• Every RFC must reference the TDEC it documents
• Codebase [file:line] references are acceptable in task descriptions when referencing specific files to modify

Quality Checklist

Before finalizing all three artifacts, verify:

REFACTOR_TASKS.md

• Every CHG-NNNN from MIGRATION_PLAN.md decomposed into tasks
• Every GAP-NNNN has at least one task addressing it
• Every RISK-NNNN has at least one mitigation task
• Task dependencies form a valid DAG (no circular dependencies)
• Every task has acceptance criteria and testing requirements
• Effort estimates use standard sizes (XS/S/M/L/XL)
• Tasks are granular enough for 1-5 day completion
• Parallelization opportunities identified

ROADMAP.md

• Every PHASE has at least one milestone
• Gantt chart reflects task dependencies accurately
• Critical path identified and highlighted
• Progress tracking table initialized at 0%
• Timeline risks documented with mitigations
• Milestones have clear success criteria

RFC_LIST.md

• Every TDEC-NNNN from target architecture has a corresponding RFC
• Every RFC documents at least 2 alternatives with pros/cons
• Consequences (positive, negative, neutral) documented
• Reversibility level assessed for each decision
• Implementation notes reference specific PHASE and TASK IDs
• Decision dependency map shows constraints between decisions

Cross-Artifact Consistency

• TASK-NNNN IDs referenced in ROADMAP match those in REFACTOR_TASKS
• MS-NNNN IDs referenced in tasks match those in ROADMAP
• RFC-NNNN cross-references are consistent across all three artifacts
• Total task counts in summary tables match actual task entries
• Timeline in ROADMAP aligns with duration estimates in tasks

Error Handling

• MIGRATION_PLAN.md not found: Report error; direct user to run migration-strategy first
• ARCH_GAPS_AND_RISKS.md not found: Report error; direct user to run architecture-gap-analysis first
• TO_BE_ARCHITECTURE.md not found: Report error; direct user to run target-architecture first
• No changes in migration plan: If migration plan concludes no changes needed, generate minimal artifacts documenting this conclusion
• Task decomposition too granular or too coarse: Aim for 1-5 day tasks; if a change cannot be decomposed below XL, note it as a complex task requiring further breakdown during sprint planning
• Circular task dependencies: Restructure tasks to break cycles; if impossible, document in Open Questions
• Missing duration estimates: Use ranges and flag uncertainty in Assumptions
• Too many RFCs: If more than 15 TDEC decisions exist, group minor decisions into a single "Minor Decisions" RFC and only create full RFCs for decisions with Medium or Low reversibility