Code change impact audit

Code Change Impact Audit

Outcome

Prevent local symptom patches from breaking other modules. Audit broadly, patch narrowly, and verify completely. Trace each change from its definition through every direct and indirect consumer, then close the loop with the smallest correct implementation and verification evidence.

Treat “comprehensive” as discovering and classifying every plausible consumer, not producing a large diff. Do not assume every consumer needs modification; change only affected paths and record why inspected consumers are unaffected.

Mandatory Rules

• Start every feature, bug-fix, and refactor task with an impact audit before editing.
• Maintain an impact ledger while working; update it when new dependencies appear.
• Before the first edit, share an impact preview containing the suspected changed contract, consumer groups, high-risk surfaces, and planned verification.
• Inspect behavior and contracts, not only matching text or filenames.
• Examine direct consumers, wrappers, re-exports, registries, shared state, and downstream side effects.
• Express required operations as capabilities, not vendor-specific tool names; adapt search, editing, execution, and inspection to the active agent runtime.
• Fix the root at the correct abstraction layer; avoid leaf-only patches when shared behavior is responsible.
• Understand the full flow before optimizing for fewer files or lines; the smallest patch in the wrong layer is another bug.
• Prefer deletion, existing code, standard or native capabilities, and already-installed dependencies before adding code or concepts.
• Extract shared code only when actual reuse or consistency requires it; do not componentize by reflex.
• Reject speculative abstractions, single-use factories, future scaffolding, premature configuration, and unnecessary dependencies.
• Never simplify away explicit requirements, trust-boundary validation, data-loss prevention, security, accessibility, financial correctness, or required compatibility.
• Classify every discovered consumer as change, verify, unaffected, or blocked.
• Treat every unexplained, unverified, or out-of-scope affected consumer as a completion blocker.
• Never call work complete merely because one screen works, a build passes, or the original symptom disappears.
• Report failed checks, unavailable environments, assumptions, and residual risk exactly as they are.

Load Applicable Guidance

Read repository instructions such as AGENTS.md, CLAUDE.md, contribution guidance, and matching area rules before mapping impact. Treat project-specific rules as authoritative when they are stricter.

Open references/impact-surfaces.md before mapping impact. Read every section matching the changed layer and its downstream layers. Read the entire reference for shared contracts, persistence, databases, money, security, authentication, public APIs, jobs, queues, deployment, infrastructure, or native changes.

Open references/agent-platform-compatibility.md when installing, distributing, or bridging this skill to another agent, or when the active runtime lacks repository search, shell execution, tests, browser or device access, or parallel agents.

Runtime Portability

• Treat SKILL.md as the single source of truth. Do not maintain vendor-specific copies of the workflow.
• Resolve bundled relative paths from the directory containing SKILL.md, regardless of the current working directory.
• Use native skills discovery when supported; otherwise load this file through the client's project instructions, custom rules, system prompt, or file-reading mechanism.
• Adapt tool use to the capabilities present. Missing tools reduce available evidence; they do not relax the impact audit or completion gate.
• Treat files under agents/ as optional client metadata. The workflow must remain functional when a client ignores them.

Core Doctrine: Wide Audit, Narrow Patch

Separate discovery scope from implementation scope:

• Expand discovery until every credible dependency and behavior path is classified.
• Contract implementation to the rows marked change and the minimum compatibility work they require.
• Prefer one root-cause correction shared by affected consumers over repeated leaf workarounds.
• Leave inspected verify and unaffected code unchanged unless verification proves otherwise.
• Treat a one-line shared-contract change as high impact when its dependency graph is broad; verification depth follows risk, not diff size.

After understanding the task and dependency graph, stop at the first rung that satisfies the task contract, resolves every change row, preserves invariants, and can be verified:

1. Avoid new code when deletion, configuration correction, data correction, or correct use of existing behavior solves the problem.
2. Reuse an existing component, helper, type, store action, pattern, or shared rule in the repository.
3. Use the language standard library.
4. Use a native platform capability.
5. Use an already-installed dependency.
6. Make the smallest direct change at the owning layer.
7. Only then add the minimum new helper, abstraction, configuration, or dependency justified by current consumers.

Question an over-specified mechanism, not the user's explicit outcome. Do not turn this ladder into a research project. Use evidence already gathered by the impact audit, choose the first rung that fully holds, and move on.

