/git-archaeology

name: git-archaeology
description: Layer 1 skill for mining git history for behavioral intelligence. Repository overview, commit message mining, PR/MR description extraction, blame-based maintenance heat maps, issue tracker cross-referencing. Loaded by the analyzer agent during Layer 1.

Git Archaeology Methodology

Extract behavioral intelligence from version control history. Commit messages, PR descriptions, blame annotations, and issue references encode design decisions, behavioral changes, and maintenance patterns that no other source captures.

When to Use This Mode

Git archaeology activates when:

• The target is a git repository (or has a `.git` directory)
• The discovery inventory identifies a git repository with meaningful commit history
• Other modes discover a git repository during analysis

This mode runs independently of all other intelligence sources. It requires only access to the git repository and optionally to a GitHub/GitLab remote. All output is **RAW** (commit messages and PR descriptions may reference proprietary internals).

Why Git History Matters

Source code tells you what the system does NOW. Git history tells you:

• **What changed and why** -- commit messages encode intent that is invisible in the current code
• **What broke and how it was fixed** -- fix commits reveal failure modes and edge cases
• **What was deliberately removed** -- reverted features and deleted code reveal abandoned behaviors
• **Where maintenance concentrates** -- frequently modified files signal complexity and instability
• **What decisions were debated** -- PR descriptions capture design trade-offs that never appear in documentation

Phase 1: Repository Overview

**Goal:** Establish the scope, age, and shape of the project.

# Commit count and date range
echo "Total commits: $(git rev-list --count HEAD)"
echo "First commit: $(git log --reverse --format='%ai' | head -1)"
echo "Latest commit: $(git log -1 --format='%ai')"

# Contributors
git shortlog -sn --no-merges | head -20

# Active branches
git branch -r --sort=-committerdate | head -20

# Tags (releases)
git tag --sort=-version:refname | head -20

# Commit frequency (commits per month, last 12 months)
for i in $(seq 0 11); do
  month=$(date -d "$i months ago" +%Y-%m 2>/dev/null || date -v-${i}m +%Y-%m)
  count=$(git rev-list --count --after="${month}-01" --before="${month}-31" HEAD 2>/dev/null || echo "0")
  echo "$month: $count"
done

# Top-level directory structure at HEAD
git ls-tree --name-only HEAD

Write to `workspace/raw/project-history/overview.md`.

Phase 2: Commit Message Mining

**Goal:** Extract behavioral claims from commit messages. Commit messages that describe features, fixes, and breaking changes encode behavioral contracts.

2.1 Feature Commits

# Conventional commits: feat
git log --oneline --grep="^feat" --no-merges | head -100

# Keywords indicating new behavior
git log --oneline --grep="add\|implement\|introduce\|support\|enable" -i --no-merges | head -100

For each feature commit, extract:

• What behavior was added (the claim)
• When it was added (the commit date, for version context)
• The commit SHA (for provenance)

2.2 Fix Commits

# Conventional commits: fix
git log --oneline --grep="^fix" --no-merges | head -100

# Keywords indicating bug fixes
git log --oneline --grep="fix\|bug\|repair\|correct\|resolve\|patch" -i --no-merges | head -100

Fix commits are especially valuable because they reveal:

• A behavior that was WRONG (the bug)
• A behavior that is now CORRECT (the fix)
• Edge cases that the original implementation missed

2.3 Breaking Change Commits

# Conventional commits: breaking
git log --oneline --grep="BREAKING" --no-merges | head -50

# Keywords indicating behavioral changes
git log --oneline --grep="breaking\|deprecat\|remov\|migration\|upgrade" -i --no-merges | head -50

Breaking changes reveal behavioral contracts that were considered important enough to announce their violation.

2.4 Detailed Message Extraction

For high-value commits (features, fixes, breaking changes), read the full commit message:

# Full message for a specific commit
git log -1 --format='%H%n%ai%n%an%n%n%B' <commit-sha>

Extract behavioral claims from the message body. Many commit messages contain:

• **Before/after descriptions** -- explicit behavioral contract changes
• **Issue references** -- links to detailed context
• **Test descriptions** -- what was verified
• **Migration instructions** -- how behavior shifted

Write to `workspace/raw/project-history/behavioral-claims.md`.

Provenance for Commit-Derived Claims

- The `--output csv` flag was added in v2.3
  <!-- cite: source=git-history, ref=abc1234, confidence=inferred, agent=git-archaeologist -->

Phase 3: PR/MR Description Mining

**Goal:** Extract behavioral intelligence from pull request and merge request descriptions. PR descriptions often contain the richest behavioral context: motivation, design decisions, testing notes, and review discussions.

3.1 GitHub PRs

# List merged PRs (most recent first)
gh pr list --state merged --limit 100 --json number,title,body,mergedAt,labels

# View a specific PR with full body and comments
gh pr view <number> --json title,body,comments,reviews,labels,mergedAt

# Search PRs by keyword
gh pr list --state merged --search "authentication" --limit 20 --json number,title,body

3.2 GitLab MRs

If the remote is GitLab rather than GitHub:

# List merged MRs
glab mr list --state merged --per-page 100

# View a specific MR
glab mr view <number>

3.3 What to Extract from PRs/MRs

For each PR/MR, extract:

• **Motivation** -- why was this change made? What problem does it solve?
• **Design decisions** -- what alternatives were considered? Why was this approach chosen?
• **Testing notes** -- what was tested? How was it verified?
• **Review comments** -- what concerns were raised?