Impact Map

Impact Map

Answer one question before any code is written:

> Before I change this, what else could this change affect?

The deliverable is an evidence-based blast-radius report: what is affected, why it is affected, how it is connected, how confident you are, and what should happen next. A list of filenames is not the deliverable.

Activation

Engage when a change alters something other code depends on: a shared concept, status or enum renamed or removed; a schema, API response, event or configuration key changed; behavior that crosses modules or layers; code read by raw SQL, jobs, reports or string comparisons. Also on what's the blast radius or what did this PR miss, and whenever the user names the skill.

Stay quiet when the code is new and nothing consumes it yet, or the change is copy, a typo, formatting, a comment, a rename the type checker fully covers, or a dependency bump.

Depth ACTIVE. An explicit request for a map gets the full report and stops there, read-only. When the user asked for the change itself, the map runs first as a compact pre-step: 🟥 MUST CHANGE, ⚠️ HIDDEN COUPLING and the open questions, nothing else. The requested change then proceeds on that surface. Stop for the user only when a finding needs their decision.

Composes with proof-driven-dev (MUST CHANGE and hidden coupling become regression requirements) · production-guard (the hidden-coupling findings are its regression surface) · api-contract-guard (an external consumer shows up in the map) · project-compass (the same coupling surfacing in a third change) · engineering-investigator (a cause that crosses systems comes back for a map).

In Claude Code it runs as its own subagent (context: fork), so the files it reads stay out of the conversation. It sees this file and the task it is handed, which arrives as ARGUMENTS: at the end, and not the conversation. With no task, map the uncommitted diff. With a clean tree, return one line naming what to pass. It returns the map. The change happens back in the conversation, and a plan needs the map passed back in with the request.

Working with the other Skills Hub skills

• Loaded is not engaged. This file stays in context once loaded. Decide

again on every new request whether it applies. Relevance to an earlier request carries nothing forward. Project state persists, and engagement does not.

• Depth. PASSIVE informs judgment and adds nothing to the reply ·

CONSULT adds a few lines that change what gets built · ACTIVE shapes the work · GATING decides whether something proceeds, and only when a person asked for that decision.

• Announce once. When any skill engages at CONSULT or above, open the

reply with one line such as ⚡ Impact Map · Standards Compass — rename reaches report SQL; export carries personal data: names and a few words of reason. Never include reasoning. Add no line for PASSIVE, and none on a trivial request. The line is a promise: every skill it names is loaded before the reply ends. If one turns out not to apply, say so in one line: dropped: .

• One interruption per request. Skills that must speak before the work share

one short block. Everything else arrives with the work.

• Hand off; don't absorb. When another discipline is needed, write

HANDOFF → : [] and let that skill do its part. When the request asked for that skill's decision, load it in the same turn and pass it your findings; a HANDOFF line alone does not answer the request. Never state another skill's verdict yourself. If it is not installed, do the smallest version of its check inline and say so.

• Conflicts. User intent, then project context, then engineering risk, then

applicable standards, then verification depth. Each skill keeps its own verdict, and none overrules another's.

• Overrides. "Use X" engages X. "Skip X" or "no review" drops X's ceremony.

Three things are never dropped: invented evidence, a check reported as run when it did not run, and a live hazard (a reachable security hole, data loss, money at risk). A live hazard is said once, in one line.

• State. Read what sibling skills recorded (.project-compass/,

.project-standards/, .proofbuild/, .agent-investigation/) rather than re-deriving it. Write only your own.

• Lessons. On engaging, read ~/.skills-hub/lessons/.md

if it exists. When a person corrects this skill's work (a miss, a false alarm, a wrong verdict), or the work exposes a gap in this file that another project would hit too, append one line to it: - YYYY-MM-DD · — . Never write project names, paths, identifiers, code or data there; facts about one repository are project state. Keep at most 20 lines, merging or replacing one to add another. A lesson sharpens this file's checks and never overrides its rules or a person's instruction. The file sits outside every project, so no read-only rule covers it. Say Lesson recorded: once; if the file cannot be written, give the lesson in the reply instead.

Non-negotiable rules

1. Read-only. During impact analysis do not edit, create, delete, or move

files; do not write migrations, install packages, run formatters, commit, or push. Inspecting files, git log/git blame, and dependency manifests is fine, as is reading an existing git diff. Running the project's own test suite is not part of analysis.

