| 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:
- Load review findings
- Prioritize issues
- Execute refactoring
- Final verification
- Produce refactoring report
- 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):
- Read the review report
- Extract all Critical and Major issues
- These are your refactoring targets
If no review report (standalone invocation):
- Invoke
reviewing-agent-systems skill first to produce a report
- 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:
- Critical — must fix before shipping
- Major — should fix for quality
- 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:
- Identify the specific change
- Make the edit
- Verify the fix resolves the issue
- 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:
- Create archive directory:
.rcc/archive/{YYYY-MM-DD}/
- Move ALL
*.md files from .rcc/ to the archive directory (excluding the archive/ directory itself)
- 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. |
