Add git-blame-historic-context skill by AryanGodara · Pull Request #4373 · cowprotocol/services

AryanGodara · 2026-05-01T09:03:43Z

What this is

A standalone procedure for using git blame to recover historic context before flagging unusual-looking code. Often, certain decisions led to sub-optimal-looking code, and those decisions are codified in git history rather than the code itself. This skill formalises the lookup + decision rubric.

Ships with /blame-context <path>:<line>, a slash command that wraps the procedure end-to-end. Use either the slash command or the procedure manually.

Why split out

Extracted from #4351 because the procedure is reusable beyond PR review — order-debug sessions and ad-hoc code investigations both want the same lookup play. Splitting keeps each consumer's surface focused.

Files

docs/skills/git-blame-historic-context.md — the procedure + decision rubric.
.claude/commands/blame-context.md — slash command wrapping the procedure.

Changes after Jose's review

Reword the opener: "certain decisions led to sub-optimal-looking code, and those decisions are codified in git history rather than the code itself."
Add a "When to invoke" section. The biggest framing change in this round. Don't run blame on first sighting — build the full picture first (read the change / PR / file end-to-end and collect lines that look off during the pass), then run blame on each candidate. Code that looks weird is often being partially fixed, moved, or replaced by the diff you're currently reading.
Add a real second worked example. The original settlement.rs:444 magic-constant case was a single data point. Added a second example from crates/observe/src/panic_hook.rs:14-15 — std::process::exit(1) from inside a panic hook looks aggressive, but blame walks back to PR Exit process if thread panics #530 / issue Forward panics from background tasks #514 (silent corruption from background-task panics). Different decision flavour: this one inverts the suspicion (drop the finding entirely, don't just downgrade), where the first example weakens it.
Drop "rare here;" from the merge-commit edge case (no need to pollute context with rarity comments).
Typo: "weigh" not "weight" the finding.

Reviewing this in isolation

The skill body is self-contained. The "Used by" footer links to ../COW_PR_REVIEW_SKILL.md, which lands with #4351; that link will 404 until that PR merges. Nothing else here depends on #4351.

How to try it

/blame-context crates/driver/src/domain/competition/solution/settlement.rs:444
/blame-context crates/observe/src/panic_hook.rs:14-15

Worked sample output for both is in the skill file's Examples section.

gemini-code-assist

Code Review

This pull request introduces a new Claude command and detailed documentation for the 'git blame historic context' skill, which assists developers in understanding the rationale behind unusual code by tracing it back to its originating PR. The feedback focuses on improving the automation of the gh pr view command by removing unnecessary repository flags that would require manual variable substitution, allowing the CLI to infer the context automatically.

gemini-code-assist · 2026-05-05T13:50:20Z

+1. `git blame -L <start>,<end> -- <path>` to find the originating commit.
+2. If the surface looks like a wholesale move/refactor (same author across many lines, recent date, identical hashes), retry with `git blame -w -C -C -C -L <start>,<end> -- <path>` to recover the real authoring commit.
+3. `git log -1 --format='%s%n%b' <sha>` for the commit body.
+4. If the subject ends with `(#NNNN)`, pivot to the PR conversation: `gh pr view <NNNN> -R <owner>/<repo>`. The PR body is usually richer than the squash commit alone.


The placeholder / in the gh pr view command will cause the command to fail when executed by the AI, as it won't have a value for these variables. Since the command is executed within a git repository, the gh CLI can automatically detect the repository context. Removing the -R flag makes the procedure truly end-to-end and more robust.

Suggested change

4. If the subject ends with `(#NNNN)`, pivot to the PR conversation: `gh pr view <NNNN> -R <owner>/<repo>`. The PR body is usually richer than the squash commit alone.