1. Evidence or nothing. Every classified finding names the file (and symbol

or line where useful) plus the observation that supports it. If you did not see it in the repository, say so and mark it for verification.

1. Never promote a guess. A low-confidence finding may never be reported as

MUST CHANGE. Downgrade instead of rounding up.

1. No fabricated numbers. Only report counts you actually produced. Prefer

"several files inspected" over an invented total. Counts are optional; accuracy is not.

1. No implementation inside the map. When the map was asked for, stop at

the report and offer the implementation plan; produce it only when the user asks. When the map runs as the pre-step to a change the user requested (see Activation), the analysis still edits nothing — the requested change follows it, on the surface the map found.

1. Report the gaps. Name the parts of the system you could not inspect

(generated code, private packages, external repos) rather than leaving them silently missing.

Workflow

Phases 1–7 run for every analysis. Phases 8–12 run when the change actually touches that layer — skip a phase explicitly rather than inventing content for it.

Phase 1 — Understand the request

Extract requested behavior, domain concepts, entities, fields, state/status transitions, user-facing behavior, API changes, data changes, integrations, and stated constraints. Compress it into one CHANGE STATEMENT:

> Introduce approval_status into course completion and expose it through the > existing API and UI.

If the request is ambiguous, pick the most reasonable reading, state it under INTERPRETATION, and continue. Do not stall the analysis on a clarification you can flag as an open question.

When the change already exists — the user points at uncommitted work, a branch, a PR, or a commit range — read the diff and write the change statement from what the code now does, not from the branch name. Every symbol, column, route, literal, and enum value the diff touches becomes a primary concept for Phase 3. Run the analysis on those concepts, then subtract the files already in the diff: what remains is the finding — the surface this change touches but has not visited. Commands and the rest of the recipe: references/git-signals.md.

Phase 2 — Repository reconnaissance

Learn the actual repository before searching it. Read the manifests (package.json, composer.json, pyproject.toml, go.mod, pom.xml, Gemfile, Cargo.toml), the top-level tree, and any workspace config. Identify language, framework, monorepo layout, and where the layers really live: frontend, API, domain/services, persistence, migrations, jobs/queues, events, notifications, authorization, configuration, integrations, generated code, tests.

Never assume src/, app/, lib/, or controllers/ exist. Look. When the repository contradicts framework convention, the repository wins. See references/framework-detection.md.

