fearovex/config-refactor

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.