ALWAYS invoke this skill when moving nodes, re-scoping content, or extracting shared enablers. NEVER restructure the spec tree without this skill.
From spec-treenpx claudepluginhub outcomeeng/claude --plugin spec-treeThis skill is limited to using the following tools:
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Compares coding agents like Claude Code and Aider on custom YAML-defined codebase tasks using git worktrees, measuring pass rate, cost, time, and consistency.
Apply structural changes to the Spec Tree: move nodes between parents, re-scope content across nodes, extract shared enablers, and consolidate nodes. Analyzes impact, applies changes, and reports what was modified.
</objective><quick_start>
PREREQUISITE: Check for <SPEC_TREE_FOUNDATION> marker. If absent, invoke /understanding first.
References from the understanding skill (${SKILL_DIR}/../understanding/):
${SKILL_DIR}/../understanding/references/decomposition-semantics.md — enabler extraction, cross-cutting assertions${SKILL_DIR}/../understanding/references/ordering-rules.md — index assignment, dependency encoding${SKILL_DIR}/../understanding/references/what-goes-where.md — content taxonomy (what belongs where)${SKILL_DIR}/../understanding/references/node-types.md — enabler vs outcome</quick_start>
<operations>This skill handles four structural operations:
| Operation | Input | Output |
|---|---|---|
| Move | Node + new parent | Node relocated, paths updated |
| Re-scope | Two+ nodes + assertions to move | Assertions redistributed, specs updated |
| Extract enabler | Two+ nodes sharing infrastructure | New enabler at lower index, dependents updated |
| Consolidate | Two+ nodes to merge | Single node with combined content, old nodes removed |
Step 1: Identify the operation
Determine which operation from the user's request:
If the request is ambiguous, ask.
</step> <step name="context">Step 2: Load context
Invoke /contextualizing for each node involved in the operation. This loads:
Step 3: Analyze impact
Before applying changes, determine what will be affected:
For Move:
tests/ directory?For Re-scope:
tests/ directory)?For Extract enabler:
For Consolidate:
Step 4a: Apply — Move
tests/ directory and all test files.Index assignment: Use ordering rules from ${SKILL_DIR}/../understanding/references/ordering-rules.md. If inserting between existing siblings, use the midpoint.
Step 4b: Apply — Re-scope
tests/ to target tests/.Step 4c: Apply — Extract enabler
{NN}-{slug}.enabler/${SKILL_DIR}/../understanding/templates/nodes/enabler-name.md.tests/ directory.tests/.Step 4d: Apply — Consolidate
tests/ into the surviving node's tests/.Step 5: Validate
After applying any operation:
([test](...)) in affected specs resolves to an existing filetests/ directories is linked from an assertion${SKILL_DIR}/../understanding/references/what-goes-where.md)Step 6: Report
Summarize what changed:
Refactoring: {operation type}
Files created:
- {path}
Files modified:
- {path}: {what changed}
Files moved:
- {old path} → {new path}
Files removed:
- {path}
Assertions redistributed: {count}
Test files moved: {count}
Cross-cutting links updated: {count}
If the refactoring revealed further issues (nodes with too many assertions, orphaned enablers, scope ambiguity), note them as recommended follow-ups.
</step> </workflow><failure_modes>
Failure 1: ADR scope silently lost after move
Agent moved a node from directory A to directory B. Directory A contained an ADR at index 15 that governed the moved node. After the move, the node was no longer a descendant of that ADR's scope — the architectural constraint silently disappeared. Tests continued to pass because they tested behavior, not ADR compliance.
How to avoid: In the impact analysis step, glob for all ADRs/PDRs in the source ancestry. For each one, check whether the constraint still applies at the destination. If it does, either the ADR needs to move too or a new ADR must be created at the destination's scope.
Failure 2: Test links broken after move, not caught
Agent moved a node and its tests/ directory but didn't update the assertion test links in ancestor specs that referenced ([test](old-path/tests/...)). The assertions still claimed coverage, but the links pointed to nonexistent files.
How to avoid: After any move, grep the entire spx/ tree for the old path. Every match is a broken reference that must be updated. The validation step checks "every ([test](...)) resolves to an existing file" — run it.
Failure 3: Consolidated nodes with different hypotheses
Agent merged two "parsing" outcomes because they sounded similar. One parsed user input for validation; the other parsed API responses for data extraction. Different hypotheses, different users, different failure modes. The merged node's hypothesis became a vague compromise that fit neither concern well.
How to avoid: Before consolidating, compare the hypotheses (for outcomes) or enables statements (for enablers). If they serve different users or have different "outcome" components in the three-part hypothesis, they are distinct nodes regardless of implementation similarity.
Failure 4: Used mv instead of git mv for tracked files
Agent used Bash mv to relocate a node directory. Git saw this as a deletion plus an unrelated new file. The file's history was lost, and git blame showed the move as the original author of all lines.
How to avoid: Always use git mv for files tracked by git. This preserves rename detection and history. Check git status first — if the file shows as tracked, use git mv.
Failure 5: Temporal language introduced during re-scope
Agent moved assertions between nodes and rewrote the source node's hypothesis to explain what happened: "After extracting the validation concerns into the sibling node, this outcome focuses on data transformation." This narrates a refactoring history — it's temporal. The atemporal version: "This outcome transforms raw input into normalized records."
How to avoid: When rewriting specs after structural changes, treat the rewrite as if the spec was always this way. The spec tree is a durable map — it states product truth, not a changelog. Apply the read-aloud test: if the sentence would sound strange to someone who never saw the old structure, it's temporal.
</failure_modes>
<anti_patterns>
Moving without checking ADR/PDR scope. A node governed by an ADR at index 15 in directory A is no longer governed by that ADR if moved to directory B. The constraint silently disappears.
Consolidating similar but distinct nodes. Two nodes about "parsing" may parse different things for different reasons. If they have different hypotheses, they're different outcomes — similarity in implementation doesn't mean similarity in purpose.
Extracting enablers for single dependents. An enabler with only one dependent is not an enabler — it's an internal concern of that dependent. Extract only when 2+ siblings share the need.
Leaving empty nodes after re-scope. If you move all assertions out of a node, the node is now empty. Either remove it or consolidate it — don't leave a spec with no assertions.
</anti_patterns>
<success_criteria>
Refactoring is complete when:
</success_criteria>