AGENT SKILL

heatmap

Use git heatmap analysis to identify high-churn files and lines as candidates for thorough review or bug hunting. Works for PR reviews, security audits, bug hunts, or any code analysis task.

License 许可
Apache-2.0
所属仓库
apache/cassandra
最近更新
2026-11-14
Stars
★ 1.0w
Forks
4.1k

01 前言 Front Matter

name
heatmap
version
1.0.0
description
Use git heatmap analysis to identify high-churn files and lines as candidates for thorough review or bug hunting. Works for PR reviews, security audits, bug hunts, or any code analysis task.

02 资源文件 1

03 SKILL.md 正文

Heatmap-Guided Review

Use the bundled heatmap.py script to identify the hottest (most frequently and recently changed) code in a repository, then focus review effort on those areas. Hot code is statistically more likely to contain bugs: it changes often, accumulates complexity, and is where active development risk concentrates.

When to use

Invoke this skill whenever you want to prioritize where to look in a codebase — during PR reviews, bug hunts, security audits, onboarding exploration, or any task where you need to decide which files and lines deserve the closest attention.

Prerequisites

  • Python 3 must be available.
  • The target must be a git repository.
  • The heatmap script is bundled with this skill at ~/.claude/skills/heatmap/heatmap.py. All commands below use HEATMAP as a placeholder:
    HEATMAP="$HOME/.claude/skills/heatmap/heatmap.py"
    
    If heatmap is available on PATH, you may use that instead.

Workflow

Step 1: Determine the repository path and scope

Figure out the git repository root. If the user provided a repo path, use that. If working in a repo already, use the current directory. If reviewing a PR, determine which files were changed.

HEATMAP="$HOME/.claude/skills/heatmap/heatmap.py"
# Find the repo root
git -C <path> rev-parse --show-toplevel

Step 2: Run repo-level heatmap

Get the hottest files in the repository. Use --json for machine-readable output. Adjust --top based on context (20-50 for a broad scan, more for large repos).

python3 "$HEATMAP" repo --json --top 50 <repo_path>

This returns JSON array of objects with: path, heat, commits, last_modified_days.

Step 3: Cross-reference with the task context

For PR reviews: Intersect the heatmap results with the files changed in the PR. Files that are both changed in the PR AND high on the heatmap are the highest-priority review targets — they are already complex/volatile and the PR is adding more changes to them.

# Get PR changed files
git diff --name-only <base_branch>...HEAD

For bug hunts: The hottest files ARE the candidates — frequent recent changes correlate with bugs. Focus on the top 10-20.

For security audits: Filter heatmap results to security-sensitive paths (auth, crypto, input parsing, network, serialization).

For general exploration: Use the heatmap as a map of where active development is happening.

Step 4: Run line-level heatmap on top candidates

For each high-priority file (typically 3-8 files), run the line-level heatmap to find the hottest regions within those files.

python3 "$HEATMAP" file --json <file_path_relative_to_repo> <repo_path>

This returns JSON array of objects with: line, heat, content.

Step 5: Identify hot zones

From the line-level results, identify contiguous regions of high heat. These "hot zones" are where to focus review. Look for:

  • Clusters of hot lines — contiguous blocks of high-heat code indicate areas under active rework. These are prime bug candidates because:

    • Multiple recent changes suggest the logic is not yet settled
    • Each change is an opportunity for regression
    • Complex interactions between recent changes may not be fully tested
  • Hot lines surrounded by cold code — surgical edits in otherwise stable code may indicate bug fixes, workarounds, or special-case handling that deserves scrutiny.

  • Hot function/method boundaries — if a method signature or its first few lines are hot, the contract may have changed recently, affecting all callers.

Step 6: Produce the review focus list

Output a ranked list of review targets, structured as:

## Heatmap Review Targets

### Priority 1: <file_path> (heat: X, commits: Y)
- **Hot zones**: lines A-B (description of what this code does)
- **Why it matters**: <context — e.g., "most changed file in repo AND modified in this PR">
- **What to look for**: <specific guidance based on the code — race conditions, edge cases, etc.>

### Priority 2: ...

Step 7: Deep review

