refactoring-agent-systems

name	refactoring-agent-systems
description	Cleans up and consolidates an agent system after creation or modification. Use when user says "cleanup agent system", "refactor agent setup", "clean up skills", "consolidate agents". Use when called by applying-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):

Issue Type	Action	Method
Duplicate logic across components	Merge or extract to rule	Main conversation edits
Conflicting instructions	Unify or remove one	Main conversation edits
Over-engineered component	Simplify (YAGNI)	Main conversation edits
Weak skill trigger	Improve description	Main conversation edits
Missing isolation	Add context: fork to agent	Main conversation edits
CLAUDE.md too long	Move content to rules/skills	Main conversation edits
Skill missing asset	Add scripts/, templates/, or references/	Create directly — no user confirmation needed

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

Excuse	Reality
"Skip re-analysis"	Building introduces new issues. Always re-analyze.
"Skip comparison"	Without before/after, you can't prove improvement.
"Subagent edits"	Subagents can't write to .claude/. Use main conversation.
"Skip verification"	Refactoring can break things. Verify.
"Skip report"	Report documents decisions for future maintainers.
"Skip archiving"	Accumulated documents confuse future pipeline runs. Archive.