refactor
The refactor skill detects configuration changes between config.yaml and the original derivation.md, then plans and executes vault restructuring across all affected artifacts including folder organization, MOC templates, context sections, and dimension-dependent skills. Use it when vault dimensions change to ensure configuration, directory structure, and documentation stay synchronized and prevent drift across interconnected systems.
git clone --depth 1 https://github.com/agenticnotetaking/arscontexta /tmp/refactor && cp -r /tmp/refactor/skill-sources/refactor ~/.claude/skills/refactorSKILL.md
## 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
- Use `vocabulary.notes` for the notes folder name
- Use `vocabulary.note` / `vocabulary.note_plural` for note type references
- Use `vocabulary.topic_map` / `vocabulary.topic_map_plural` for MOC references
- Use `vocabulary.inbox` for the inbox folder name
2. **`ops/config.yaml`** — current live configuration (the "after" state)
3. **`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.yamlProactive methodology guidance agent. Monitors note creation and provides real-time quality advice. Suggests connections, flags quality issues, recommends MOC updates. Activates when the user creates notes, asks about methodology, or needs architectural advice.
Interactive knowledge graph analysis. Routes natural language questions to graph scripts, interprets results in domain vocabulary, and suggests concrete actions. Triggers on "/graph", "/graph health", "/graph triangles", "find synthesis opportunities", "graph analysis".
Research a topic and grow your knowledge graph. Uses Exa deep researcher, web search, or basic search to investigate topics, files results with full provenance, and chains to processing pipeline. Triggers on "/learn", "/learn [topic]", "research this", "find out about".
Surface the most valuable next action by combining task stack, queue state, inbox pressure, health, and goals. Recommends one specific action with rationale. Triggers on "/next", "what should I do", "what's next".
End-to-end source processing -- seed, reduce, process all claims through reflect/reweave/verify, archive. The full pipeline in one command. Triggers on "/pipeline", "/pipeline [file]", "process this end to end", "full pipeline".
Queue processing with fresh context per phase. Processes N tasks from the queue, spawning isolated subagents to prevent context contamination. Supports serial, parallel, batch filter, and dry run modes. Triggers on "/ralph", "/ralph N", "process queue", "run pipeline tasks".
Extract structured knowledge from source material. Comprehensive extraction is the default — every insight that serves the domain gets extracted. For domain-relevant sources, skip rate must be below 10%. Zero extraction from a domain-relevant source is a BUG. Triggers on "/reduce", "/reduce [file]", "extract insights", "mine this", "process this".
Find connections between notes and update MOCs. Requires semantic judgment to identify genuine relationships. Use after /reduce creates notes, when exploring connections, or when a topic needs synthesis. Triggers on "/reflect", "/reflect [note]", "find connections", "update MOCs", "connect these notes".