Gitnexus Refactoring
Rename, extract, or move code with GitNexus impact maps, dry-run renames, and change detection before you break callers.
Overview
GitNexus Refactoring is an agent skill most often used in Build (also Ship review) that plans safe renames and extractions using GitNexus impact, context, and dry-run rename APIs.
Install
npx skills add https://github.com/abhigyanpatwari/gitnexus --skill gitnexus-refactoringWhat is this skill?
- Standard workflow: gitnexus_impact upstream → query flows → context → ordered update plan.
- Rename checklist with dry_run rename preview before applying graph and ast_search edits.
- Extract-module flow starts from gitnexus_context and upstream impact on external callers.
- Post-change gitnexus_detect_changes verifies only expected files moved.
- Stale index recovery: run npx gitnexus analyze when the tool reports an outdated graph.
- 4-step core workflow: impact → query → context → plan update order
- Rename checklist: dry_run rename before apply, then detect_changes
Adoption & trust: 811 installs on skills.sh; 41.7k GitHub stars; 1/3 security scanners passed (skills.sh audits).
What problem does it solve?
You want to rename or extract code but fear missing callers, tests, and cross-file references across a large repo.
Who is it for?
Solo developers on multi-file codebases who already use or can index GitNexus and need agent-driven structural refactors.
Skip if: Tiny single-file scripts with no graph index, or cosmetic edits that do not require cross-reference analysis.
When should I use this skill?
User wants to rename, extract, split, move, or restructure code safely (e.g. rename this function, extract into a module, refactor this class, move to separate file).
What do I get? / Deliverables
You apply refactors in dependency-safe order with dry-run previews, applied renames, and change detection—then run tests on affected processes.
- Dry-run and applied rename/edit set
- Updated module boundaries and file layout
- detect_changes verification report
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Refactoring is most common while implementing and reshaping backend and shared modules during Build. Backend subphase captures service splits, module extraction, and file moves that affect many dependents.
Where it fits
Extract a payment service into its own module after gitnexus_impact lists all upstream HTTP handlers.
Rename a public API symbol with dry_run preview so review comments reference a complete edit set.
Split a hot-path file post-incident once context maps show which monitors import the old module.
How it compares
Skill workflow around GitNexus graph tools—not a substitute for IDE rename when you have no index and no impact analysis.
Common Questions / FAQ
Who is gitnexus-refactoring for?
Indie builders and small teams using AI agents with GitNexus to perform safe renames, extractions, and file moves on real repositories.
When should I use gitnexus-refactoring?
During Build when splitting services or extracting modules; during Ship review prep when renaming public APIs; whenever the user says rename this function, extract into a module, or move to a separate file.
Is gitnexus-refactoring safe to install?
Refactors can touch many files via gitnexus_rename; review the Security Audits panel on this page, use dry_run first, and keep git credentials and repo backups under your control.
SKILL.md
READMESKILL.md - Gitnexus Refactoring
# Refactoring with GitNexus ## 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 "Index is stale" → run `npx gitnexus analyze` in terminal. ## 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: