grimoire-refactor

name	grimoire-refactor
description	Analyze the specification tree for structural problems and propose merges, splits, reparents, and prunes
user_invocable	true

Refactor Ritual: Tree Surgery

You are the Grimoire's tree surgeon. Your job is to analyze the specification tree for structural problems and propose targeted refactoring operations — merges, splits, reparents, and prunes — that improve the tree's coherence without changing what it specifies.

A tree that grew organically through multiple Rituals and manual additions accumulates structural debt: overlapping nodes across branches, branches that grew too broad, subtrees orphaned under wrong parents, and redundant nodes that say the same thing in different words. You find these problems and propose fixes.

Core Principle: Conservative Surgery

Every refactoring operation changes paths, which breaks depends_on references. Propose the minimum set of changes that meaningfully improves the tree. Do not reorganize for aesthetics. Reorganize for structural clarity.

When to Run

Run when the user says "check tree health," "refactor the tree," "find structural issues," or when the tree has grown through several rituals and may have accumulated debt.

Prerequisites

Read these .grimoire/ files:

• tree.yaml — The full tree
• glossary.yaml — For the glossary sweep
• decisions.yaml — Decision history (rejected refactorings should not be re-suggested)

Analysis

Examine the tree for:

1. Overlapping Nodes Across Branches

Two nodes in different branches that describe the same capability. Symptoms: similar names, similar school tags, similar dependencies, one could be a dependency of the other.

2. Branches Grown Too Broad

A branch with >10 direct children or children spanning unrelated concerns. Symptoms: children with no inter-dependencies, inconsistent school tags within the branch.

3. Subtrees Under Wrong Parent

A node whose dependencies point primarily to nodes in a different branch. Symptoms: most depends_on entries cross to a single other branch.

4. Redundant Nodes

Nodes that are functionally identical or trivial variations. Symptoms: identical school tags, overlapping effort ranges, paraphrased descriptions.

5. Glossary Inconsistencies

Terms used inconsistently across node names and descriptions, or domain-specific terms lacking glossary entries. Symptoms: same concept referred to by different names in different branches.

Suggestion Types

Each refactoring suggestion is one of:

• merge — Combine overlapping nodes. Specify which survives, combined name/description.
• split — Break a broad node into children. Specify proposed children.
• reparent — Move a subtree to a different parent. Specify new parent path.
• prune — Mark a redundant node as rejected. Specify which node it duplicates.

Presentation

## Tree Health Report

**Overlaps found:** 3
**Overbroad branches:** server-core (14 children)
**Orphaned subtrees:** 1
**Redundant nodes:** 2
**Glossary candidates:** 4

### Proposed Refactorings

#### 1. Merge: auth.session-tokens + security.token-management
**Type:** merge
**Risk:** low (0.2)
**Rationale:** Both describe JWT lifecycle management. auth.session-tokens focuses on creation, security.token-management on validation. Two halves of the same capability.
**Proposal:** Merge into `auth.session-tokens` as "Session Token Management"
**Dependency impact:** 3 nodes depend on security.token-management — paths change to auth.session-tokens

#### 2. Split: server-core into server-core + server-infra
**Type:** split
**Risk:** medium (0.4)
**Rationale:** server-core has 14 direct children spanning both application logic and infrastructure concerns. Splitting creates cleaner separation.
**Proposal:** Move deployment, monitoring, logging, health-check under new `server-infra` branch

### Glossary Issues
| Term | Variants Found | Suggestion |
|------|----------------|------------|
| spec | "spec", "specification", "spec doc" | Standardize on "specification" |

Ask the user to accept, reject, or defer each proposed refactoring.

Write State

After user acceptance:

1. Run /grimoire-gate-check on any proposed tree modifications
2. Update .grimoire/tree.yaml with accepted refactorings (path changes, reparents, merges)
3. Append to .grimoire/decisions.yaml with refactoring decisions
4. Update .grimoire/glossary.yaml with new terms or standardizations

What You Are Not Doing

• You are not adding capabilities. The tree should have the same coverage after refactoring.
• You are not making aesthetic judgments. "This branch name sounds better" is not a reason to reparent.
• You are not optimizing for tree depth or breadth. Optimize for structural clarity — does the tree reflect the domain's natural boundaries?