Safe Refactoring - GitNexus

When to Use This Skill

Use the Refactoring skill when you need to:

Rename a function or class across multiple files
Extract code into a separate module
Split a large service into smaller pieces
Move code to a different file
Restructure packages or modules
Safely modify public APIs

Example Scenarios

Rename this function safely

Use gitnexus_rename with dry_run: true to preview all edits, then apply if satisfied.

Extract this into a module

Use gitnexus_context to see all dependencies, plan the new interface, then extract and update imports.

Split this service

Use gitnexus_context to understand callees, group by responsibility, then use impact to find all callers to update.

Move this to a new file

Use impact to find all dependents, move the code, then update import paths using rename or manually.

Workflow

Follow these steps for safe refactoring:

General Refactoring Principles

Update Order:

Interfaces and types first
Implementations next
Callers after that
Tests last

This ensures you’re always working with valid code.

Workflow: Rename Symbol

Renaming is the most common refactoring task. GitNexus provides automated multi-file rename with confidence scoring.

Step-by-Step Guide

1. Preview the Rename (Dry Run)

gitnexus_rename({
  symbol_name: "validateUser",
  new_name: "authenticateUser",
  dry_run: true
})

Returns:

{
  status: "success",
  files_affected: 8,
  total_edits: 12,
  graph_edits: 10,        // High confidence (from knowledge graph)
  text_search_edits: 2,    // Review carefully (from AST search)
  changes: [
    {
      file_path: "src/auth/validate.ts",
      edits: [
        {
          line: 15,
          old_text: "function validateUser(",
          new_text: "function authenticateUser(",
          confidence: "graph"  // or "ast_search"
        }
      ]
    },
    {
      file_path: "config/auth.json",
      edits: [
        {
          line: 3,
          old_text: '"handler": "validateUser"',
          new_text: '"handler": "authenticateUser"',
          confidence: "ast_search"  // ⚠️ String reference, review!
        }
      ]
    }
  ]
}

2. Review Edits Pay special attention to:

graph edits: High confidence, based on knowledge graph relationships
ast_search edits: Lower confidence, found via text search (might include string refs, comments)

Always review ast_search edits manually. These might include:

String references in config files
Comments or documentation
False positives (different symbol with same name)

3. Apply the Rename If satisfied with the preview:

gitnexus_rename({
  symbol_name: "validateUser",
  new_name: "authenticateUser",
  dry_run: false
})

4. Verify Changes

gitnexus_detect_changes({scope: "all"})

Check that only expected files were modified. 5. Run Tests The detect_changes output shows affected processes—run tests for those:

npm test -- LoginFlow TokenRefresh

Rename Checklist

gitnexus_rename({..., dry_run: true}) to preview all edits
Review graph edits (high confidence)
Carefully review ast_search edits (might include string refs)
If satisfied: gitnexus_rename({..., dry_run: false}) to apply
gitnexus_detect_changes() to verify scope
Run tests for affected processes

Workflow: Extract Module

Extracting code into a separate module requires understanding dependencies.

Step-by-Step Guide

1. Get Full Context

gitnexus_context({name: "processPayment"})

Returns:

{
  incoming: {
    calls: ["checkoutHandler", "webhookHandler"]  // External callers
  },
  outgoing: {
    calls: ["validateCard", "chargeStripe", "saveTransaction"]  // Dependencies
  }
}

2. Map All External Callers

gitnexus_impact({
  target: "processPayment",
  direction: "upstream"
})

These are all the places you’ll need to update imports. 3. Define New Module Interface Based on incoming calls, design your new module’s API:

// payments/processor.ts
export async function processPayment(amount: number): Promise<PaymentResult> {
  // Implementation
}

4. Extract Code

Create new file
Move implementation
Export public interface

5. Update Imports For each caller found in step 2, update the import:

- import { processPayment } from './checkout'
+ import { processPayment } from './payments/processor'

6. Verify with detect_changes

gitnexus_detect_changes({scope: "all"})

Confirm affected scope matches expectations. 7. Run Tests Run tests for all affected processes.

Extract Module Checklist

gitnexus_context({name: target}) to see all dependencies
gitnexus_impact({target, direction: "upstream"}) to find external callers
Define new module interface
Extract code and update imports
gitnexus_detect_changes() to verify scope
Run tests for affected processes