Workflow

1. Establish the Task Contract

• Restate the requirement or reproduce the bug.
• Capture current behavior, expected behavior, acceptance criteria, and relevant non-goals.
• Identify the observable symptom and the likely root layer separately.
• Record invariants that must remain unchanged.
• Preserve the user's requested scope; expose affected work outside that scope instead of silently skipping it.
• Capture relevant pre-existing worktree changes before using a final diff as evidence.

For a bug, create or define a failing regression scenario before applying the fix whenever practical. For a feature, define positive, negative, loading, error, and boundary behavior before implementation.

2. Identify Change Seeds

List every artifact whose contract or behavior may change:

• components, props, defaults, callbacks, refs, styles, and accessibility behavior;
• hooks, contexts, stores, selectors, actions, events, and side effects;
• utilities, constants, types, schemas, and serialization formats;
• API parameters, responses, mappings, cache keys, invalidation, and optimistic updates;
• services, controllers, middleware, domain logic, repositories, and external integrations;
• database schemas, migrations, constraints, indexes, transactions, and data backfills;
• event producers, consumers, queues, workers, schedulers, retries, and dead-letter paths;
• CLI commands, flags, configuration files, standard input, output formats, and exit codes;
• routes, navigation params, deep links, configuration, and feature flags;
• storage keys, persisted state, migrations, native modules, and build configuration;
• infrastructure definitions, environment variables, permissions, deployment order, rollout, and rollback;
• translation keys, analytics events, permissions, and background behavior.

Include implicit changes such as timing, ordering, defaults, nullability, rounding, error behavior, and render frequency.

3. Build the Dependency Graph

Use indexed symbol references and repository text search when available. Prefer a fast recursive search such as rg when shell access exists; otherwise use the client's native search, code index, or file-reading tools. Search each seed by:

• declared symbol and file basename;
• import path, path alias, renamed import, barrel export, and re-export;
• prop, callback, event, route, configuration, storage, query, and translation keys;
• endpoint, schema, table, column, topic, queue, job, command, environment, and infrastructure resource names;
• wrapper, adapter, composition, registry, factory, and dynamic lookup;
• external clients, protocol contracts, database readers, event subscribers, scripts, and operational runbooks;
• platform-specific variants and native bridges;
• tests, mocks, fixtures, snapshots, examples, generated consumers, and scripts.

Trace both directions:

1. Trace upstream inputs and assumptions feeding the changed artifact.
2. Trace downstream consumers and side effects produced by it.
3. Recursively inspect wrappers and shared abstractions until reaching user-visible or externally observable behavior.
4. Inspect dynamic registries and string-keyed lookups that text references cannot prove.
5. Search omitted/defaulted inputs as carefully as explicit inputs; a default change affects callers that pass nothing.

Do not stop after finding the first consumer or the first plausible root cause.

4. Create the Impact Ledger

Record one row for every discovered consumer or behavior path:

Artifact or consumer	Dependency path	Scenario	Classification	Action or rationale	Verification	Status

Use classifications consistently:

• change: behavior is affected and code, data, tests, or configuration must change.
• verify: behavior should remain compatible but requires proof.
• unaffected: inspection proves no relevant behavior change; record the reason.
• blocked: impact cannot be determined, authority is missing, or verification is unavailable.

Do not remove unaffected rows merely to shorten the report. Summarize large sets only when they share the same dependency path, rationale, and verification.

5. Assign Risk and Verification Depth

Treat a change as high risk when it touches shared public contracts, persisted data, database migrations, financial calculations, authentication or secrets, API or event schemas, jobs or queues, deployment order, infrastructure, navigation, feature gates, concurrency, native code, or many consumers.

Require deeper proof as risk rises:

• Verify every affected consumer for high-risk changes.
• Verify changed consumers and representative unaffected consumers for medium-risk changes.
• Still enumerate all consumers for isolated low-risk changes, then run focused proof.
• Expand verification when the audit discovers uncertain ownership, weak tests, dynamic consumers, or divergent implementations.

Map every change and verify row to a planned proof before editing.

6. Choose the Smallest Complete Solution

