Use this workflow when you need to change code structure while preserving product behavior. CodeGraph shows the blast radius, compares evidence before and after the edit, and records the decision from the verification results.
Outcome
At the end you should have:
- a named symbol and a recorded base revision;
- a pre-change impact report and read-only audit;
- a small source change made in your normal editor;
- project tests and lint results;
- a refreshed CPG plus post-change review evidence;
- a clear decision to keep, revise, or roll back the change.
A successful command exit confirms that the command ran. Tests, linting, and review results confirm unchanged product behavior.
Prerequisites
- The repository is already imported into CodeGraph.
- The working tree contains only changes you intend to evaluate.
- You know the project test and lint commands.
- You can identify the DuckDB path shown by project information.
The examples below use PowerShell variables so that paths with spaces are handled safely:
$ProjectName = "my-project"
$RepoPath = "D:\src\my-project"
$CpgDb = "D:\codegraph-data\my-project.duckdb"
$BaseRef = "origin/main"
$Symbol = "qualified_symbol_name"
python -m src.cli projects info $ProjectName
Confirm that the reported source and DuckDB paths match the repository you are about to change. Stop if they do not.
1. Record the baseline
Capture the Git revision and current changes using your normal version-control tooling. Then run a deterministic, read-only audit:
python -m src.cli audit --db $CpgDb --source-path $RepoPath --profile ci_fast --format json --skip-llm-conclusion --skip-persistence
The –skip-persistence flag prevents this diagnostic run from updating audit projections. Save the output in your task evidence system if the refactoring is governed; the command does not write a report unless you pass an output option.
2. Bound the impact zone
Analyze the symbol before editing it:
python -m src.cli impact $Symbol --db $CpgDb --max-depth 5 --format json
Review direct_callers, transitive_callers, affected_methods, and impact_score. Treat an empty result as “not resolved”, not automatically “safe”. Check the symbol spelling, project database, language import, and CPG freshness before continuing.
Stop and split the work if the result crosses an ownership boundary, public API, persistence schema, authorization path, or release-critical entry point that is outside the approved task.
3. Make one bounded change
Edit the code in your normal editor. Keep behavior-preserving changes separate from feature work. Do not combine a rename, dependency upgrade, API change, and algorithm change in one refactoring slice.
Run the project’s focused tests and lint immediately. If either fails, restore the known-good version through your normal version-control workflow or correct the smallest failing slice before continuing.
4. Refresh the graph
The impact report is based on the imported CPG. Refresh it after the source change:
python -m src.cli cpg --path $RepoPath --output $CpgDb
Use the exact database reported for this project. If your installation manages imports through another approved pipeline, run that pipeline instead and verify the resulting project information before reusing the reports.
5. Review the changed slice
Run the unified review against the recorded base:
python -m src.cli review --db $CpgDb --base-ref $BaseRef --format markdown
Then repeat the impact analysis:
python -m src.cli impact $Symbol --db $CpgDb --max-depth 5 --format json
The second result should explain the intended structural change without introducing unexpected callers, security findings, or unrelated files. Re-run the read-only audit when the refactoring can affect project-wide quality metrics.
Decision table
| Evidence | Decision |
|---|---|
| Focused tests and lint pass; impact remains within the approved scope; review has no unresolved high-risk finding | Keep the slice and attach the evidence |
| Symbol is unresolved or the CPG is stale | Refresh or correct project context, then rerun |
| New callers, public surfaces, or security-sensitive paths appear | Stop and request a broader review |
| Behavior changes or acceptance criteria need revision | Reclassify the work as a product change |
| Tests, lint, or review fail | Revise the smallest slice or roll back through version control |
Evidence checklist
Record the project name, source revision, base ref, CPG identity, exact commands, exit codes, relevant report fields, test results, and the final human decision. For governed delivery, command output joins the acceptance evidence with requirements, QA, review, AppSec, and financial closure.
Troubleshooting
- “impact analysis requires explicit –db”: pass the DuckDB path from projects info.
- No callers for a known symbol: verify the qualified name and refresh the CPG.
- Review shows unrelated files: use the correct base ref and clean the task scope.
- Audit updates operational state: rerun with –skip-persistence.
- Results differ between runs: verify source revision, database path, import freshness, and configuration before comparing them.
Current source contracts
- src/cli/analysis_commands/audit_commands.py
- src/cli/analysis_commands/review_command.py
- src/cli/analysis_commands/impact_commands.py
- src/cli/domain_suite/gocpg_commands.py
See also Project import, Code review, and Scenario 09: Code review.