4. If the subject ends with (#NNNN), pivot to the PR conversation: gh pr view <NNNN>. The PR body is usually richer than the squash commit alone.

References

Focus on identifying logic that deviates from the PR's stated goals (end-to-end automation). ^(link)

gemini-code-assist · 2026-05-05T13:50:21Z

+# subject ends with "(#NNNN)" — extract the PR number, then pivot to the
+# PR conversation, which is usually richer than the commit body alone.
+git log -1 --format='%s%n%b' <sha>
+gh pr view <NNNN> -R <owner>/<repo>


The placeholder / in the gh pr view command is problematic for automated execution. Since the tool is intended to be used within the repository context, the gh CLI can infer the repository automatically. Removing the explicit repository flag ensures the command works without requiring the AI to guess or prompt for the owner and repository names.

Suggested change

gh pr view <NNNN> -R <owner>/<repo>

gh pr view <NNNN>

References

Focus on identifying logic that deviates from the PR's stated goals (end-to-end automation). ^(link)

jmg-duarte · 2026-05-06T13:32:17Z

@@ -0,0 +1,72 @@
+# Skill — `git blame` for historic context
+
+Use before flagging code that looks unusual, redundant, accidental, or "easy to clean up". Often that code looks weird because it had to.


This or similar

Suggested change

Use before flagging code that looks unusual, redundant, accidental, or "easy to clean up". Often that code looks weird because it had to.

Use before flagging code that looks unusual, redundant, accidental, or "easy to clean up". Often times, certain decisions led to sub-optimal code, those decisions are also often codified in git history.

jmg-duarte · 2026-05-06T13:34:00Z

+
+Two ways:
+
+- **Procedurally** — follow the steps below when you encounter unusual-looking code in any context (PR review, order-debug session, ad-hoc *"why is this here?"*).


Not sure how this interacts with other parts, but this shouldn't be invoked the first time the agent comes around weird code.

The agent needs to have a full picture of the PR they're analyzing first, gather places where code "looks off" while it analyzed it and only then, run this. Often times, the code that looks off is being partially fix, moved, etc

jmg-duarte · 2026-05-06T13:37:12Z

+A reviewer sees this in `crates/driver/src/domain/competition/solution/settlement.rs:444`:
+
+```rust
+let max_gas = eth::Gas(block_limit.0 / eth::U256::from(2));
+```
+
+`/2` looks arbitrary — a reviewer might be tempted to flag it as a magic number. Run the procedure first:
+
+```bash
+git blame -L 444,444 -- crates/driver/src/domain/competition/solution/settlement.rs
+# → a4ee76aae3  Felix Leupold  2024-03-18  ...
+
+git log -1 --format='%s%n%b' a4ee76aae3
+# → subject ends with `(#NNNN)`; pivot to the PR
+gh pr view <NNNN>
+# → body: "block builders' default algorithm picks tx whose gas limit
+#    fits remaining space; leave headroom for inclusion."
+```
+
+Decision: **weakens** the "magic number" suspicion — the constant has documented inclusion-economics rationale. Drop the finding, or downgrade to a `Question:` confirming the rationale still applies on the chain in question.


I think you need to find a second example, not to replace, but rather to provide more than one data point

I find that this example is a bit lackluster

jmg-duarte · 2026-05-06T13:37:36Z

+
+## Decision
+
+Promote what blame reveals into the finding's Explanation, then weight the finding:


Suggested change

Promote what blame reveals into the finding's Explanation, then weight the finding:

Promote what blame reveals into the finding's Explanation, then weigh the finding:

jmg-duarte · 2026-05-06T13:43:57Z

+
+## Edge cases
+
+- **Merge commit, not squash** — rare here; inspect with `git log -1 --format='%s%n%b' <sha>` and walk parents (`<sha>^1`, `^2`) to find the commit that actually authored the line.


No need to pollute context with rarity comments

Suggested change

- **Merge commit, not squash** — rare here; inspect with `git log -1 --format='%s%n%b' <sha>` and walk parents (`<sha>^1`, `^2`) to find the commit that actually authored the line.

- **Merge commit, not squash** — inspect with `git log -1 --format='%s%n%b' <sha>` and walk parents (`<sha>^1`, `^2`) to find the commit that actually authored the line.

… second worked example, typo + cosmetic fixes

AryanGodara changed the title ~~Add git-blame-historic-context skill"~~ Add git-blame-historic-context skill May 1, 2026

AryanGodara assigned AryanGodara and unassigned AryanGodara May 1, 2026

AryanGodara mentioned this pull request May 5, 2026

Add /review-pr skill and wire it into the Claude Code Review workflow #4351

Open

AryanGodara force-pushed the aryan/git-blame-skill branch from 07f2227 to ff73770 Compare May 5, 2026 13:45

AryanGodara marked this pull request as ready for review May 5, 2026 13:48

AryanGodara requested a review from a team as a code owner May 5, 2026 13:48

gemini-code-assist Bot reviewed May 5, 2026

View reviewed changes

AryanGodara added 3 commits May 5, 2026 19:57

Add git-blame-historic-context skill

841a9ed

feat: add /blame-context slash command and worked example

c58803a

fix: drop unused -R flag from gh pr view

8cb5c1d

AryanGodara force-pushed the aryan/git-blame-skill branch from 9b89fe4 to 8cb5c1d Compare May 5, 2026 14:27

jmg-duarte reviewed May 6, 2026

View reviewed changes

address Jose review on git-blame skill: reframe 'when to invoke', add…

4cc1201

… second worked example, typo + cosmetic fixes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add git-blame-historic-context skill#4373

Add git-blame-historic-context skill#4373
AryanGodara wants to merge 4 commits intomainfrom
aryan/git-blame-skill

AryanGodara commented May 1, 2026 •

edited

Loading

Uh oh!

gemini-code-assist Bot left a comment

Uh oh!

gemini-code-assist Bot May 5, 2026

Uh oh!

gemini-code-assist Bot May 5, 2026

Uh oh!

jmg-duarte May 6, 2026

Uh oh!

jmg-duarte May 6, 2026

Uh oh!

jmg-duarte May 6, 2026

Uh oh!

jmg-duarte May 6, 2026

Uh oh!

jmg-duarte May 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	4. If the subject ends with `(#NNNN)`, pivot to the PR conversation: `gh pr view <NNNN> -R <owner>/<repo>`. The PR body is usually richer than the squash commit alone.
	4. If the subject ends with (#NNNN), pivot to the PR conversation: gh pr view <NNNN>. The PR body is usually richer than the squash commit alone.

		@@ -0,0 +1,72 @@
		# Skill — `git blame` for historic context

		Use before flagging code that looks unusual, redundant, accidental, or "easy to clean up". Often that code looks weird because it had to.


		Two ways:

		- Procedurally — follow the steps below when you encounter unusual-looking code in any context (PR review, order-debug session, ad-hoc "why is this here?").


		## Decision

		Promote what blame reveals into the finding's Explanation, then weight the finding:


		## Edge cases

		- Merge commit, not squash — rare here; inspect with `git log -1 --format='%s%n%b' <sha>` and walk parents (`<sha>^1`, `^2`) to find the commit that actually authored the line.

	- Merge commit, not squash — rare here; inspect with `git log -1 --format='%s%n%b' <sha>` and walk parents (`<sha>^1`, `^2`) to find the commit that actually authored the line.
	- Merge commit, not squash — inspect with `git log -1 --format='%s%n%b' <sha>` and walk parents (`<sha>^1`, `^2`) to find the commit that actually authored the line.

Conversation

AryanGodara commented May 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What this is

Why split out

Files

Changes after Jose's review

Reviewing this in isolation

How to try it

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot May 5, 2026

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist Bot May 5, 2026

Choose a reason for hiding this comment

Uh oh!

jmg-duarte May 6, 2026

Choose a reason for hiding this comment

Uh oh!

jmg-duarte May 6, 2026

Choose a reason for hiding this comment

Uh oh!

jmg-duarte May 6, 2026

Choose a reason for hiding this comment

Uh oh!

jmg-duarte May 6, 2026

Choose a reason for hiding this comment

Uh oh!

jmg-duarte May 6, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

AryanGodara commented May 1, 2026 •

edited

Loading