impact-analyze/
├── SKILL.md              # 主指令（必需，建议 < 500 行）
├── risk-rubric.md        # 风险评判标准（按需加载）
├── report-template.md    # 输出模板（按需加载）
└── scripts/
    └── find-refs.sh      # 可执行脚本（被执行，而非读入上下文）

mkdir -p ~/.claude/skills/impact-analyze/scripts

#!/usr/bin/env bash
# find-refs.sh — locate references to a symbol across the repo
# Usage: find-refs.sh <symbol-or-path>
set -euo pipefail

SYMBOL="${1:-}"
if [[ -z "$SYMBOL" ]]; then
  echo "ERR: no symbol provided"; exit 1
fi

ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
echo "# Target: $SYMBOL"
echo "# Repo root: $ROOT"
echo

# 1. 文件级命中清单（用于判断波及面广度）
echo "## Files referencing '$SYMBOL'"
rg -l --no-heading "$SYMBOL" "$ROOT" 2>/dev/null | head -50 || true
echo

# 2. 命中密度 Top20（密度高 = 可能是核心调用点）
echo "## Match density (top 20 by file)"
rg -c --no-heading "$SYMBOL" "$ROOT" 2>/dev/null \
   | sort -t: -k2 -rn | head -20 || true
echo

# 3. 疑似定义点（多语言常见定义关键字）
echo "## Candidate definitions"
rg -n --no-heading \
   "(def |function |func |class |const |export (default )?function |interface )" \
   "$ROOT" 2>/dev/null \
   | rg "\b${SYMBOL}\b" | head -20 || true
echo

# 4. 命中该符号的测试文件（回归测试范围线索）
echo "## Test files touching '$SYMBOL'"
rg -l --no-heading "$SYMBOL" "$ROOT" \
   -g '*test*' -g '*spec*' -g '*.test.*' 2>/dev/null | head -20 || true

chmod +x ~/.claude/skills/impact-analyze/scripts/find-refs.sh

---
description: Analyze the blast-radius of a code change. Use when the user asks "who calls X", "what will this affect", "is it safe to change/rename/delete X", or before any refactor / rename / delete of a function, class, method, or constant. Produces a risk-rated impact report plus a Mermaid call graph.
argument-hint: <symbol or file path>
allowed-tools: Read Grep Glob Bash
---

## References to "$1"

!`${CLAUDE_SKILL_DIR}/scripts/find-refs.sh "$1"`

## Instructions

You are performing a **change-impact (blast-radius) analysis** of the symbol
above. Work through these steps, then produce the report.

1. **Identify the definition.** From "Candidate definitions", pick the real
   definition site(s). Read 1-2 of them to confirm signature & visibility.
2. **Classify references** into: direct callers, indirect/transitive callers,
   re-exports, and tests. Use "Match density" to spot hotspots.
3. **Rate the risk** of *changing/renaming/deleting* this symbol using the
   rubric in risk-rubric.md — load it: see [risk-rubric.md](risk-rubric.md).
4. **Recommend regression scope** — list the test files that must pass, and any
   caller that has no test coverage (a gap that itself is a risk).
5. **Draw a Mermaid call graph** of the top callers → target → top callees.

## Output format

Follow [report-template.md](report-template.md) exactly:
definition location, risk level (low/medium/high) with one-line reason,
caller table, recommended tests, and a fenced ```mermaid graph.

Keep prose tight. Tables > paragraphs.

# Risk rubric for blast-radius

Rate the risk of changing/renaming/deleting the target symbol:

- **High** — exported public API / entry point / called by >5 files / part of
  an interface or base class / has no direct test.
- **Medium** — internal helper used by 2-5 files, or public but well-tested.
- **Low** — single-file local, private, fully covered by tests.

Tie-breakers: any "no test coverage on a caller" bumps the level up one notch.

# Impact report: <symbol>

**Definition:** `path/to/file.py:42` (visibility)
**Risk: HIGH | MEDIUM | LOW** — <one-line reason>

## Callers (top)
| Caller | File | Has test? |
|:--|:--|:--|

## Regression scope
- Must pass: <test files>
- Coverage gaps (risk): <callers without tests>

## Call graph
```mermaid
graph LR
  A[Caller] --> T[Target]
  T --> C[Callee]

这两个文件故意不塞进 `SKILL.md` 正文——它们只在「评级」和「排版」两步才需要，常驻是浪费。

### 步骤 5：验证热加载

由于目录已存在，**无需重启**。在仓库里启动 `claude`，输入 `/` 应能看到 `impact-analyze`（带 argument-hint）。

---

## 四、三种调用方式与效果验证

1. **显式调用**：`/impact-analyze checkoutSession`
2. **自然语言触发**（靠 description 命中）：直接问「我把 `checkoutSession` 的返回值从对象改成 Promise，会影响哪些地方？」
3. **带引号的多词参数**：`/impact-analyze "processOrder"` —— 若符号含特殊字符，用 shell 风格引号包起来。

预期：模型先呈现「References to ...」段（即脚本实时输出），再按 `report-template.md` 给出定义位置、风险评级、调用方表格、回归测试范围，最后一张 Mermaid 图。

---

## 五、进阶配置

### `paths`：只在改相关文件时触发

若你希望这个 Skill 只在用户编辑源码时自动激活（而非写文档时），加 frontmatter：

```yaml
paths: "**/*.{ts,js,py,go,java,rs,c,cpp}"

> /impact-analyze checkoutSession

# Impact report: checkoutSession

**Definition:** src/auth/session.ts:88 (exported, public)
**Risk: HIGH** — exported public API, called by 7 files, 3 callers lack tests.

## Callers (top)
| Caller                       | File                        | Has test? |
|:--|:--|:--|
| handleCheckout               | src/routes/checkout.ts:21   | yes       |
| refreshIfNeeded              | src/middleware/auth.ts:54   | yes       |
| adminForceCheckout           | src/admin/sessions.ts:33    | no        |
| ...                          | ...                         | ...       |

## Regression scope
- Must pass: tests/routes/checkout.test.ts, tests/middleware/auth.test.ts
- Coverage gaps (risk): src/admin/sessions.ts (no test — bump risk)

## Call graph
```mermaid
graph LR
  R[checkout route] --> T[checkoutSession]
  M[auth middleware] --> T
  A[admin tool] --> T
  T --> S[(Session store)]

flowchart TD
  U[用户: /impact-analyze checkoutSession] --> RND[渲染 SKILL.md]
  RND --> SUB[字符串替换: $1, $ARGUMENTS, ${CLAUDE_SKILL_DIR}]
  SUB --> INJ[动态注入: 执行 find-refs.sh]
  INJ --> CTX[实时引用结果 进入正文]
  CTX --> M[Claude 接到 含数据的指令]
  M --> S1[确认定义点 Read]
  M --> S2[分类调用方 Grep]
  S2 --> S3[读 risk-rubric.md 评级]
  S3 --> S4[套 report-template.md]
  S4 --> OUT[影响报告 + Mermaid 调用图]

  style INJ fill:#fde68a,stroke:#b45309
  style CTX fill:#bbf7d0,stroke:#15803d