Workflow: Split Function/Service

Splitting a large function or service requires grouping callees by responsibility.

Step-by-Step Guide

1. Understand All Callees

gitnexus_context({name: "handleCheckout"})

Returns:

{
  outgoing: {
    calls: [
      "validateCart",      // Validation concern
      "processPayment",    // Payment concern
      "sendEmail",         // Notification concern
      "updateInventory"    // Inventory concern
    ]
  }
}

2. Group Callees by Responsibility

Validation: validateCart
Payment: processPayment
Notification: sendEmail
Inventory: updateInventory

3. Map Callers to Update

gitnexus_impact({
  target: "handleCheckout",
  direction: "upstream"
})

These are the places that call the monolithic function. 4. Create New Functions/Services

// Before
async function handleCheckout() {
  validateCart();
  processPayment();
  sendEmail();
  updateInventory();
}

// After
async function validateCheckout() {
  return validateCart();
}

async function executeCheckout() {
  await processPayment();
  await updateInventory();
}

async function notifyCheckout() {
  await sendEmail();
}

5. Update Callers For each caller found in step 3, update to use the new functions. 6. Verify and Test Use detect_changes and run tests.

Split Function Checklist

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

Tools for Refactoring

gitnexus_rename

Automated multi-file rename with confidence scoring:

gitnexus_rename({
  symbol_name: "oldName",
  new_name: "newName",
  dry_run: true,           // Preview before applying
  minConfidence: 0.8       // Optional: filter low-confidence edits
})

Returns:

{
  status: "success",
  files_affected: 8,
  total_edits: 12,
  graph_edits: 10,         // From knowledge graph (high confidence)
  text_search_edits: 2,    // From AST search (review carefully)
  changes: [
    {
      file_path: "src/auth/validate.ts",
      edits: [{line, old_text, new_text, confidence}]
    }
  ]
}

Edit Confidence Levels:

graph: Found via knowledge graph relationships (high confidence)
ast_search: Found via text search (lower confidence, might include string refs)

Always run with dry_run: true first to preview changes before applying.

gitnexus_impact

Map all dependents before refactoring:

gitnexus_impact({
  target: "validateUser",
  direction: "upstream"
})

Use this to find all callers you’ll need to update.

gitnexus_detect_changes

Verify refactoring scope:

gitnexus_detect_changes({scope: "all"})

Returns:

{
  summary: {
    changed_count: 8,
    affected_count: 12,
    changed_files: 5,
    risk_level: "medium"
  },
  changed_symbols: [...],
  affected_processes: ["LoginFlow", "TokenRefresh"]
}

Run tests for the affected processes.

gitnexus_cypher

Custom queries for complex refactoring:

// Find all callers across the codebase
MATCH (caller)-[:CodeRelation {type: 'CALLS'}]->(f:Function {name: "validateUser"})
RETURN caller.name, caller.filePath
ORDER BY caller.filePath

Risk Rules

Use these rules to assess refactoring risk:

Risk Factor	Mitigation Strategy
Many callers (>5)	Use `gitnexus_rename` for automated updates
Cross-area refs	Use `detect_changes` after to verify scope
String/dynamic refs	Use `gitnexus_query` to find them, review `ast_search` edits
External/public API	Version and deprecate properly, coordinate with consumers

Example: Rename validateUser to authenticateUser

Here’s a complete refactoring walkthrough:

Step 1: Preview the Rename

gitnexus_rename({
  symbol_name: "validateUser",
  new_name: "authenticateUser",
  dry_run: true
})

Result:

Files affected: 8
Total edits: 12

Breakdown:
  - 10 graph edits (high confidence)
  - 2 ast_search edits (review)

Files:
  ✓ src/auth/validate.ts (definition)
  ✓ src/auth/login.ts (caller)
  ✓ src/api/middleware.ts (caller)
  ⚠ config/auth.json (string reference!)
  ...

Step 2: Review ast_search Edits

Check config/auth.json:

{
  "handler": "validateUser"  // ← String reference found by ast_search
}

This needs to be renamed too—confirms it’s a valid edit.

Step 3: Apply the Rename

gitnexus_rename({
  symbol_name: "validateUser",
  new_name: "authenticateUser",
  dry_run: false
})

Result:

✓ Applied 12 edits across 8 files

