Impact Map

---
name: impact-map
description: "Use before changing anything other code depends on: renaming, splitting, merging or removing a status, enum, field, table, column, route or shared concept, or changing a schema, API response, event, configuration or cross-module behavior; and when asked for the blast radius, or what a change or PR missed. Traces callers, jobs, reports, raw SQL, string comparisons, fixtures, permissions and tests, including couplings no import shows, and returns the surface with evidence and confidence. Read-only. Not for new isolated code, copy or typo edits, formatting, comments, local renames the compiler resolves, or dependency bumps."
context: fork
background: false
---

# 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.

<!-- skills-hub:protocol -->
### 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: `<Skill> dropped: <reason>`.
- **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 → <skill>: <reason> [<ids>]` 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/<this skill's name>.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 · <the rule, stated for any project> — <what went wrong>`.
  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: <rule>` once; if the file
  cannot be written, give the lesson in the reply instead.
<!-- /skills-hub:protocol -->

## 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.
2. **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.
3. **Never promote a guess.** A low-confidence finding may never be reported as
   MUST CHANGE. Downgrade instead of rounding up.
4. **No fabricated numbers.** Only report counts you actually produced. Prefer
   "several files inspected" over an invented total. Counts are optional;
   accuracy is not.
5. **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.
6. **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 `<modules>`), 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, serialization, fixtures, or co-change history. |
| ⬜ **OUT OF SCOPE** | Inspected and found not materially related. Use sparingly — only where a reader would otherwise expect the file to appear. |

## Confidence

- **High** — direct reference or unambiguous dependency observed in the code.
- **Medium** — strong behavioral relationship with some inference.
- **Low** — plausible relationship that requires verification.

Confidence describes the *evidence*, classification describes the *action*. Low
confidence caps a finding at NEEDS VERIFICATION.

```
F1 · app/Services/CourseCompletionService.php

  Symbol:       CourseCompletionService::complete()
  Relationship: Writes CourseCompletion.status during the completion workflow.
  Evidence:     Line 42 sets $completion->status = CompletionStatus::COMPLETED
                and is the only writer found for that field.
  Classification: 🟥 MUST CHANGE
  Confidence:   High
  Action:       Set approval_status alongside status in the transition.
```

## Report format

Emit the sections in `references/report-schema.md`, in this order, omitting any
section with nothing relevant to say:

```
IMPACT MAP
────────────────────────────────────────
REQUEST · INTERPRETATION · REPOSITORY SCOPE · CHANGE SURFACE
🟥 MUST CHANGE · 🟧 LIKELY AFFECTED · 🟨 NEEDS VERIFICATION · ⚠️ HIDDEN COUPLING
DEPENDENCY PATHS · ARCHITECTURE GRAPH · HISTORY & OWNERSHIP
DATABASE IMPACT · API IMPACT · AUTHORIZATION IMPACT · TEST IMPACT
RISK · RECOMMENDED IMPLEMENTATION ORDER · OPEN QUESTIONS
```

`REPOSITORY SCOPE` appears when the repository is a monorepo or the analysis
started from a diff; it states what was in scope, what was not, and why.
`HISTORY & OWNERSHIP` appears when git history was usable, and is omitted with a
one-line reason when it was not.

### Architecture graph

When the surface branches or crosses three or more layers, draw it — a mermaid
`flowchart` with one subgraph per layer this repository actually has, nodes
labeled by finding id, and **every edge labeled with its relationship**. Solid
edges are hard (import, call, foreign key); dashed edges are soft (string, raw
SQL, config, convention, co-change) and are where the incidents come from. A
single linear path needs no graph — emit the chain and move on.

The graph renders findings that are already in the report. Never draw a node
without a location in the repository or an explicit "outside this repository"
marker, and never draw a suspected edge as fact. Conventions, an ASCII
alternative, and collapsing rules: `references/architecture-graph.md`.

### Risk

`RISK` is a scored argument, not a verdict: six factors — breadth, coupling
opacity, test coverage, reversibility, consumer reach, area volatility — each
scored 0–3 from what the analysis observed, each printed with the observation
that set it, summed into a Low / Medium / High band.

Show the factor table. A total without its factors is exactly the invented
number rule 4 forbids. A factor that could not be assessed is scored `?` and
makes the total a lower bound — never rounded down to make a change look safe.
Floors (an irreversible migration, an unreachable external consumer) override
the total upward, and the band is never lowered below it.
Rubric: `references/risk-scoring.md`.

## Normal vs deep mode

**Normal** (default): reconnaissance and scoping → primary concepts → direct
dependency tracing → history signals on the primary concepts → cross-layer
inspection → relevant tests → high-value hidden-coupling checks → report.

**Deep** — triggered by "deep analysis", "full impact analysis", "blast radius",
"thorough", "comprehensive": additionally sweep reverse references, raw strings,
raw SQL, configuration, generated artifacts, events, jobs, permissions, reports,
fixtures, external boundaries, duplicated business logic, co-change history for
every primary concept, and — in a monorepo — every dependent package rather than
the direct ones alone.

Deep mode means more *investigation*, not a longer file listing. Every extra
finding still needs evidence and a classification, and irrelevant files stay out
of the report.

## Interactive flow

```
User:  Add approval status to course completion.
Agent: I'll map the impact surface before changing anything.
       [analysis]
       IMPACT MAP …
       Want me to turn this into an implementation plan?
