refactor

Runtime Configuration (Step 0 — before any processing)

Read these files to configure domain-specific behavior:

1. ops/derivation-manifest.md — vocabulary mapping, dimension positions, platform hints
2. Use vocabulary.notes for the notes folder name
3. Use vocabulary.note / vocabulary.note_plural for note type references
4. Use vocabulary.topic_map / vocabulary.topic_map_plural for MOC references
5. Use vocabulary.inbox for the inbox folder name

1. ops/config.yaml — current live configuration (the "after" state)

1. ops/derivation.md — original derivation record (the "before" state)

If these files don't exist, report error: "Cannot refactor without both ops/config.yaml and ops/derivation.md. These files establish the baseline and current configuration."

EXECUTE NOW

INVARIANT: /refactor never executes without approval. The plan is always shown first.

Target: $ARGUMENTS

Parse immediately:

• If target is empty: detect ALL config changes and plan restructuring
• If target names a specific dimension (e.g., "granularity", "organization"): focus on that dimension only
• If target is --dry-run: show plan without asking for approval

Execute these phases:

1. Detect changes between config.yaml and derivation.md
2. Plan restructuring for each changed dimension
3. Show the plan with affected artifacts and risk assessment
4. Execute on approval (unless --dry-run)
5. Validate post-restructuring

START NOW. Reference below defines the workflow.

Philosophy

Configuration changes cascade.

Changing a dimension is not just editing a value in config.yaml. Each dimension affects multiple artifacts — skills, templates, context file sections, hooks, MOC structure. Changing organization from "flat" to "hierarchical" means restructuring the notes directory, updating MOC templates, adjusting navigation references in the context file, and regenerating skills that reference folder structure.

/refactor makes these cascades visible and manages them. Without it, dimension changes create drift: config says one thing, artifacts say another. With it, every change is planned, approved, and validated.

The relationship to /architect: /architect RECOMMENDS changes. /refactor IMPLEMENTS them. /architect analyzes health and friction to propose dimension shifts. When those proposals are approved, /refactor ensures every affected artifact is updated consistently.

Phase 1: Detect Changes

Compare each dimension in ops/config.yaml against the same dimension in ops/derivation.md:

Step 1: Read both files

Read ops/config.yaml and ops/derivation.md fully. Extract the position for each of the 8 dimensions from both.

Step 2: Build comparison table

| Dimension | Derivation Value | Config Value | Changed? | Drift Type | |-----------|-----------------|--------------|----------|------------| | granularity | [val] | [val] | [yes/no] | [aligned/misaligned] | | organization | [val] | [val] | [yes/no] | [aligned/misaligned] | | linking | [val] | [val] | [yes/no] | [aligned/misaligned] | | processing | [val] | [val] | [yes/no] | [aligned/misaligned] | | navigation | [val] | [val] | [yes/no] | [aligned/misaligned] | | maintenance | [val] | [val] | [yes/no] | [aligned/misaligned] | | schema | [val] | [val] | [yes/no] | [aligned/misaligned] | | automation | [val] | [val] | [yes/no] | [aligned/misaligned] |

Step 3: Check feature flags

Also compare feature flags between derivation and config:

| Feature | Derivation | Config | Changed? | |---------|-----------|--------|----------| | semantic_search | [on/off] | [on/off] | [yes/no] | | processing_pipeline | [on/off] | [on/off] | [yes/no] | | self_space | [on/off] | [on/off] | [yes/no] | | session_capture | [on/off] | [on/off] | [yes/no] | | parallel_workers | [on/off] | [on/off] | [yes/no] |

Step 4: Early exit if no changes

If no changes detected:

--=={ refactor }==--

  No configuration drift detected between config.yaml and derivation.md.
  All dimensions and features match the original derivation.

  If you want to explore changes, run /architect for recommendations
  or edit ops/config.yaml directly, then run /refactor again.

Phase 2: Plan Restructuring

For each changed dimension, determine ALL affected artifacts. This is the cascade analysis.

Dimension-to-Artifact Mapping

| Change | Affected Artifacts | What Changes | |--------|-------------------|-------------| | Granularity shift | Note templates, extraction depth in /reduce, processing skills, context file "Note Design" section | Template body length guidance, extraction granularity settings, composability test thresholds | | Organization shift | Folder structure, MOC hierarchy, context file "Folder Architecture" section, hub MOC | Directory layout, MOC tier count, navigation references | | Linking shift | Semantic search config, /reflect connection density expectations, context file "Connection Finding" section | Search tool availability, link threshold values, discovery layer instructions | | Processing shift | /reduce depth settings, /reflect pass count, pipeline skills, context file "Processing Pipeline" section, config.yaml processing.depth | Extraction thoroughness, connection evaluation depth, chaining mode | | Navigation shift | MOC tier structure, hub MOC, context file "MOC" section, note Topics footers | Number of MOC tiers, hub content, navigation instructions | | Maintenance shift | /health threshold values, condition-based trigger settings, context file maintenance instructions | Check frequency conditions, stale note thresholds, reweave trigger conditions | | Schema shift | Templates (_schema blocks), validation rules, /validate skill, query scripts, context file "YAML" section | Required fields, enum values, validation patterns | | Automation shift | Hooks (session orient, write validation, inbox processing), skill activation, config.yaml automation section | Which hooks are active, automation level references |

Artifact Analysis Format

For each affected artifact, specify:

Artifact: [file path]
  Section: [specific section within the file, if applicable]
  Current: [what it says now — quote relevant content]
  Proposed: [what it should say after refactoring]
  Risk: [low | medium | high]
  Reversible: [yes | no — with explanation]
  Content impact: [does this affect existing notes? how many?]

Content Impact Assessment

Some changes affect only infrastructure (skills, templates, context file). Others affect existing content (notes, MOCs):

| Change Type | Content Impact | Action Required | |-------------|---------------|----------------| | Template field addition | New notes get field, old notes don't | Add field to old notes (schema migration) | | Template field removal | Old notes have unused field | Remove field from old notes (optional) | | Folder restructure | Notes must move | Move files, update all wiki links | | MOC tier change | MOC hierarchy restructured | Merge/split MOCs, update Topics footers | | Enum value change | Old notes have invalid values | Update values in affected notes |

For content-impacting changes:

• Count affected notes: grep -rl '[old value]' {vocabulary.notes}/*.md | wc -l
• List specific files that need updating
• Estimate time for content migration

Interaction Constraint Check

Read ${CLAUDE_PLUGIN_ROOT}/reference/interaction-constraints.md and check:

1. Hard blocks: Would the new configuration create a combination that WILL fail?
2. Example: atomic granularity + 2-tier navigation at high volume
3. If a hard block is detected: WARN the user and recommend against the change

1. Soft warns: What friction points does the new configuration create?
2. Example: dense schema + convention-level automation (manual schema enforcement is tedious)
3. If soft warns exist: note them in the plan with compensating mechanisms

1. **Cascade ef