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](../../references/task-initialization.md).

**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 |
| Heavy read-only work in main context | Move it to a subagent, or add `context: fork` to the skill | 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:**

```markdown
# 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

```bash
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. |