Step 4: Verify Changes

gitnexus_detect_changes({scope: "all"})

Result:

Changed: 12 symbols in 8 files
Affected processes: LoginFlow, TokenRefresh
Risk: MEDIUM

Step 5: Run Tests

npm test -- LoginFlow TokenRefresh

All tests pass! Refactoring complete.

Best Practices

Always Dry Run First

Preview changes with dry_run: true before applying any rename.

Review ast_search Edits

These might include string refs in config files—verify each one.

Use detect_changes After

Verify that only expected files changed and run affected tests.

Update in Order

Interfaces → implementations → callers → tests.

Advanced Techniques

Renaming Across Multiple Symbols

If you need to rename a pattern (e.g., all validate* to authenticate*):

Find all matching symbols:

MATCH (f:Function)
WHERE f.name STARTS WITH 'validate'
RETURN f.name

Rename each one with gitnexus_rename
Use detect_changes to verify total scope

Handling External/Public APIs

For public APIs used by external consumers:

Don’t rename immediately—add new function alongside old
Deprecate old function with warnings
Update internal callers to use new function
Remove old function in next major version

// Old (deprecated)
/** @deprecated Use authenticateUser instead */
export function validateUser() {
  return authenticateUser();  // Delegate to new function
}

// New
export function authenticateUser() {
  // Implementation
}

Safe Refactoring Checklist

For any refactoring task:

Understand dependencies with context and impact
Plan update order (interfaces first, tests last)
Preview changes with dry run (for renames)
Make incremental changes
Verify scope with detect_changes
Run tests for affected processes
Commit frequently with clear messages

Common Pitfalls

Not Previewing Renames

Always use dry_run: true first—you might be surprised by string references in config files.

Ignoring ast_search Edits

These are lower confidence but often valid (config files, JSON, etc.). Review each one.

Forgetting Tests

Run tests for affected processes, not just the changed files. Use detect_changes to find them.

Updating Out of Order

Update interfaces before implementations, otherwise you’ll have type errors mid-refactor.

Get Started

Core Concepts

CLI Usage

MCP Integration

Agent Skills

Web UI

Advanced

​When to Use This Skill

​Example Scenarios

​Workflow

​General Refactoring Principles

​Workflow: Rename Symbol

​Step-by-Step Guide

​Rename Checklist

​Workflow: Extract Module

​Step-by-Step Guide

​Extract Module Checklist

​Workflow: Split Function/Service

​Step-by-Step Guide

​Split Function Checklist

​Tools for Refactoring

​gitnexus_rename

​gitnexus_impact

​gitnexus_detect_changes

​gitnexus_cypher

​Risk Rules

​Example: Rename validateUser to authenticateUser

​Step 1: Preview the Rename

​Step 2: Review ast_search Edits

​Step 3: Apply the Rename

​Step 4: Verify Changes

​Step 5: Run Tests

​Best Practices

Always Dry Run First

Review ast_search Edits

Use detect_changes After

Update in Order

​Advanced Techniques

​Renaming Across Multiple Symbols

​Handling External/Public APIs

​Safe Refactoring Checklist

​Common Pitfalls

​Not Previewing Renames

​Ignoring ast_search Edits

​Forgetting Tests

​Updating Out of Order

​Next Steps

Explore Other Skills

MCP Tools Reference

Build docs developers (and LLMs) love

When to Use This Skill

Example Scenarios

Workflow

General Refactoring Principles

Workflow: Rename Symbol

Step-by-Step Guide

Rename Checklist

Workflow: Extract Module

Step-by-Step Guide

Extract Module Checklist

Workflow: Split Function/Service

Step-by-Step Guide

Split Function Checklist

Tools for Refactoring

gitnexus_rename

gitnexus_impact

gitnexus_detect_changes

gitnexus_cypher

Risk Rules

Example: Rename validateUser to authenticateUser

Step 1: Preview the Rename

Step 2: Review ast_search Edits

Step 3: Apply the Rename

Step 4: Verify Changes

Step 5: Run Tests

Best Practices

Advanced Techniques

Renaming Across Multiple Symbols

Handling External/Public APIs

Safe Refactoring Checklist

Common Pitfalls

Not Previewing Renames

Ignoring ast_search Edits

Forgetting Tests

Updating Out of Order

Next Steps