Skip to content

100+ AI Agents, Agent Skills and RAG Apps - Free and Open Source.

Add commit-archaeologist skill: reconstruct the why behind code from git history (#974)

Matt Van Horn76b63f64f044
diff --git a/README.md b/README.md
index 32bfdae8..b819022c 100644
--- a/README.md
+++ b/README.md
@@ -85,6 +85,7 @@ streamlit run travel_agent.py
* [⚰️ Project Graveyard](agent_skills/project-graveyard/) - Finds every side project you abandoned, tells you why each one died, and helps you finish the one worth going back to
* [🔭 Scope Creep Detector](agent_skills/scope-creep-detector/) - Checks whether a diff grew beyond its stated intent and recommends what to keep, split, or justify
+* [🏺 Commit Archaeologist](agent_skills/commit-archaeologist/) - Reconstructs why a file or code region exists from its introducing commit, later edits, co-changes, and intent clues
* [🧠 Advisor Orchestrator Worker](agent_skills/advisor-orchestrator-worker/) - Meta Loop with Claude Flabe 5 as advisor, GPT-5.6 as orchestrator, and Gemini 3.5 Flash as worker
* [♾️ Self-Improving Agent Skills](agent_skills/self-improving-agent-skills/) - Automatically optimize agent skills using Gemini and ADK
diff --git a/agent_skills/README.md b/agent_skills/README.md
index 4d45262a..259045c0 100644
--- a/agent_skills/README.md
+++ b/agent_skills/README.md
@@ -19,6 +19,7 @@ Most "skills" on registries are text-only prompt dumps — advice the model alre
| Skill | What it does |
|---|---|
| [🧠 advisor-orchestrator-worker](advisor-orchestrator-worker/) | Turns your agent into the orchestrator of a three-tier model team: cheap stateless workers in parallel, expensive advisor consulted only at commitment boundaries, verification gates between every step — budgeted so a run can't burn a hole in your API bill |
+| [🏺 commit-archaeologist](commit-archaeologist/) | Reconstructs why a file or code region exists from local git history, including its introducing commit, later edits, repeated companion files, current authorship, and intent clues |
| [⚰️ project-graveyard](project-graveyard/) | Scans your machine for dead side projects, autopsies why each one died from its git history (deploy fear, payments wall, killed by a newer project), shows your personal death patterns, and resurrects the one with a pulse — with relapse tracking on every resurrection it prescribes |
| [🔭 scope-creep-detector](scope-creep-detector/) | Checks a diff against its stated intent, flags unrelated files and scope signals, and recommends what to keep, split, or justify |
| [♾️ self-improving-agent-skills](self-improving-agent-skills/) | Automatically optimizes agent skills using Gemini and ADK |
diff --git a/agent_skills/commit-archaeologist/README.md b/agent_skills/commit-archaeologist/README.md
new file mode 100644
index 00000000..df2e3895
--- /dev/null
+++ b/agent_skills/commit-archaeologist/README.md
@@ -0,0 +1,74 @@
+# Commit Archaeologist Agent Skill
+
+`git blame` tells you who last changed a line. Commit Archaeologist reconstructs
+why the line exists.
+
+Point it at a tracked file and an optional line range. Its local Python script
+finds the introducing commit, orders later modifications, classifies commit
+messages, summarizes current authorship, detects repeatedly co-changed files,
+and flags issue references, reverts, workarounds, temporary choices, and TODOs.
+The agent turns that evidence into a readable history and a change-risk note.
+
+![demo](https://github.com/mvanhorn/awesome-llm-apps/releases/download/demo-assets/commit-archaeologist.gif)
+
+## Install
+
+```bash
+npx skills add https://github.com/Shubhamsaboo/awesome-llm-apps/tree/main/agent_skills/commit-archaeologist
+```
+
+The [skills CLI](https://skills.sh) installs the folder for compatible coding
+agents. You can also copy this directory into an agent's skills directory.
+
+## Run
+
+Ask your agent:
+
+> Why does `src/cache.py` lines 40-72 exist, and what should I know before I
+> change it?
+
+Or run the deterministic core from a clone of this repository:
+
+```bash
+python3 agent_skills/commit-archaeologist/scripts/archaeologist.py \
+ /path/to/repo src/cache.py --lines 40-72 --json
+```
+
+Omit `--lines` to follow the entire file history. Omit `--json` for a compact
+terminal summary.
+
+## Output
+
+The JSON dig report contains:
+
+- the normalized region, historical path aliases, and co-change threshold
+- the introducing commit
+- an oldest-to-newest timeline with changed files and intent categories
+- repeated co-changes and their supporting commits
+- current blamed-line counts alongside historical commit counts
+- intent signals grounded in commit subjects and bodies
+
+Everything runs locally with Python's standard library and git. The script is
+read-only and makes no network calls.
+
+## Verify
+
+```bash
+python3 agent_skills/evals/commit-archaeologist/test_archaeologist.py
+```
+
+The eval builds its own temporary repository and checks ordering, co-changes,
+authorship, intent signals, deterministic JSON, and validation errors.
+
+## Files
+
+```text
+commit-archaeologist/
+|-- SKILL.md
+|-- README.md
+|-- scripts/archaeologist.py
+`-- references/reading-git-history.md
+```
+
+Part of [awesome-llm-apps](https://github.com/Shubhamsaboo/awesome-llm-apps).
+Apache-2.0. Last verified: July 2026.
diff --git a/agent_skills/commit-archaeologist/SKILL.md b/agent_skills/commit-archaeologist/SKILL.md
new file mode 100644
index 00000000..a80214be
--- /dev/null
+++ b/agent_skills/commit-archaeologist/SKILL.md
@@ -0,0 +1,132 @@
+---
+name: commit-archaeologist
+description: >-
+ Reconstructs why code exists from local git history, including the introducing
+ commit, later changes, current authors, repeated companion files, and likely
+ intent. Use when the user asks "why does this code exist", "who wrote this
+ function and why", or to "explain the history of this function" before a
+ rewrite, refactor, or risky edit. Runs entirely locally.
+license: Apache-2.0
+metadata:
+ author: "Matt Van Horn"
+ version: "1.0.0"
+ source: "https://github.com/Shubhamsaboo/awesome-llm-apps"
+---
+
+# Commit Archaeologist
+
+`git blame` names the last person to touch a line. This skill reconstructs the
+reason the line exists. It traces a file or current line range through local git
+history, identifies its origin and later edits, finds files that repeatedly
+changed beside it, and extracts intent clues from commit messages.
+
+Everything runs locally. No network calls, API keys, or repository writes.
+
+## When to use
+
+- The user asks why a block, function, or file exists
+- The user wants to know who introduced code and what changed afterward
+- A rewrite or refactor needs historical constraints and change risks
+- A workaround, temporary branch, or surprising design choice needs context
+
+## When not to use
+
+- The user only wants raw blame output or a commit list
+- The task is to squash, delete, or rewrite git history
+- The repository is remote and has not been cloned locally
+- The question is about project-wide architecture rather than one file or region
+
+## Gather the target
+
+Get the repository path and tracked file path. Use a line range when the user
+names a current block or function. If either path is missing, ask only for the
+missing value. Do not scan sibling repositories.
+
+Paths should be relative to the repository and use forward slashes. Line ranges
+use inclusive current line numbers such as `40-72`.
+
+## Run the dig
+
+From this skill directory:
+
+```bash
+python3 scripts/archaeologist.py /path/to/repo src/cache.py --lines 40-72 --json
+```
+
+For the complete history of a file, omit `--lines`:
+
+```bash
+python3 scripts/archaeologist.py /path/to/repo src/cache.py --json
+```
+
+The script is read-only. With a range it uses git line-log; without one it uses
+file history with rename following. It also reads current authorship with blame.
+If it rejects a path or range, report that error and ask for a corrected target.
+
+Before interpreting the JSON, read
+`references/reading-git-history.md`. Its confidence rules prevent blame
+ownership, correlation, and commit-message hints from becoming false certainty.
+
+## Read the JSON
+
+- `region`: normalized repository, current and historical paths, mode, range,
+ and co-change threshold
+- `introduced_by`: oldest commit in the selected history
+- `timeline`: commits ordered oldest to newest, with category, changed files,
+ and detected renames
+- `co_changed`: files present beside the target in enough selected commits
+- `authors`: current blamed lines and historical commit counts, kept separate
+- `intent_signals`: issue references, reverts, workarounds, temporary markers,
+ and unfinished-work markers found in commit messages
+
+An empty signal list means the messages do not say why. It does not mean the
+change had no reason.
+
+## Write the report
+
+Turn the JSON into a short "why this code exists" report:
+
+1. **Bottom line.** One or two sentences with the most likely explanation and
+ a confidence label: high, medium, or low.
+2. **Origin.** Introducing hash, date, author, subject, and the neighboring
+ files that make the initial purpose clearer.
+3. **Timeline.** Oldest to newest. Group mechanical edits when they do not
+ change the story, but preserve reverts, fixes, and workarounds.
+4. **Companion files.** Explain repeated co-changes as a coupling clue. Do not
+ treat a one-off file in `changed_files` as a dependency.
+5. **Intent evidence.** Quote short commit subjects or signal words. Label any
+ conclusion beyond those facts as an inference.
+6. **Change risk.** Name the constraints, companion files, and unresolved
+ temporary choices worth checking before an edit.
+
+Keep hashes short in prose, but preserve enough characters to identify them.
+Do not dump the full JSON unless the user asks.
+
+## Evidence rules
+
+- Current blame ownership is not proof of original authorship.
+- The oldest selected commit is the region's introduction, not always the
+ file's first commit.
+- Repeated co-change suggests coupling; it does not prove a dependency.
+- Commit categories are message heuristics, not verified issue types.
+- "Temporary" and "workaround" are strong intent clues, but only the message
+ author or linked discussion can confirm whether the constraint still applies.
+- If the history is thin or messages are vague, say "the history shows" and
+ "likely" instead of inventing a design rationale.
+
+## Follow-ups
+
+End by offering one relevant follow-up, such as:
+
+- "Want me to assess whether this looks deliberate or accidental?"
+- "Want me to map what could break if this region changes?"
+
+For a deliberate-choice question, weigh repeated edits, issue references,
+reverts, and explicit constraint words. For a change-risk question, inspect the
+repeated co-change files and the last behavior-changing commits before proposing
+edits. Do not modify code until the user asks.
+
+## Files
+
+- `scripts/archaeologist.py`: offline git history walker and JSON report builder
+- `references/reading-git-history.md`: interpretation and confidence guide
diff --git a/agent_skills/commit-archaeologist/references/reading-git-history.md b/agent_skills/commit-archaeologist/references/reading-git-history.md
new file mode 100644
index 00000000..22b11cea
--- /dev/null
+++ b/agent_skills/commit-archaeologist/references/reading-git-history.md
@@ -0,0 +1,82 @@
+# Reading git history without inventing intent
+
+The dig report separates facts from signals. Use this guide before turning it
+into a narrative.
+
+## File history and line history answer different questions
+
+File mode uses `git log --follow` and asks how the tracked file evolved. Line
+mode uses git line-log and asks which commits shaped the current selected lines.
+A line-mode timeline can start long after the file was created. Call its oldest
+entry the region's introducing commit, not automatically the file's creator.
+
+Line-log follows patches backward. Large rewrites, copied code, and some renames
+can break the chain. When an origin looks too recent, compare it with file mode
+and say that the earlier ancestry is uncertain.
+
+## Authorship has two meanings
+
+The `authors` list holds both current blamed-line counts and commit counts in the
+selected timeline. Current blame answers who last shaped surviving lines.
+Timeline authorship answers who committed the historical changes. Neither fact
+alone proves who designed the behavior.
+
+Use precise language:
+
+- Strong: "Ada introduced the selected lines in `a1b2c3d`."
+- Strong: "Seven current lines are blamed to Ada."
+- Weak: "Ada designed the system this way." This needs message or issue evidence.
+
+## Timeline categories are routing hints
+
+The script labels messages as `feat`, `fix`, `refactor`, `revert`, `hotfix`,
+`merge`, or `other`. These labels make the narrative easier to scan. They are
+keyword classifications, not proof that a refactor preserved behavior or that a
+commit labeled fix solved the root cause.
+
+Read subject, body, and changed files together. A refactor followed by a revert
+is more informative than either label alone.
+
+## Co-change is correlation
+
+`co_changed` includes files that crossed a threshold within the selected
+timeline. Repetition is useful because a helper changed beside the target in
+several commits for a reason more often than by accident.
+
+Treat it as a clue:
+
+- Repeated test co-changes can reveal the behavior the code protects.
+- Repeated schema or migration co-changes can reveal a data constraint.
+- Repeated configuration co-changes can reveal a deployment constraint.
+- Generated or formatting commits can create meaningless co-change patterns.
+
+Say "often changed with" until the code confirms a dependency.
+
+## Intent signals and confidence
+
+Issue or PR references point to likely external context. Revert, workaround,
+temporary, and TODO words are direct evidence that the commit author framed the
+change that way. They still do not say whether the condition remains true.
+
+Use these confidence levels:
+
+- **High:** explicit constraint language plus repeated supporting changes, or a
+ revert that clearly names the behavior being restored.
+- **Medium:** message category, changed files, and timeline shape agree, but no
+ message states the rationale directly.
+- **Low:** sparse history, generic subjects, bulk rewrites, or conflicting clues.
+
+Keep quotes short and traceable to the commit. When the evidence only shows what
+changed, report what changed and leave the why open.
+
+## Change-risk checklist
+
+Before recommending an edit, check:
+
+1. Did a prior commit try the same change and get reverted?
+2. Do tests, schemas, migrations, or configs repeatedly move with the region?
+3. Does a workaround or temporary marker name an external constraint?
+4. Does current blame hide an older introducing author after a mechanical edit?
+5. Does file mode show ancestry that line mode could not retain?
+
+The safest report names the evidence, the inference, and what would confirm it.
diff --git a/agent_skills/commit-archaeologist/scripts/archaeologist.py b/agent_skills/commit-archaeologist/scripts/archaeologist.py
new file mode 100644
index 00000000..79eb9506
--- /dev/null
+++ b/agent_skills/commit-archaeologist/scripts/archaeologist.py
@@ -0,0 +1,382 @@
+#!/usr/bin/env python3
+"""Reconstruct why a file or line range exists from local git history.
+
+Usage:
+ python3 archaeologist.py REPO FILE [--lines A-B] [--json]
+
+Python 3.8+, stdlib only. Read-only and offline.
+"""
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from collections import Counter, defaultdict
+
+
+LINE_RANGE_RE = re.compile(r"^([1-9][0-9]*)-([1-9][0-9]*)$")
+ISSUE_RE = re.compile(r"(?<![\w/])(?:#[0-9]+|(?:pr|issue|gh)[\s:#-]*[0-9]+)", re.I)
+INTENT_PATTERNS = (
+ ("revert", re.compile(r"\brevert(?:ed|s|ing)?\b", re.I)),
+ ("workaround", re.compile(r"\bwork[ -]?around\b", re.I)),
+ ("temporary", re.compile(r"\b(?:temporary|temporarily|temp)\b", re.I)),
+ ("todo", re.compile(r"\bTODO\b", re.I)),
+)
+
+
+class ArchaeologistError(Exception):
+ """A user-facing validation or git error."""
+
+
+def git(repo, args, required=True):
+ """Run a read-only git command and return stdout."""
+ try:
+ result = subprocess.run(
+ ["git", "-C", repo, *args],
+ capture_output=True,
+ text=True,
+ timeout=30,
+ )
+ except FileNotFoundError as exc:
+ raise ArchaeologistError("git is not installed or is not on PATH") from exc
+ except subprocess.TimeoutExpired as exc:
+ raise ArchaeologistError("git command timed out") from exc
+ if result.returncode != 0 and required:
+ detail = result.stderr.strip() or result.stdout.strip() or "git command failed"
+ raise ArchaeologistError(detail)
+ return result.stdout if result.returncode == 0 else ""
+
+
+def normalize_inputs(repo_arg, file_arg):
+ repo_hint = os.path.abspath(os.path.expanduser(repo_arg))
+ if not os.path.isdir(repo_hint):
+ raise ArchaeologistError("repository path is not a directory: %s" % repo_arg)
+ root = git(repo_hint, ["rev-parse", "--show-toplevel"]).strip()
+ if not root:
+ raise ArchaeologistError("not a git repository: %s" % repo_arg)
+ root = os.path.abspath(root)
+
+ if os.path.isabs(file_arg):
+ candidate = os.path.abspath(os.path.expanduser(file_arg))
+ else:
+ candidate = os.path.abspath(os.path.join(root, file_arg))
+ try:
+ inside = os.path.commonpath([root, candidate]) == root
+ except ValueError:
+ inside = False
+ if not inside:
+ raise ArchaeologistError("file must be inside the repository")
+
+ relative = os.path.relpath(candidate, root).replace(os.sep, "/")
+ tracked = git(root, ["ls-files", "--error-unmatch", "--", relative], required=False)
+ if not tracked.strip():
+ raise ArchaeologistError("file is not tracked at HEAD: %s" % relative)
+ return root, relative
+
+
+def parse_line_range(value):
+ if value is None:
+ return None
+ match = LINE_RANGE_RE.match(value)
+ if not match:
+ raise ArchaeologistError("line range must use positive A-B form, such as 40-72")
+ start, end = int(match.group(1)), int(match.group(2))
+ if start > end:
+ raise ArchaeologistError("line range start must not exceed its end")
+ return start, end
+
+
+def validate_range(repo, path, line_range):
+ if line_range is None:
+ return
+ content = git(repo, ["show", "HEAD:%s" % path])
+ line_count = len(content.splitlines())
+ if line_range[1] > line_count:
+ raise ArchaeologistError(
+ "line range ends at %d, but %s has %d lines at HEAD"
+ % (line_range[1], path, line_count)
+ )
+
+
+def history_hashes(repo, path, line_range):
+ if line_range:
+ selector = "%d,%d:%s" % (line_range[0], line_range[1], path)
+ output = git(repo, ["log", "--format=%H", "--no-patch", "-L", selector])
+ else:
+ output = git(
+ repo,
+ ["log", "--format=%H", "--no-patch", "--follow", "--", path],
+ )
+ newest_first = [line.strip() for line in output.splitlines() if line.strip()]
+ hashes = []
+ seen = set()
+ for commit_hash in reversed(newest_first):
+ if commit_hash not in seen:
+ seen.add(commit_hash)
+ hashes.append(commit_hash)
+ if not hashes:
+ raise ArchaeologistError("no commits found for %s" % path)
+ return hashes
+
+
+def classify_message(subject, body):
+ text = "%s\n%s" % (subject, body)
+ lowered = text.lower()
+ if subject.lower().startswith("merge "):
+ return "merge"
+ if re.search(r"\brevert(?:ed|s|ing)?\b", lowered):
+ return "revert"
+ if re.search(r"\bhot[ -]?fix\b", lowered):
+ return "hotfix"
+ if re.search(r"\b(refactor|cleanup|restructure|rename)\b", lowered):
+ return "refactor"
+ if re.search(r"\b(fix|fixed|fixes|bug|patch)\b", lowered):
+ return "fix"
+ if re.search(r"\b(feat|feature|add|added|introduce|implement)\b", lowered):
+ return "feat"
+ return "other"
+
+
+def changed_file_details(repo, commit_hash):
+ output = git(
+ repo,
+ [
+ "diff-tree", "--root", "--no-commit-id", "--name-status", "-r",
+ "-M", commit_hash, "--",
+ ],
+ )
+ paths = set()
+ renames = []
+ for line in output.splitlines():
+ fields = line.split("\t")
+ if len(fields) >= 3 and fields[0].startswith("R"):
+ old_path, new_path = fields[1], fields[2]
+ paths.update((old_path, new_path))
+ renames.append({"from": old_path, "to": new_path})
+ elif len(fields) >= 2:
+ paths.add(fields[-1])
+ return sorted(paths), renames
+
+
+def intent_signals(commit_hash, subject, body):
+ text = "%s\n%s" % (subject, body)
+ signals = []
+ for match in ISSUE_RE.finditer(text):
+ signals.append({
+ "type": "issue_reference",
+ "commit": commit_hash,
+ "evidence": match.group(0),
+ "subject": subject,
+ })
+ for signal_type, pattern in INTENT_PATTERNS:
+ match = pattern.search(text)
+ if match:
+ signals.append({
+ "type": signal_type,
+ "commit": commit_hash,
+ "evidence": match.group(0),
+ "subject": subject,
+ })
+ return signals
+
+
+def read_commit(repo, commit_hash):
+ fmt = "%H%x00%an%x00%ae%x00%aI%x00%s%x00%b"
+ raw = git(repo, ["show", "-s", "--format=%s" % fmt, commit_hash]).rstrip("\n")
+ parts = raw.split("\x00", 5)
+ if len(parts) != 6:
+ raise ArchaeologistError("could not parse commit metadata for %s" % commit_hash)
+ full_hash, author, email, date, subject, body = parts
+ signals = intent_signals(full_hash, subject, body)
+ files, renames = changed_file_details(repo, full_hash)
+ return {
+ "hash": full_hash,
+ "short_hash": full_hash[:12],
+ "author": author,
+ "email": email,
+ "date": date,
+ "subject": subject,
+ "body": body.strip(),
+ "category": classify_message(subject, body),
+ "changed_files": files,
+ "renames": renames,
+ "intent_signals": [signal["type"] for signal in signals],
+ }, signals
+
+
+def blame_authors(repo, path, line_range):
+ args = ["blame", "--line-porcelain"]
+ if line_range:
+ args.extend(["-L", "%d,%d" % line_range])
+ args.extend(["HEAD", "--", path])
+ output = git(repo, args, required=False)
+ counts = Counter()
+ names = {}
+ current_name = ""
+ current_email = ""
+ for line in output.splitlines():
+ if line.startswith("author "):
+ current_name = line[7:]
+ elif line.startswith("author-mail "):
+ current_email = line[12:].strip("<>")
+ elif line.startswith("\t"):
+ if current_email:
+ key = current_email.lower()
+ counts[key] += 1
+ names[key] = (current_name, current_email)
+ current_name = ""
+ current_email = ""
+ return counts, names
+
+
+def summarize_authors(repo, path, line_range, timeline):
+ line_counts, names = blame_authors(repo, path, line_range)
+ commit_counts = Counter()
+ for entry in timeline:
+ key = entry["email"].lower()
+ commit_counts[key] += 1
+ names.setdefault(key, (entry["author"], entry["email"]))
+ authors = []
+ for key in set(line_counts) | set(commit_counts):
+ name, email = names[key]
+ authors.append({
+ "name": name,
+ "email": email,
+ "current_lines": line_counts[key],
+ "timeline_commits": commit_counts[key],
+ })
+ return sorted(
+ authors,
+ key=lambda author: (
+ -author["current_lines"], -author["timeline_commits"],
+ author["name"].lower(), author["email"].lower(),
+ ),
+ )
+
+
+def historical_paths(path, timeline):
+ aliases = {path}
+ for entry in reversed(timeline):
+ for rename in entry["renames"]:
+ if rename["to"] in aliases:
+ aliases.add(rename["from"])
+ return aliases
+
+
+def summarize_co_changes(path, timeline):
+ threshold = max(2, (len(timeline) + 2) // 3)
+ aliases = historical_paths(path, timeline)
+ commits_by_file = defaultdict(list)
+ for entry in timeline:
+ for changed in entry["changed_files"]:
+ if changed not in aliases:
+ commits_by_file[changed].append(entry["hash"])
+ co_changed = []
+ for changed, commits in commits_by_file.items():
+ if len(commits) >= threshold:
+ co_changed.append({
+ "file": changed,
+ "count": len(commits),
+ "commit_ratio": round(len(commits) / len(timeline), 3),
+ "commits": commits,
+ })
+ return (
+ threshold,
+ sorted(co_changed, key=lambda item: (-item["count"], item["file"])),
+ sorted(aliases),
+ )
+
+
+def build_report(repo, path, line_range):
+ hashes = history_hashes(repo, path, line_range)
+ timeline = []
+ signals = []
+ for commit_hash in hashes:
+ entry, commit_signals = read_commit(repo, commit_hash)
+ timeline.append(entry)
+ signals.extend(commit_signals)
+ threshold, co_changed, aliases = summarize_co_changes(path, timeline)
+ return {
+ "region": {
+ "repo": repo,
+ "file": path,
+ "mode": "lines" if line_range else "file",
+ "lines": (
+ {"start": line_range[0], "end": line_range[1]}
+ if line_range else None
+ ),
+ "co_change_threshold": threshold,
+ "historical_paths": aliases,
+ },
+ "introduced_by": timeline[0],
+ "timeline": timeline,
+ "co_changed": co_changed,
+ "authors": summarize_authors(repo, path, line_range, timeline),
+ "intent_signals": signals,
+ }
+
+
+def print_human(report):
+ region = report["region"]
+ target = region["file"]
+ if region["lines"]:
+ target += ":%d-%d" % (
+ region["lines"]["start"], region["lines"]["end"],
+ )
+ intro = report["introduced_by"]
+ print("COMMIT ARCHAEOLOGIST: %s" % target)
+ print("Introduced by %s %s: %s" % (
+ intro["short_hash"], intro["author"], intro["subject"],
+ ))
+ print("\nTIMELINE")
+ for entry in report["timeline"]:
+ print(" %s %-8s %s" % (
+ entry["short_hash"], entry["category"], entry["subject"],
+ ))
+ print("\nREPEATED CO-CHANGES")
+ if report["co_changed"]:
+ for item in report["co_changed"]:
+ print(" %dx %s" % (item["count"], item["file"]))
+ else:
+ print(" none above threshold")
+ print("\nINTENT SIGNALS")
+ if report["intent_signals"]:
+ for signal in report["intent_signals"]:
+ print(" %s %s %s" % (
+ signal["commit"][:12], signal["type"], signal["evidence"],
+ ))
+ else:
+ print(" none found in commit messages")
+
+
+def main(argv=None):
+ parser = argparse.ArgumentParser(
+ description="Explain why a file or line range exists from local git history.",
+ )
+ parser.add_argument("repo", help="path to a local git repository")
+ parser.add_argument("file", help="tracked file path, relative to the repository")
+ parser.add_argument("--lines", metavar="A-B", help="current line range to trace")
+ parser.add_argument("--json", action="store_true", dest="as_json",
+ help="emit the structured dig report as JSON")
+ args = parser.parse_args(argv)
+
+ try:
+ repo, path = normalize_inputs(args.repo, args.file)
+ line_range = parse_line_range(args.lines)
+ validate_range(repo, path, line_range)
+ report = build_report(repo, path, line_range)
+ except ArchaeologistError as exc:
+ print("error: %s" % exc, file=sys.stderr)
+ return 2
+
+ if args.as_json:
+ print(json.dumps(report, indent=2, sort_keys=True))
+ else:
+ print_human(report)
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/agent_skills/evals/commit-archaeologist/evals.json b/agent_skills/evals/commit-archaeologist/evals.json
new file mode 100644
index 00000000..17b0ea9c
--- /dev/null
+++ b/agent_skills/evals/commit-archaeologist/evals.json
@@ -0,0 +1,38 @@
+{
+ "skill_name": "commit-archaeologist",
+ "evals": [
+ {
+ "id": 1,
+ "prompt": "Why does src/cache.py lines 40-72 exist? Trace who introduced it and what changed later.",
+ "expected_output": "A history report grounded in the local repository, with the introducing commit, chronological timeline, repeated co-changes, and intent evidence.",
+ "expectations": [
+ "The agent runs scripts/archaeologist.py with the user-provided repository, file, line range, and --json",
+ "The report names the introducing commit and presents later modifications from oldest to newest",
+ "Repeatedly co-changed files are separated from one-off neighboring changes",
+ "Intent claims cite commit messages or explicit signals and label inference as inference",
+ "The agent offers to assess whether the choice was deliberate or what could break if the region changes"
+ ]
+ },
+ {
+ "id": 2,
+ "prompt": "Who wrote this function and why? The repo is /work/api and the file is src/retry.py.",
+ "expected_output": "A file-wide dig report that distinguishes current blame ownership from historical commit authorship and explains the likely reason for the function.",
+ "expectations": [
+ "The agent uses only the specified local repository and file",
+ "Current blame ownership and timeline authors are not treated as the same fact",
+ "The narrative includes timeline, co-change, and intent sections",
+ "The answer does not claim certainty when the commit evidence is ambiguous"
+ ]
+ },
+ {
+ "id": 3,
+ "prompt": "Explain the history of this function before I rewrite it.",
+ "expected_output": "The agent asks only for the missing repository, file, or line range, then produces a change-risk oriented history report.",
+ "expectations": [
+ "The agent requests missing path information instead of scanning unrelated repositories",
+ "The report identifies repeated companion files and temporary or workaround signals",
+ "The closing follow-up focuses on deliberate constraints and change risks"
+ ]
+ }
+ ]
+}
diff --git a/agent_skills/evals/commit-archaeologist/test_archaeologist.py b/agent_skills/evals/commit-archaeologist/test_archaeologist.py
new file mode 100644
index 00000000..610c0008
--- /dev/null
+++ b/agent_skills/evals/commit-archaeologist/test_archaeologist.py
@@ -0,0 +1,247 @@
+#!/usr/bin/env python3
+"""Deterministic eval for the commit-archaeologist skill.
+
+Builds a temporary git repository with a known file history, runs the skill's
+offline script, and checks the resulting dig report.
+
+ python3 agent_skills/evals/commit-archaeologist/test_archaeologist.py
+
+Python stdlib plus git only. The fixture never touches the source checkout.
+"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+
+
+SCRIPT = os.path.abspath(os.path.join(
+ os.path.dirname(__file__),
+ "..", "..", "commit-archaeologist", "scripts", "archaeologist.py",
+))
+checks = []
+
+
+def check(name, condition, detail=""):
+ checks.append(bool(condition))
+ status = "PASS" if condition else "FAIL"
+ suffix = " - %s" % detail if detail and not condition else ""
+ print(" %s %s%s" % (status, name, suffix))
+
+
+def git(repo, *args, env=None):
+ result = subprocess.run(
+ ["git", *args], cwd=repo, env=env, capture_output=True, text=True,
+ )
+ if result.returncode != 0:
+ raise RuntimeError(result.stderr.strip() or "git command failed")
+ return result.stdout.strip()
+
+
+def write(repo, path, content):
+ target = os.path.join(repo, path)
+ os.makedirs(os.path.dirname(target), exist_ok=True)
+ with open(target, "w", encoding="utf-8") as handle:
+ handle.write(content)
+
+
+def commit(repo, date, message, files):
+ for path, content in files.items():
+ write(repo, path, content)
+ git(repo, "add", "-A")
+ env = dict(
+ os.environ,
+ GIT_AUTHOR_DATE=date,
+ GIT_COMMITTER_DATE=date,
+ )
+ git(repo, "commit", "-m", message, env=env)
+ return git(repo, "rev-parse", "HEAD")
+
+
+def build_repo(root):
+ repo = os.path.join(root, "fixture")
+ os.makedirs(repo)
+ git(repo, "init", "-q")
+ git(repo, "config", "user.name", "Ada Archaeologist")
+ git(repo, "config", "user.email", EMAIL)
+
+ introduced = commit(
+ repo,
+ "2026-01-01T10:00:00+0000",
+ "feat: introduce calculator #12",
+ {
+ "src/calculator.py": (
+ "def add(values):\n"
+ " return sum(values)\n"
+ ),
+ "docs/decision.md": "Calculator experiment notes.\n",
+ },
+ )
+ refactored = commit(
+ repo,
+ "2026-01-02T10:00:00+0000",
+ "refactor: name the accumulator",
+ {
+ "src/calculator.py": (
+ "def add(values):\n"
+ " total = 0\n"
+ " for value in values:\n"
+ " total += value\n"
+ " return total\n"
+ ),
+ "src/helpers.py": (
+ "def normalize_zero():\n"
+ " return 0\n"
+ ),
+ },
+ )
+ workaround = commit(
+ repo,
+ "2026-01-03T10:00:00+0000",
+ "fix: temporary workaround for empty totals #34",
+ {
+ "src/calculator.py": (
+ "from .helpers import normalize_zero\n\n"
+ "def add(values):\n"
+ " total = 0\n"
+ " for value in values:\n"
+ " total += value\n"
+ " return total if values else normalize_zero()\n"
+ ),
+ "src/helpers.py": (
+ "def normalize_zero():\n"
+ " # Keep the legacy integer return type.\n"
+ " return 0\n"
+ ),
+ },
+ )
+ return repo, [introduced, refactored, workaround]
+
+
+def run(repo, *args, file_path="src/calculator.py"):
+ return subprocess.run(
+ [sys.executable, SCRIPT, repo, file_path, *args],
+ capture_output=True,
+ text=True,
+ )
+
+
+def main():
+ root = tempfile.mkdtemp(prefix="commit-archaeologist-eval-")
+ try:
+ repo, expected_hashes = build_repo(root)
+
+ print("line-range report:")
+ result = run(repo, "--lines", "1-7", "--json")
+ check("script exits cleanly", result.returncode == 0, result.stderr)
+ if result.returncode != 0:
+ return 1
+ report = json.loads(result.stdout)
+
+ check(
+ "region identifies the requested lines",
+ report["region"]["file"] == "src/calculator.py"
+ and report["region"]["lines"] == {"start": 1, "end": 7},
+ str(report.get("region")),
+ )
+ check(
+ "introducing commit is the first commit",
+ report["introduced_by"]["hash"] == expected_hashes[0],
+ report["introduced_by"]["hash"],
+ )
+ timeline_hashes = [entry["hash"] for entry in report["timeline"]]
+ check(
+ "timeline is oldest to newest",
+ timeline_hashes == expected_hashes,
+ str(timeline_hashes),
+ )
+ check(
+ "commit categories follow message intent",
+ [entry["category"] for entry in report["timeline"]]
+ == ["feat", "refactor", "fix"],
+ )
+ co_changed = {entry["file"]: entry for entry in report["co_changed"]}
+ check(
+ "helper is detected as a repeated co-change",
+ co_changed.get("src/helpers.py", {}).get("count") == 2,
+ str(report["co_changed"]),
+ )
+ check(
+ "one-off neighboring files stay below the threshold",
+ "docs/decision.md" not in co_changed,
+ str(report["co_changed"]),
+ )
+ single_commit = run(repo, "--json", file_path="docs/decision.md")
+ single_commit_report = (
+ json.loads(single_commit.stdout) if single_commit.returncode == 0 else {}
+ )
+ check(
+ "single-commit history has no repeated co-changes",
+ single_commit.returncode == 0
+ and single_commit_report.get("co_changed") == []
+ and single_commit_report.get("region", {}).get("co_change_threshold") == 2,
+ single_commit.stderr or str(single_commit_report),
+ )
+ signal_types = {entry["type"] for entry in report["intent_signals"]}
+ check("workaround signal is present", "workaround" in signal_types)
+ check("temporary signal is present", "temporary" in signal_types)
+ check("issue reference signal is present", "issue_reference" in signal_types)
+ check(
+ "blame authorship is summarized",
+ any(
+ author["email"] == EMAIL and author["current_lines"] == 7
+ for author in report["authors"]
+ ),
+ str(report["authors"]),
+ )
+
+ repeat = run(repo, "--lines", "1-7", "--json")
+ check("JSON output is deterministic", repeat.stdout == result.stdout)
+
+ print("file-wide rename and error behavior:")
+ git(repo, "mv", "src/calculator.py", "src/arithmetic.py")
+ git(repo, "commit", "-m", "refactor: rename calculator module")
+ renamed = git(repo, "rev-parse", "HEAD")
+ file_result = run(repo, "--json", file_path="src/arithmetic.py")
+ file_report = json.loads(file_result.stdout) if file_result.returncode == 0 else {}
+ check("file-wide mode exits cleanly", file_result.returncode == 0, file_result.stderr)
+ check(
+ "file-wide mode uses follow history",
+ file_report.get("region", {}).get("mode") == "file"
+ and [entry["hash"] for entry in file_report.get("timeline", [])]
+ == expected_hashes + [renamed],
+ )
+ check(
+ "a target's old name is not reported as a co-change",
+ all(
+ entry["file"] != "src/calculator.py"
+ for entry in file_report.get("co_changed", [])
+ ),
+ str(file_report.get("co_changed")),
+ )
+
+ invalid = run(
+ repo, "--lines", "7-1", "--json", file_path="src/arithmetic.py",
+ )
+ check("invalid line range fails", invalid.returncode != 0)
+ check(
+ "invalid line range explains the problem without a traceback",
+ "line range" in invalid.stderr.lower() and "traceback" not in invalid.stderr.lower(),
+ invalid.stderr,
+ )
+
+ print()
+ if all(checks):
+ print("PASS - %d/%d checks" % (len(checks), len(checks)))
+ return 0
+ print("FAIL - %d/%d checks passed" % (sum(checks), len(checks)))
+ return 1
+ finally:
+ shutil.rmtree(root, ignore_errors=True)
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/agent_skills/evals/commit-archaeologist/trigger-cases.json b/agent_skills/evals/commit-archaeologist/trigger-cases.json
new file mode 100644
index 00000000..2efc3039
--- /dev/null
+++ b/agent_skills/evals/commit-archaeologist/trigger-cases.json
@@ -0,0 +1,42 @@
+{
+ "skill": "commit-archaeologist",
+ "purpose": "Trigger behavior spec. CI checks that positive prompts match the skill description more strongly than near-misses.",
+ "cases": [
+ {
+ "id": "why-code-exists",
+ "prompt": "why does this code exist",
+ "should_trigger": true,
+ "assert": "Traces the relevant lines through local git history and explains the evidence for their likely intent."
+ },
+ {
+ "id": "who-wrote-function",
+ "prompt": "who wrote this function and why",
+ "should_trigger": true,
+ "assert": "Reports current authorship, the introducing commit, later changes, and likely intent."
+ },
+ {
+ "id": "explain-function-history",
+ "prompt": "explain the history of this function",
+ "should_trigger": true,
+ "assert": "Builds a chronological narrative for the function from local git evidence."
+ },
+ {
+ "id": "near-miss-git-blame",
+ "prompt": "run git blame on src/parser.py",
+ "should_trigger": false,
+ "assert": "Does not trigger for a direct request to print blame output without intent analysis."
+ },
+ {
+ "id": "near-miss-delete-history",
+ "prompt": "delete this file's history",
+ "should_trigger": false,
+ "assert": "Does not trigger for destructive history rewriting."
+ },
+ {
+ "id": "near-miss-squash",
+ "prompt": "squash my commits",
+ "should_trigger": false,
+ "assert": "Does not trigger for commit rewriting."
+ }
+ ]
+}