• Apply the minimum-solution ladder only after completing the dependency graph and initial ledger.
• Compare viable options by acceptance coverage, affected-consumer coverage, edge-case correctness, compatibility, reversibility, and added complexity.
• Count new files, lines, concepts, dependencies, configuration, migrations, and maintenance paths as complexity.
• Prefer boring, direct code over clever generalization.
• Prefer removing an obsolete workaround over layering a new workaround on top.
• Use a local override when behavior is intentionally local; do not change a shared default merely because it is convenient.
• Use a shared root fix when sibling consumers share the same defect; repeated local guards are not a minimal complete solution.
• Require present evidence before adding an abstraction for multiple implementations, a configurable value, a framework, or a dependency.
• Record only material alternatives that were skipped and the condition that would justify them later.

7. Implement a Complete Fix

• Change the narrowest correct shared contract rather than duplicating fixes at leaves.
• Preserve backward compatibility unless the requirement explicitly changes it.
• Update every impacted caller, wrapper, type, mock, fixture, and state transition in the same work unit.
• Add a variant or local exception only when behavior is intentionally context-specific; document the rationale in the ledger.
• Prefer deletion and reuse over addition, and keep the diff mechanically simple.
• Avoid unrelated cleanup that obscures the impact boundary.
• Revisit the ledger whenever implementation reveals a new dependency or side effect.

8. Verify Behavior

• Run the smallest relevant static checks, type checks, lint checks, and automated tests first.
• Add or update a regression test that fails without the bug fix whenever practical.
• Leave at least one focused runnable regression check for non-trivial branches, loops, parsers, persistence, money, or security logic; expand coverage only as the impact risk requires.
• Exercise the original path plus applicable loading, error, empty, disabled, retry, offline, and cancellation paths.
• Verify relevant services, runtimes, platforms, themes, locales, screen sizes, accessibility settings, feature flags, persisted-old-data paths, rollout order, and rollback behavior.
• Verify adjacent unaffected consumers when a shared implementation changed.
• Record exact commands, scenarios, outcomes, and skipped checks.
• Distinguish new failures from pre-existing unrelated failures with evidence.
• When a runtime capability is unavailable, use the strongest supported alternative and classify the missing proof as blocked; never relabel static inspection as runtime verification.

Do not treat code inspection, a type check, or a single happy-path test as sufficient proof of runtime behavior when material risk remains.

9. Re-audit the Final Diff

• Inspect the final diff for accidental scope expansion and missing companion changes.
• Repeat consumer searches using old and new symbols, signatures, keys, and values.
• Check for stale wrappers, obsolete call shapes, duplicated fallback logic, and newly inconsistent modules.
• Check for unused abstractions, premature configuration, avoidable dependencies, future-only scaffolding, and code that can now be deleted.
• Confirm that tests exercise the changed contract rather than only implementation details.
• Update the ledger counts and status after the final diff.

Completion Gate

Claim completion only when all conditions hold:

• Reproduce or define the original problem and acceptance criteria.
• Enumerate all credible direct and indirect consumers.
• Resolve every ledger row with evidence; leave no unexplained blocked or unverified row.
• Update all affected code, data, configuration, types, tests, and callers.
• Use the smallest complete solution supported by the impact evidence; justify every new abstraction, dependency, configuration surface, or migration.
• Leave verify and unaffected paths unchanged unless evidence required a reclassification.
• Verify the original behavior and relevant regression paths.
• Add regression coverage for a bug, or document why automation is impractical and provide equivalent focused evidence.
• Verify compatibility for shared consumers and applicable cross-platform or cross-state branches.
• Run relevant repository checks and report their results truthfully.
• Review the final diff and repeat impact searches.
• State remaining risk explicitly; state “none identified” only when supported by the audit.

If a material verification step cannot run, report the work as implemented but not fully verified. Do not relabel it as complete.

Required Final Report

Return a compact report containing:

1. Outcome — requirement satisfied or bug root cause fixed.
2. Changed contract — behavior, interface, data, timing, or side effect that changed.
3. Impact inventory — counts of direct, indirect, changed, verified, unaffected, and blocked consumers.
4. Affected paths changed — consumers and why they required changes.
5. Verified unaffected paths — consumers and the evidence or rationale.
6. Minimality decision — reused or deleted code, avoided complexity, and why the chosen layer is the smallest complete fix.
7. Verification evidence — commands, automated tests, and manual scenarios with results.
8. Residual risk — skipped checks, environmental limits, rollout concerns, or none identified.

Never use “done” or “complete” without satisfying the completion gate.