In a monorepo, scope before searching. Read the workspace config (pnpm-workspace.yaml, turbo.json, nx.json, go.work, Cargo [workspace], Gradle settings.gradle, Maven `), list the packages and their *published* names, find which package the change originates in, and invert the graph to get its dependents. Scope by that dependency graph, not by directory proximity, and report the scope — including the packages you did not inspect and why — under REPOSITORY SCOPE. A published package has consumers this repository cannot enumerate; say so rather than implying the surface is closed. See references/monorepo.md`.

Phase 3 — Find primary concepts

Search progressively, starting from the vocabulary in the change statement: class, function, and component names; tables and columns; enums and status values; routes; event names; domain terms.

Expand across naming conventions before concluding something does not exist — CourseCompletion, course_completion, course-completion, courseCompletion, completion_status, completed, approval, approve, approved. Exact identifier matching alone will miss the interesting coupling.

Phase 4 — Dependency analysis

For each primary concept, trace both directions:

• Upstream (who depends on this): importers, callers, consumers, queries,

API callers, components, jobs, event producers and listeners.

• Downstream (what this depends on): services invoked, models written,

tables touched, serializers, API responses, UI, notifications, events, queues.

Record the paths as chains, not sets, and explain the link at each step:

CourseCompletionService  → writes CourseCompletion.status
CourseCompletion         → serialized by CourseCompletionResource
CourseCompletionResource → returned by GET /api/course-completions
/api/course-completions  → consumed by CourseCompletion.tsx

Details and search tactics: references/dependency-analysis.md.

Phase 5 — History and ownership

Git records coupling that no import graph holds: which files engineers actually change together, which parts of the surface churn, and who reviews them.

• Co-change. For each primary concept, list the commits that touched it and

the other files in those commits. A file that appears in most of them with no code reference between the two is temporal coupling — a ⚠️ HIDDEN COUPLING finding at Medium confidence, never higher on history alone.

• Churn. High churn in the change surface means unsettled code: half-done

migrations, duplicated logic, stale tests. A file untouched for years carries the opposite risk — nobody currently holds it in their head. Both feed RISK; neither is a finding by itself.

• Ownership. CODEOWNERS first, contributor counts as a fallback. Report it

as routing — which reviewer or team this change needs — never as attribution or as a judgment about anyone's work.

Check that history is usable before trusting it: a shallow clone, a squash-merge workflow, a single founding commit, or an untracked rename all produce numbers that mislead. When history is unusable, say which condition applies and move on. Commands, ratios, and reporting rules: references/git-signals.md.

Phase 6 — Cross-layer analysis

Walk the layers this repository actually has, typically:

UI → API → Controller → Service/Domain → Model/Repository → Database

Then check the layers that sit beside the request path: events, jobs, scheduled tasks, notifications, permissions, reports/exports, integrations. Do not invent layers a repository does not have, and do not skip one because the framework "usually" handles it.

Phase 7 — Hidden coupling

The highest-value phase, and the one generic code search skips. Look for relationships that do not appear as imports:

• Raw strings — "completed" where the domain uses CompletionStatus.COMPLETED.
• Raw SQL — queries naming the affected tables or columns.
• Direct data access — code bypassing the domain/service layer.
• Duplicated business logic — the same status === "completed" decision in

several places.

• Configuration — environment variables, config keys, feature flags,

permission identifiers.

• Events and listeners — subscribers matched by string name.
• Jobs, workers, schedules — queue payloads carrying the affected shape.
• Serialization — JSON field names, API resources, DTOs, schemas, contracts.
• Tests and fixtures — factories, fixtures, snapshots, hardcoded states.
• Temporal coupling — files git history says change together, with no

reference between them (Phase 5).

• Documentation — API docs or runbooks that go stale on this change.

Everything found here is indirect evidence and must be labeled as such. Search patterns per category: references/hidden-coupling.md.

Phase 8 — Database impact

When persisted data is involved: migrations, schema, models/entities, relationships, repositories, raw SQL, indexes, constraints, seeders, factories, fixtures, reports, exports.

For schema changes also consider existing rows, defaults, nullability, backward compatibility, migration ordering, and whether a data backfill is required. Do not invent requirements — anything needing a human decision goes under OPEN QUESTIONS.

Phase 9 — API impact

Routes, controllers, request validation, response serializers, DTOs/schemas, API clients, frontend and mobile consumers, contract tests, documentation. Assess request shape, response shape, backward compatibility, validation, authorization, and versioning. Distinguish a consumer you found in the repository from a consumer that may exist outside it.

Phase 10 — Authorization impact

If the change touches approval, status transitions, roles, permissions, ownership, visibility, or administrative actions, inspect policies, guards, middleware, role checks, permission constants, UI permission checks, API authorization, and their tests.

Changing business logic does not update authorization. A new state usually needs a new answer to "who may move a record into it, and who may see it there."

Phase 11 — Test impact

Identify unit, integration, feature, API, component, E2E, and contract tests, plus factories, fixtures, and snapshots. For each relevant group state what behavior it protects, not just that it exists.

Missing coverage is a finding:

> No existing test covers the transition pending → approved.

Phase 12 — External boundaries

External APIs, webhooks, message brokers, mobile clients, other frontends, third-party integrations, imports/exports, scheduled syncs, reporting systems. Only claim an external consumer when repository evidence supports it; otherwise report it as an open question.

Classification

Every significant finding carries a stable id — F1, F2, … in report order — and exactly one classification. The ids are what the architecture graph, the risk table, and the implementation plan point at, so they must not be reused or renumbered inside a report.

| Category | Meaning | | --- | --- | | 🟥 MUST CHANGE | Strong evidence this location requires modification for the change to work. | | 🟧 LIKELY AFFECTED | Strong relationship established; whether it changes needs confirmation. | | 🟨 NEEDS VERIFICATION | Plausible relationship that must be checked before implementation. | | ⚠️ HIDDEN COUPLING | Indirect dependency via strings, SQL, config, duplicated logic, generated code, conventions, ser

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: soumyaRauth
• Source: soumyaRauth/skills-hub
• License: MIT
• Homepage: https://soumyarauth.github.io/skills-hub/

Install and usage instructions live in the source repository linked above.