Dhpk Gitnexus Refactoring

---
name: dhpk-gitnexus-refactoring
description: 'Safely rename, extract, split, move, or restructure code using the GitNexus graph + coordinated rename. Use when: renaming a symbol across files, extracting a module, splitting a function/service, moving code. Not for: understanding code (use dhpk-gitnexus-exploring), pre-change risk only (use dhpk-gitnexus-impact-analysis), bug tracing (use dhpk-gitnexus-debugging). Output: an ordered refactor plan + verified multi-file edits.'
metadata:
  dhpk-invocation-class: implicit-eligible
---

# Refactoring with GitNexus

The schema, tool names, resource catalog, and stale-index recovery are owned by
`dhpk-gitnexus-guide`; this skill owns the ordered refactor workflow.

## When to Use

- "Rename this function safely"
- "Extract this into a module"
- "Split this service"
- "Move this to a new file"
- Any task involving renaming, extracting, splitting, or restructuring code

## Workflow

```
1. gitnexus_impact({target: "X", direction: "upstream"})  → Map all dependents
2. gitnexus_query({query: "X"})                            → Find execution flows involving X
3. gitnexus_context({name: "X"})                           → See all incoming/outgoing refs
4. Plan update order: interfaces → implementations → callers → tests
```

> If the context reports a stale index, follow `dhpk-gitnexus-guide` for the
> single stale-index recovery path before continuing this workflow.

## Checklists

### Rename Symbol

```
- [ ] gitnexus_rename({symbol_name: "oldName", new_name: "newName", dry_run: true}) — preview all edits
- [ ] Review graph edits (high confidence) and ast_search edits (review carefully)
- [ ] If satisfied: gitnexus_rename({..., dry_run: false}) — apply edits
- [ ] gitnexus_detect_changes() — verify only expected files changed
- [ ] Run tests for affected processes
```

### Extract Module

```
- [ ] gitnexus_context({name: target}) — see all incoming/outgoing refs
- [ ] gitnexus_impact({target, direction: "upstream"}) — find all external callers
- [ ] Define new module interface
- [ ] Extract code, update imports
- [ ] gitnexus_detect_changes() — verify affected scope
- [ ] Run tests for affected processes
```

### Split Function/Service

```
- [ ] gitnexus_context({name: target}) — understand all callees
- [ ] Group callees by responsibility
- [ ] gitnexus_impact({target, direction: "upstream"}) — map callers to update
- [ ] Create new functions/services
- [ ] Update callers
- [ ] gitnexus_detect_changes() — verify affected scope
- [ ] Run tests for affected processes
```

## Tools

**gitnexus_rename** — automated multi-file rename:

```
gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
→ 12 edits across 8 files
→ 10 graph edits (high confidence), 2 ast_search edits (review)
→ Changes: [{file_path, edits: [{line, old_text, new_text, confidence}]}]
```

**gitnexus_impact** — map all dependents first:

```
gitnexus_impact({target: "validateUser", direction: "upstream"})
→ d=1: loginHandler, apiMiddleware, testUtils
→ Affected Processes: LoginFlow, TokenRefresh
```

**gitnexus_detect_changes** — verify your changes after refactoring:

```
gitnexus_detect_changes({scope: "all"})
→ Changed: 8 files, 12 symbols
→ Affected processes: LoginFlow, TokenRefresh
→ Risk: MEDIUM
```

**gitnexus_cypher** — custom reference queries:

```cypher
MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
RETURN caller.name, caller.filePath ORDER BY caller.filePath
```

## Risk Rules

| Risk Factor         | Mitigation                                |
| ------------------- | ----------------------------------------- |
| Many callers (>5)   | Use gitnexus_rename for automated updates |
| Cross-area refs     | Use detect_changes after to verify scope  |
| String/dynamic refs | gitnexus_query to find them               |
| External/public API | Version and deprecate properly            |

## Example: Rename `validateUser` to `authenticateUser`

```
1. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: true})
   → 12 edits: 10 graph (safe), 2 ast_search (review)
   → Files: validator.ts, login.ts, middleware.ts, config.json...

2. Review ast_search edits (config.json: dynamic reference!)

3. gitnexus_rename({symbol_name: "validateUser", new_name: "authenticateUser", dry_run: false})
   → Applied 12 edits across 8 files

4. gitnexus_detect_changes({scope: "all"})
   → Affected: LoginFlow, TokenRefresh
   → Risk: MEDIUM — run tests for these flows
```

## When NOT to Use

- You only need to understand the code, not change it → `dhpk-gitnexus-exploring`
- You only need the blast radius / risk, not the edit → `dhpk-gitnexus-impact-analysis`
- You are chasing a bug → `dhpk-gitnexus-debugging`

## Output

An ordered refactor plan (interfaces → implementations → callers → tests), the verified multi-file edits (dry-run reviewed before apply), and a post-change `detect_changes` scope confirmation.

## Verification

- [ ] Upstream impact was checked before editing the symbol.
- [ ] The dry-run rename or edit set was reviewed for dynamic and external references.
- [ ] Interfaces, implementations, callers, and tests were updated in dependency order.
- [ ] Focused tests for affected flows pass.
- [ ] `gitnexus_detect_changes` shows only the intended symbols and execution flows.