SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsconfig-refactor

config-refactor

Coding & development

View repository

Updated 10-15 21:41

About this skill

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

Locate the guidelines spec by mode (per Step 0, mirroring config-audit Step 1):

  • Global mode — read docs/config-guidelines.md from CWD root.
  • Project mode — read ~/.claude/docs/config-guidelines.md (the deployed global spec). The project has no local copy by design; never require one.

If the guidelines file is missing in the resolved location → stop. In global mode, the spec is absent from the repo. In project mode, run install.sh from the claude-config repo on this machine to deploy it.

audit-report.md is required at the CWD root in BOTH modes (config-audit writes it there). If it is MISSING → do NOT stop. Auto-run config-audit first (invoke the config-audit skill in the same CWD/mode), let it write audit-report.md, then continue to Step 2. Tell the user: "No audit-report.md found — running /config-audit first, then applying fixes." This makes config-refactor self-sufficient: one invocation runs the full audit→refactor chain.

If audit-report.md EXISTS but is older than 24h or older than the last commit touching CLAUDE.md, output-styles/, skills/, or hooks/ → it is STALE. Re-run config-audit to regenerate it (same auto-run as above), then continue. Do not apply fixes from a stale report.

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

Source resolution (Principle 14) — resolve WHERE the edit lands before applying it. Root CLAUDE.md, AGENTS.md, GEMINI.md are build products: editing them directly is reverted on the next install.sh. In Global mode (the claude-config repo), every fix targeting root CLAUDE.md MUST instead edit the source fragment it is assembled from — core/instructions/*, core/methodology/*, or adapters/claude-code/claude.sections-*.md (locate the owning fragment by grep-ing the target text across those sources). For a skill: a SKILL.md containing an ASSEMBLY:BEGIN marker is spliced → edit core/skills/<x>/logic.md; no marker → edit skills/<x>/SKILL.md in place. In Project mode, the project's own CLAUDE.md is a real source file — edit it directly.

For each confirmed finding, derive the edit from the fix_hint plus the principle cited. Standard fix actions and how to execute them (paths below resolve per the rule above):

Fix hint pattern Action
"Move scoped section to agents/" Cut the section from its source fragment (resolve per Principle 14, not root CLAUDE.md in Global mode); create agents/<name>.md with that content plus a YAML header --- name: <name> ---; replace the cut location in the source fragment with a one-line reference: "Orchestrator rules live in agents/<name>.md — loaded on demand."
"Remove manual skill catalog" Delete the catalog table from its source fragment. 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 its source fragment (resolve per Principle 14). 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: "⚠ 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, auto-run config-audit to (re)generate it (Step 1), then proceed — never dead-end on the user.
  • 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.