For each priority target, read the hot zones and perform the actual review. The heatmap tells you WHERE to look; your expertise tells you WHAT to look for. Common patterns in hot code:

  • State management bugs: Hot code often manages complex state. Check for inconsistent updates, missing synchronization, or partial failures.
  • Edge cases: Frequent changes often mean edge cases keep being discovered. Look for more.
  • Regression risk: If code was recently fixed, check whether the fix is complete and doesn't break other paths.
  • Missing tests: Hot code that lacks test coverage is the highest-risk combination.

Output format

Always present findings as a prioritized list with:

  1. File path and heat metrics
  2. Specific line ranges to focus on
  3. What the hot code does (brief)
  4. What risks to look for (specific to the code, not generic)

Tips

  • Heat is relative — compare files against each other, not against an absolute threshold.
  • Files with high heat but few commits have large individual changes (risky). Files with high heat and many commits are under constant churn (also risky, differently).
  • last_modified_days close to 0 means very recent changes — highest chance of unfound bugs.
  • Use --since to adjust the time window. Default is 2 years. For recent bug hunts, try --since "6 months ago".
  • The --no-color flag is useful when piping output, but prefer --json for programmatic use.

04 同仓库更多 Skills

apache
apache/cassandra

write-reproducer

Write minimal, reliable bug reproducers (repros) for any project. Use when: (1) a bug report or issue needs a test that reliably demonstrates the failure, (2) converting a described failure scenario into runnable code, (3) minimizing an existing complex test to its essential trigger conditions. Covers the full repro workflow: failure characterization, scope selection, writing the repro, verifying it fails for the right reason, and minimizing to the smallest possible trigger.

测试与质量
★ 1.0w
apache
apache/cassandra

tla-plus

Create, run, and verify TLA+ and PlusCal formal specifications. Use for modeling distributed systems, protocols, concurrent algorithms, state machines. Can compose specs from code, find divergences between spec and implementation, spot concurrency bugs and invariant violations. Use when asked to "write a TLA+ spec", "model check", "verify protocol", "find race conditions", or "formal verification".

★ 1.0w
apache
apache/cassandra

targeted-review

Findings-driven targeted code review. Understands the patch via patch-explainer and surrounding code via codebase-analysis, then consults a catalog of bug patterns (~11 categories under references/categories/). Picks only categories whose diff-signals match the patch and items whose "look for" hints match actual code shapes, groups them by review focus (function/file/feature), and spawns parallel subagents — each with a tight scope and selective checklist. Use for medium-to-large patches (50-1000 LOC) as a focused alternative to whole-patch ensemble or whole-file deep review. Triggers on: "review this patch/diff/change", "find bugs in this change", "scoped review", "what could go wrong here", "review using findings", or proactive PR review.

代码审查
★ 1.0w
apache
apache/cassandra

shallow-review

Shallow (quick) ensemble bug-finding review using 6 specialist agents in parallel. Each specialist reviews the same patch through a different lens: Logic & Types, Boundaries & I/O, Concurrency & State, Resources & Serialization, Absence Analysis, and API Completeness. Findings are merged and deduplicated. Best for: quick first-pass review of patches, triage of diffs, broad surface-level bug scan. For deeper file-focused review with full pattern catalogs and codebase investigation, use the deep-review skill instead.

开发工程师后端与接口
★ 1.0w
apache
apache/cassandra

patch-explainer

Deep code analysis with ASCII visualizations showing structure, flow, and state transitions. Use when analyzing patches/diffs, explaining classes or subsystems, understanding code architecture, reviewing changes for inconsistencies, or when asked to visualize how code works. Provides before/after diagrams, data/control flow, concurrency analysis, assumptions, and failure modes. Triggers on explain this patch/code/class, how does X work, show me the flow, visualize this change, code review requests, or proactive analysis during PR reviews.

代码审查
★ 1.0w
apache
apache/cassandra

mega-review

Multi-pass deep code review for large patches (1000+ LOC) that maximizes real bug detection. Orchestrates targeted-review, shallow-review, and deep-review in parallel across all HIGH and MEDIUM risk files and commits: understands the feature holistically, splits by file and commit, runs deep review on every HIGH/MEDIUM file, targeted review across the same scope, and per-commit shallow review, followed by cross-cut consistency checks. Use when: reviewing a large patch (feature branch, multi-commit, or single large diff, 1000+ LOC), doing a thorough pre-merge review, or when shallower reviews miss bugs due to patch size. Triggers on: "review this branch", "review these commits", "review this feature", "mega review", "thorough review", "full review of X commits", or when the user specifies a commit range or feature for review.

代码审查
★ 1.0w