# Code Change Guardian

> Analyze the blast radius of proposed or existing code changes, plan and execute behavior-preserving refactors, and prove whether changes are safe with repository evidence. Use when Codex needs to assess what could break before editing, safely refactor complex code, review a working-tree diff or pull request for regressions, map dependencies and implicit contracts, create characterization tests, plan rollback, or produce a native Markdown CODE-CHANGE-REPORT.md that opens directly in Codex.

- Skill: `kappaemme-git/code-change-guardian` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add kappaemme-git/code-change-guardian`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kappaemme-git/code-change-guardian/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: kappaemme-git (https://skillmd.com/u/kappaemme-git)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kappaemme-git/code-change-guardian

---


# Code Change Guardian

Protect a code change from proposal through proof. Lead with a native Markdown report, distinguish evidence from inference, and never claim safety without verification.

## Select a mode

- **impact**: Analyze a proposed change without editing project files. Use this by default when the user asks what could break or says not to change code.
- **refactor**: Analyze, request approval, capture baseline behavior, edit incrementally, and verify behavior preservation.
- **verify**: Inspect an existing diff, branch, commit, or pull request and determine what it may break. Do not rewrite it unless asked.

If the request is ambiguous, start in `impact` mode. State the selected mode in the report.

## Create the report first

Create `CODE-CHANGE-REPORT.md` in the repository root, unless the user specifies another path. Write the report in English. Keep updating the same file throughout the task so it remains the single source of truth inside Codex.

Use `scripts/collect_change_context.mjs` for the initial repository snapshot when Node.js is available:

```bash
node <skill-dir>/scripts/collect_change_context.mjs \
  --root <repository-root> \
  --mode impact \
  --request "<requested change>" \
  --out .codex/change-guardian/context.json
```

Read [analysis-playbook.md](references/analysis-playbook.md) before tracing impact. Read [risk-model.md](references/risk-model.md) before scoring risks. Populate a report model following [report-schema.md](references/report-schema.md), then render it:

```bash
node <skill-dir>/scripts/generate_report.mjs \
  --input .codex/change-guardian/report.json \
  --out CODE-CHANGE-REPORT.md
```

Do not wait until the end to create the report. A partial, clearly labeled report is preferable to an invisible analysis.

## Phase 1: Establish scope and baseline

1. Resolve the repository root and inspect local instructions.
2. Record the requested outcome, explicit non-goals, selected mode, current branch, HEAD, and dirty working-tree files.
3. Preserve unrelated user changes. Never discard or overwrite them.
4. Discover relevant validation commands from package manifests, CI configuration, build files, and repository docs.
5. Run only proportionate read-only baseline checks. Record exact commands, results, duration when available, and skipped checks with reasons.

## Phase 2: Map the blast radius

Start from the requested symbol, file, endpoint, schema, dependency, or current diff. Trace outward using repository-native tools and `rg`:

1. Identify definitions, imports, exports, callers, consumers, registrations, routes, schemas, configuration, persistence, side effects, and tests.
2. Inspect dynamic and implicit connections: string keys, reflection, dependency injection, event names, environment variables, generated code, serialization, migrations, feature flags, native boundaries, and public package exports.
3. Use Git history only when it adds evidence: files that change together, prior regressions, reversions, and ownership hotspots.
4. Classify each affected surface as direct, transitive, contractual, operational, or test-only.
5. Attach evidence to every material claim with a file path, symbol, command result, diff hunk, or commit. Label unsupported conclusions `Inference` or `Unknown`.

Do not treat a text search as a complete dependency graph. Explicitly list blind spots.

## Phase 3: Model failure and risk

For each credible failure mode, record:

- trigger and affected user or system behavior;
- evidence and impacted files;
- likelihood, severity, detectability, and blast-radius scores;
- total risk tier using [risk-model.md](references/risk-model.md);
- prevention, detection, rollback, and remaining uncertainty.

Prioritize behavioral and contract risks over aesthetic code-quality observations.

## Phase 4: Build a safe change plan

Produce an ordered plan with small reversible steps. For each step include files, preserved behavior, validation, rollback boundary, and prerequisites.

In `impact` mode, stop after the report and recommend the next safest action.

In `refactor` mode, pause before editing and request explicit approval for the proposed file scope and verification plan. Analysis does not authorize implementation.

## Phase 5: Preserve behavior and change incrementally

After approval in `refactor` mode:

1. Add or identify characterization tests for behavior that is important but insufficiently protected.
2. Capture baseline outputs for observable contracts when tests are impractical.
3. Make one coherent change at a time with recoverable checkpoints.
4. Run the narrowest relevant checks after each step.
5. Stop and update the report if the observed impact contradicts the plan or unrelated user changes overlap the target.

Do not call a feature change a refactor. If externally observable behavior intentionally changes, document the changed contract and obtain approval.

## Phase 6: Verify and conclude

Run validation in layers: focused tests, contract or integration tests, type checking and linting, build, then broader suites when proportionate. Compare baseline and final behavior.

Update `CODE-CHANGE-REPORT.md` with:

- final verdict: `SAFE TO PROCEED`, `PROCEED WITH CONDITIONS`, `NOT SAFE YET`, or `INCONCLUSIVE`;
- what was analyzed or changed;
- proof ledger with exact commands and results;
- residual risks, skipped checks, blind spots, and rollback plan;
- links to the most important local files.

Use `SAFE TO PROCEED` only when all high-risk paths have relevant passing evidence and no material unknown remains. Passing tests alone never prove universal safety.

## Report quality rules

- Keep the executive summary useful without reading the rest.
- Include at least one compact impact table and one risk table.
- Include a Mermaid impact map only when it clarifies three or more relationships.
- Prefer clickable repository-relative paths in the report.
- Never fabricate coverage, call graphs, test results, or Git history.
- Separate `Observed`, `Inferred`, and `Unknown` evidence.
- Make the file readable as a decision artifact, not a raw scanner dump.