```

Only on an explicit yes, convert the map into a plan. The plan is a **handoff
artifact**: written so an engineer, or a fresh agent session with no memory of
the analysis, can execute it without re-reading anything. It still contains no
code.

Each step carries: the files, the finding ids it **resolves**, what it depends
on, the change in prose, the one-line evidence from the map, how to **verify**
it, and how to roll it back.

Three rules make it a handoff rather than a to-do list:

- **Coverage is explicit.** A closing table maps every finding id to its step.
  Each 🟥 is resolved by exactly one step; a 🟥 with no step is an invalid plan.
  🟧 is mapped or explicitly deferred with a reason; every ⚠️ gets a step or a
  recorded decision; every 🟨 becomes a **prerequisite** resolved before the
  steps that depend on it, never a check buried inside one.
- **Every step leaves the system working.** Order by dependency and
  reversibility: prerequisites, then compatibility (dual-read, dual-emit), then
  the change innermost outward, then data backfills, then the coverage for the
  quiet paths, then removing the shim. Size each step to one commit.
- **Verification is an observation**, not "verify it works" — an existing test
  path, a described assertion, or a command whose output shows the change took
  effect. A step that cannot be verified says so.

Unresolved decisions stay visible as prerequisites or `Stop if:` conditions,
never as assumptions baked into a step. If implementation shows the map was
wrong, stop and say which finding changed instead of re-planning quietly. The
plan's last line names what to validate afterwards — the hidden-coupling
findings and the factors that set the risk band.

Full structure and rules: `references/implementation-plan.md`. Worked example:
`examples/implementation-plan.md`.

Never jump silently from analysis to editing code.

## References

- `references/report-schema.md` — full report structure and finding fields
- `references/dependency-analysis.md` — upstream/downstream tracing tactics
- `references/hidden-coupling.md` — indirect-coupling search patterns
- `references/framework-detection.md` — per-ecosystem reconnaissance cues
- `references/git-signals.md` — co-change, churn, ownership, diff-driven analysis
- `references/monorepo.md` — workspace detection, package graph, scoping
- `references/architecture-graph.md` — graph conventions and honesty rules
- `references/risk-scoring.md` — the six-factor risk rubric
- `references/implementation-plan.md` — the plan structure and handoff contract

If `references/company-architecture.md` exists in this skill directory, read it
during Phase 2 — it carries team-specific conventions that override generic
framework assumptions.