config-refactor

What this skill does

# config-refactor

> Applies fixes from `audit-report.md` against the repo configuration. Reads
> `docs/config-guidelines.md` and `audit-report.md` as its spec; never invents rules.

**Triggers**: /config-refactor, apply config fixes, refactor claude config, fix config issues

---

## Process

### Step 0 — Detect execution context

Apply the same detection logic as `config-audit` Step 0 (per Principle 13):

- **Global mode** — CWD is the `claude-config` repo. Fixes apply to repo files only.
- **Project mode** — CWD is another project with a `CLAUDE.md`. Fixes apply to the
  project's own files only. The global layer is read-only — `config-refactor` MUST
  NEVER edit `~/.claude/` or the source repo from project mode.
- **No-config mode** — no `CLAUDE.md` in CWD. Stop and print:
  `No CLAUDE.md found. Nothing to refactor.`

Record the mode and proceed.

### Step 1 — Verify inputs

Required files in the repo root:

- `docs/config-guidelines.md`
- `audit-report.md`

If either is missing → stop. Tell the user to run `/config-audit` first.

If `audit-report.md` is older than 24h or older than the last commit touching `CLAUDE.md`,
`output-styles/`, `skills/`, or `hooks/` → WARNING to the user and ask whether to proceed or
re-run `/config-audit`. STOP and wait for the answer.

### Step 2 — Load and group findings

Parse `audit-report.md`. Group findings by the file they target. Within each file group,
sort by severity (CRITICAL first) then by line number descending (so edits do not shift
later line numbers).

### Step 3 — Present the plan

Show the user a plan grouped by file, in this format:

```
File: <path>
  [CRIT-3] <title>           → <action verb> (e.g. "delete lines 145–308", "rename heading", "move to agents/")
  [WARN-7] <title>           → <action verb>
  ...
File: <path>
  ...
```

End the plan with a one-line summary:

```
Applying <N> fixes across <M> files. CRITICAL: a, WARNING: b, SUGGESTION: c.
Confirm to proceed? (y / n / pick)
```

`y` → apply everything.
`n` → abort, leave repo untouched.
`pick` → user selects specific finding IDs to apply (e.g. "CRIT-1, WARN-3, WARN-5").

STOP and wait for the user's choice.

### Step 4 — Apply fixes

For each confirmed finding, derive the edit from the `fix_hint` plus the principle cited.
Standard fix actions and how to execute them:

| Fix hint pattern | Action |
|------------------|--------|
| "Move scoped section to `agents/`" | Cut the section from `CLAUDE.md`; create `agents/<name>.md` with that content plus a YAML header `--- name: <name> ---`; replace the cut location in `CLAUDE.md` with a one-line reference: "Orchestrator rules live in `agents/<name>.md` — loaded on demand." |
| "Remove manual skill catalog" | Delete the catalog table. Add no replacement. |
| "OS-specific tooling assumed without declaration" | Either prefix the line with the OS marker the user confirms, or delete the line. ASK before choosing. |
| "Engram protocol duplicated…" | Delete the protocol block from `CLAUDE.md`. Replace with a one-line reference: "Engram protocol is injected by the `SessionStart` hook. Repo-specific topic-key conventions follow." Keep only the topic-key list. |
| "Rule duplicated (Principle 3.2)" between `CLAUDE.md` and an output-style | Delete the duplicate from the output-style. The output-style may add a single line: "Behavior rules from `CLAUDE.md` still apply." |
| "Force-read table exceeds 4 entries" | Show the user the current entries and ask which 2–4 to keep. STOP and wait. |
| "Rename to 'Skills — Force-read inline'" | Rename the heading. No other changes. |
| "Force-read entry points to missing file" | Delete the row. |
| Skill format violations | Add the missing frontmatter field or section. If `format` value is missing, default to `procedural` and emit a follow-up SUGGESTION to confirm. |
| File over hard token limit | Identify which section is the largest expendable block (orchestrator content, duplicated engram protocol, decorative philosophy). Propose the cut to the user. STOP and wait for approval. |
| "Dead reference" / "Reference to missing skill" | Remove the reference or update it to a valid path. If user intent is unclear, ASK. |
| "Project CLAUDE.md restates global rule…" (Principle 13) | Delete the duplicated line from the project `CLAUDE.md`. Add no replacement — the global rule already applies. |
| "Project CLAUDE.md contradicts global without override" (Principle 13) | STOP and ask the user: (a) accept the global rule and delete the project line, or (b) declare an explicit `## Overrides global` block with the reason. Never auto-resolve. |
| "Orphan in ~/.claude/" (Principle 12) | STOP and ask the user before deleting anything in `~/.claude/`. Never auto-delete runtime-adjacent files. |

For ambiguous fixes (anything not in the table above), STOP and ask the user before editing.

### Step 5 — Verify

After all edits:

1. Re-read each modified file briefly to confirm syntactic integrity (YAML frontmatter still
   parses, markdown headings still balanced, no orphaned bullet lists).
2. Run a lightweight self-check: for every finding marked as applied, confirm the change
   actually landed in the file.
3. If any verification fails → revert that specific edit and report it as UNAPPLIED in the
   final summary. Do NOT roll back the entire run.

### Step 6 — Report and remind

Print a final summary to the user:

```
Applied: <N> fixes
  - <ID> <title> → <file>
Unapplied: <K> fixes (manual review required)
  - <ID> <reason>
Skipped (user chose not to apply): <S>

Next steps:
  1. Review the diff: git diff
  2. Run install.sh to deploy: bash install.sh
  3. Commit when satisfied
```

Do NOT run `install.sh` automatically. Do NOT commit. Both decisions belong to the user.

If any CRITICAL finding is still unapplied, end the summary with a one-line nudge:
"⚠ <N> CRITICAL finding(s) remain — re-run /config-audit after manual review."

### Step 7 — Save context to engram

Save a `mem_save` entry with:

- title: `Applied config refactor — <date>`
- type: `config`
- topic_key: `config/refactor-history`
- content: structured **What/Why/Where/Learned** summarizing the run.

This is mandatory so future sessions can trace the configuration evolution.

---

## Rules

- Never write to `~/.claude/` directly. Only edit repo files. Remind the user to run
  `install.sh` after.
- Never invent fixes. Every edit must trace back to a finding ID and a principle.
- Never apply fixes the user did not confirm.
- Never commit. Never run `install.sh`. Those are user decisions.
- Never produce a unified mega-rewrite. Apply fixes file by file, finding by finding, so the
  user can pin the source of every change.
- If `audit-report.md` is missing or stale, stop and require re-audit.
- If a fix requires user input (which entries to keep, which OS to declare), STOP and ask —
  never default silently.
- After the run, the repo MUST be in a state where re-running `/config-audit` produces fewer
  findings than before. If it does not, the refactor failed and must be reverted.