Safe change

Map blast radius before shipping — run when editing a service, controller, hook, or shared utility to surface all importers, affected API routes, test gaps,...

Security Scan

The skill's code, instructions, and requirements are consistent with its stated purpose (mapping blast radius and gating changes); it is read-only static analysis plus an expected verify gate that runs the project's build/test scripts.

Purpose & Capability

The SKILL.md, README, and the included scripts implement an impact scanner and a verify gate. The scanner only reads project files (package.json and .ts/.tsx files) to build importers, routes, env var references, and recent migrations. The verify gate runs tsc/lint/test/build if present. All requested capabilities align with 'map blast radius' and 'verify build integrity'.

Instruction Scope

Instructions confine the agent to running the included scanner and verify script and to pausing for an explicit checkpoint. The scanner performs project-wide read-only file traversal and regex analysis (expected). The verify gate executes project commands (npm scripts, tsc) which may run arbitrary repo code (tests/build scripts can have side effects) — this is expected for a verify gate but worth noting as an operational risk.

Install Mechanism

No install spec; the skill is instruction + scripts included in the bundle. No external downloads or package installs are performed by the skill itself (scan-impact.mjs intentionally uses only Node stdlib).

Credentials

The skill declares no required environment variables or credentials. The scanner only locates process.env.* references in source files (it does not read those environment values). No unrelated secrets or external service credentials are requested.

Persistence & Privilege

The skill is not forced-always, does not modify other skills or global agent configuration, and contains no code that persistently enables itself. The verify gate runs local build/test commands but does not change other skills or system-wide settings.

Assessment

This skill appears to do what it says: read-only impact analysis plus an optional verify gate. Before installing/run it, ensure the agent is allowed to run shell commands in a safe environment (tests and npm scripts can execute arbitrary repository code and may have side effects). Review your project's test/build scripts for destructive actions or external network calls if you plan to run the verify gate via an agent. Also remember the scanner is regex-based and can undercount importers (barrels, dynamic imports, path aliases) — treat Low scores conservatively and manually inspect barrels/dynamic imports in high-risk areas.

Know exactly what breaks before you touch it.

Safe Change maps the blast radius of any code change — importers, API routes, test coverage, ENV vars, database migrations — then gives you a risk score and waits for your go/no-go before running the verify gate.

It is the proactive companion to deep-debugging: catch impact before the bug ships, not after.

---

Quick Reference

Situation	Action
About to edit a shared service	→ Run scan-impact.mjs on the target file first
Risk score is High	→ Stop, read the impact report, get explicit go/no-go
Test gap detected (gap: true)	→ Write tests before changing, not after
Recent migrations found	→ Confirm migration compatibility before deploying
All checks pass	→ Run verify-gate.sh to confirm build integrity
Risk score is Low, tests green	→ Proceed, run verify gate at end

---

When to Use

Activate this skill whenever:

• You are about to rename or extract a function/class used across multiple files
• You are changing the signature of a service method
• You are modifying a NestJS controller or Next.js API route
• You are touching a file that is imported by more than 3 other files
• You are changing code that reads from process.env
• There is an active DB migration in the migrations folder
• A teammate asks "is it safe to change X?"

Do not skip this step for "small" changes. Most production incidents start as changes that felt small.

---

How It Works — 6 Phases

Phase 1 — Detect Stack

The agent reads package.json at the project root to determine:

• Is this NestJS, Next.js, or generic TypeScript?
• Are both frameworks present (monorepo)?

Phase 2 — Build Impact Map

Run scripts/scan-impact.mjs <target-file> from the project root.

The script uses regex-based static analysis (no AST compiler, zero install friction) to collect:

Dimension	What is collected
Importers	All .ts/.tsx files that import the target
API Routes	NestJS @Controller + HTTP verb decorators; Next.js app/api/**/route.ts
Tests	Spec/test files that import the target; gap flag when none exist
ENV vars	All process.env.X references in the target file
DB migrations	Files in migrations/ modified in the last 7 days

Phase 3 — Risk Score

Heuristic scoring (see table below). The agent reads the JSON output and renders it as a human-readable report.

Score	Conditions
Low	≤2 importers, no API routes, tests exist, no ENV vars, no recent migrations
Medium	3–7 importers OR 1–2 routes OR test gap OR ENV vars present
High	≥8 importers OR ≥3 routes OR test gap + ENV vars + recent migration

Phase 4 — Render Report

The agent formats the JSON from scan-impact.mjs into a Markdown report (see Output Format below). It presents the report and explicitly states the risk score at the top.

Phase 5 — Checkpoint (mandatory)

After presenting the report the agent must pause and ask:

"Risk score is [Low/Medium/High]. Do you want to proceed with this change? (yes / no / adjust scope)"

Do not proceed until the user confirms. This is the core safety gate.

Phase 6 — Verify Gate

After the change is made, run scripts/verify-gate.sh from the project root.

The gate runs in order:

1. tsc --noEmit — type-check
2. npm run lint (if script exists)
3. npm test (if script exists)
4. npm run build (if script exists)

Stops on first failure. Color-coded output. Non-zero exit on failure.

---

Output Format

The agent renders the JSON from scan-impact.mjs as:

## Safe Change Report — src/notifications/notifications.service.ts

**Risk Score: MEDIUM**
Risk factors: 5 importers, 1 API route, test coverage exists

### Importers (5)
- src/users/users.service.ts
- src/appointments/appointments.service.ts
- src/billing/billing.service.ts
- src/reports/reports.service.ts
- src/audit/audit.service.ts

### API Routes Affected
| Controller | Endpoints |
|------------|-----------|
| NotificationsController | POST /notifications, GET /notifications |

### Test Coverage
- src/notifications/notifications.service.spec.ts ✓
- Gap: no

### ENV Variables Referenced
- SMTP_HOST
- SMTP_USER
- SMTP_PASS

### Recent Migrations (last 7 days)
- None

---
**Checkpoint:** Do you want to proceed with this change? (yes / no / adjust scope)

---

Limitations

See references/limitations.md for the full list. Key constraints:

• Regex-based: dynamic imports (import(path)) are not detected
• Re-exports through barrel files (index.ts) may undercount importers
• Decorator aliases (custom @Route() wrapping @Controller) are not detected
• TypeScript only — no Python, Go, Rust adapters in v0.1

---

Companion Skills

• deep-debugging — use after a bug ships; safe-change is what you run before
• self-improving-agent — log the impact report as a learning when a change causes an incident

---

Scripts

Script	Purpose
scripts/scan-impact.mjs	Builds impact map, outputs JSON
scripts/verify-gate.sh	Runs tsc → lint → test → build in sequence

---

File Structure

safe-change/
├── SKILL.md                          # This file
├── README.md                         # Marketing overview
├── package.json                      # ClawHub metadata
├── scripts/
│   ├── scan-impact.mjs               # Impact analyzer (Node ESM, no deps)
│   └── verify-gate.sh                # Verify gate (bash)
├── references/
│   ├── example-impact-report.md      # Full SMTP swap example
│   ├── usage.md                      # How agent invokes the scripts
│   └── limitations.md                # Known limitations + trade-offs
└── assets/
    └── SKILL-TEMPLATE.md             # Template for creating similar skills