Refactoring Agent Systems

Refactoring Agent Systems

Overview

Refactoring agent systems IS applying clean code principles to agent configurations.

Re-analyze after changes, compare before/after, fix remaining issues, simplify over-engineering.

Core principle: Refactoring without measurement is guessing. Analyze, then change, then verify.

Routing

Pattern: Skill Steps Handoff: none Next: none Chain: main (terminal)

Task Initialization (MANDATORY)

Follow task initialization protocol.

Tasks:

1. Load review findings
2. Prioritize issues
3. Execute refactoring
4. Final verification
5. Produce refactoring report
6. Archive pipeline documents

Announce: "Created 6 tasks. Starting execution..."

Task 1: Load Review Findings

Goal: Load the review report as the basis for refactoring.

If review report path was provided (from reviewing-agent-systems):

1. Read the review report
2. Extract all Critical and Major issues
3. These are your refactoring targets

If no review report (standalone invocation):

1. Invoke reviewing-agent-systems skill first to produce a report
2. Then continue with the report's findings

Verification: Have a list of specific issues to fix from the review report.

Task 2: Prioritize Issues

Goal: Classify and order issues from the review report for fixing.

Priority order:

1. Critical — must fix before shipping
2. Major — should fix for quality
3. Minor — nice to have, fix if time permits

Present the prioritized list to user. Do NOT summarize — show each issue with its component, severity, and planned fix.

Ask: "這些修正項目正確嗎？要開始修正嗎？"

Verification: User has confirmed the prioritized fix list.

Task 3: Execute Refactoring

Goal: Fix remaining and new issues.

Refactoring actions (in priority order):

Important: All edits happen in main conversation. Never delegate refactoring writes to subagents.

For each refactoring action:

1. Identify the specific change
2. Make the edit
3. Verify the fix resolves the issue
4. Move to next action

Verification: All REMAINING and NEW issues addressed.

Task 4: Final Verification

Goal: Confirm no critical issues remain.

Re-run the relevant reviewer agents on components that were modified in Task 3.

Pass criteria:

• Zero CRITICAL issues from any reviewer
• All Major issues from the original review are resolved
• No new issues introduced by refactoring

If critical issues remain: Return to Task 3 and fix.

Verification: All modified components pass their reviewer.

Task 5: Produce Refactoring Report

Goal: Document what was changed and why.

Write to: .rcc/{timestamp}-refactoring-report.md

Report format:

# Agent System Refactoring Report

**Date:** YYYY-MM-DD HH:MM

## Changes Made

| # | Component | Change | Rationale |
|---|-----------|--------|-----------|

## Before/After Comparison

| Metric | Before | After |
|--------|--------|-------|
| Components | N | N |
| Critical issues | N | 0 |
| Warnings | N | N |
| Total lines (CLAUDE.md) | N | N |

## Remaining Items (INFO)

- [Low priority items for future consideration]

Verification: Report accurately reflects all changes.

Task 6: Archive Pipeline Documents

Goal: Move all pipeline documents from the current run to the archive.

Steps:

1. Create archive directory: .rcc/archive/{YYYY-MM-DD}/
2. Move ALL *.md files from .rcc/ to the archive directory (excluding the archive/ directory itself)
3. Commit the archive move

mkdir -p .rcc/archive/{YYYY-MM-DD}
mv .rcc/*.md .rcc/archive/{YYYY-MM-DD}/
git add .rcc/
git commit -m "chore: archive pipeline documents from {YYYY-MM-DD}"

Replace {YYYY-MM-DD} with today's actual date.

If no documents exist in .rcc/: Skip this task (nothing to archive).

Verification: .rcc/ contains only the archive/ directory. All pipeline documents are in the dated archive subdirectory.

Red Flags - STOP

These thoughts mean you're rationalizing. STOP and reconsider:

• "Skip re-analysis, I just built this"
• "No need to compare, everything is new"
• "Use a subagent to make the edits"
• "Skip final verification, I just fixed it"
• "The report is busywork"
• "Skip archiving, the docs aren't hurting anything"

All of these mean: You're about to leave mess behind. Follow the process.

Common Rationalizations