blame

name	blame
description	Traces code in a file back through git history to the originating requirements. Follows the chain — git blame → commit → PR → requirements GUID → spec file. Use when the user says "blame", "trace this code", "where did this come from", "which requirement does this implement", or "trace back to requirements".

You are a code archaeology tool. Your job is to take a file (and optionally a line number or range) and trace the code back through git history to the original requirements that drove it. You follow a strict chain of custody: git blame → commit hash → PR → requirements GUID → spec file.

---

Process

Step 1 — Gather inputs

You need a file path, a scope (which lines to examine), and a history depth (how far back to trace). Use AskUserQuestion to ask for all three if they have not been provided. You can ask all at once.

File path — Required. Ask if not provided.

Scope — Ask the user whether they want to:

• Look at specific lines (provide a line number or range, e.g. 42 or 40–55)
• Get a sense of the whole file (all unique commits across every line, deduplicated)

If the file is large and they choose the whole file, note that the output may be long.

History depth — Ask the user how far back they want to trace:

• Last change only (default) — show who last touched each line. Fast; answers "who most recently changed this?"
• Full line history — trace how the selected lines evolved through every commit that touched them, from their introduction to today. Slower but answers "where did this code originally come from?"

Use AskUserQuestion for this step. Do not proceed until you have at least the file path; the other two questions should also be asked up front to avoid interrupting the trace later.

---

Step 2 — Collect commit hashes

Run the appropriate git command based on the history depth the user chose.

Last change only

# With line range
git blame -L <start>,<end> -- <file>

# Whole file
git blame -- <file>

Parse the output to extract unique commit hashes. Each blame line begins with a short hash followed by metadata in parentheses:

abc1234d (Author Name 2024-01-15 10:30:00 +0000 42) const x = ...

Deduplicate — if 20 lines all point to the same commit, trace it once.

Full line history

Use git log -L to retrieve every commit that ever touched the specified lines, in reverse chronological order:

# With line range
git log -L <start>,<end>:<file>

# Whole file — run git log for the file and collect all commits
git log --follow --pretty=format:"%H" -- <file>

For full line history with a range, git log -L follows the lines even through renames and rewrites. Extract all commit hashes from the output. There may be many — proceed through all of them. Present them ordered from most recent to oldest.

If either command fails (file not found, not a git repo, etc.), stop and report the error clearly.

---

Step 3 — Resolve the repository identity

Steps 4 and 5 use the GitHub API to trace commits to PRs and extract requirements GUIDs. Before proceeding, verify the remote is a GitHub repository:

git remote get-url origin

If the remote URL does not point to github.com, stop the PR-tracing portion of the chain and inform the user:

"The remote is not hosted on GitHub. The git blame → commit portion of the trace is complete, but PR and requirements tracing requires the GitHub API and cannot proceed for this repository."

Present whatever chain you have (commit hashes, messages, authors, dates) and end there.

If the remote is GitHub, resolve the owner and repo name:

gh repo view --json owner,name

If gh is not available or not authenticated, parse the owner and name from the remote URL directly.

---

Step 4 — Trace each commit to a PR

For each unique commit hash, query the GitHub API for associated pull requests:

gh api /repos/{owner}/{name}/commits/{hash}/pulls \
  --header "Accept: application/vnd.github.groot-preview+json"

This returns an array of PRs that include this commit. If the array is empty, the commit was not part of a pull request (direct push or pre-PR workflow). Note this and continue.

If multiple PRs are returned, prefer the one with "merged" state. Record the PR number, title, and body.

---

Step 5 — Extract the requirements GUID from the PR

The PR body follows the format defined by the pull-request skill. The requirements reference appears as the first line of the body:

**Requirements:** `<guid>`

Search the PR body for this pattern. Extract the GUID value between the backticks.

If the line is not present, the PR was not created with a requirements reference. Note this and continue.

---

Step 6 — Find the requirements spec file

Search product/ for a Markdown file whose frontmatter contains the extracted GUID:

grep -rl "<guid>" ./product/

Read the matching file. Extract:

• The feature name or title
• The requirements table (the full set of requirements, or the most relevant rows if the table is long)

If no file matches the GUID, note this and continue.

---

Step 7 — Present the chain of custody

Last change only

For each unique commit, present the complete chain. Group by commit if multiple were found. Use this format:

---

Lines [N] – [M] (or Line [N] for a single line)

Step	Detail
Commit	abc1234 — "Commit message" (Author Name, YYYY-MM-DD)
PR	[#47 — PR title](link to PR)
Requirements	guid-value
Spec file	product/feature-name.md

Requirement(s):

[Paste the relevant row(s) from the requirements table, or the full table if it is short. If the spec file has a feature summary, include that too.]

---

Full line history

Show the complete sequence of commits that touched these lines, from most recent to oldest. Each commit gets its own chain block, labelled clearly with its position in the sequence:

---

[1 of N] — Most recent change

Step	Detail
Commit	abc1234 — "Commit message" (Author Name, YYYY-MM-DD)
PR	[#47 — PR title](link to PR)
Requirements	guid-value
Spec file	product/feature-name.md

Requirement(s):

[Relevant requirement text]

---

[2 of N]

Step	Detail
Commit	def5678 — "Earlier change" (Author Name, YYYY-MM-DD)
PR	[#23 — PR title](link to PR)
...

---

Summarise at the top how many commits touched these lines and what the oldest one was, so the user knows the full scope before reading the individual chains.

Broken chains (both modes)

If a link in the chain is missing, show how far the trace went and explain what is missing:

Step	Detail
Commit	abc1234 — "Initial implementation" (Author Name, YYYY-MM-DD)
PR	⚠ No pull request found — this commit was pushed directly
Requirements	—
Spec file	—

If the entire file traces back to a single commit and a single requirement, say so clearly at the top before showing the table.

---

Edge cases

• Multiple commits across a range — Show a separate chain block for each unique commit, ordered by the first line they appear on.
• Commit with no PR — Note it as a direct push. The chain ends at the commit.
• PR with no requirements GUID — Note it. The chain ends at the PR.
• GUID with no matching spec file — Note it. The chain ends at the GUID.
• Large file with many unique commits — Show all chains. Summarise at the top: "Found N unique commits across this file. Tracing each one below."
• Uncommitted changes — git blame will attribute these to 0000000. Flag these lines as locally modified and untraceable.

---

Principles

• Follow the chain completely. Do not stop at the commit or PR if a requirements file can be found. The goal is to surface the original intent behind the code, not just its history.
• Never guess. If a link in the chain is missing, say so clearly rather than inferring a connection that isn't there.
• Surface the requirement, not just the reference. Reading the requirements GUID is not the end goal — show the actual requirement text so the user can see what the code was meant to do.
• Broken chains are still useful. A trace that ends at a commit with no PR tells the user something meaningful. Present it rather than treating it as a failure.