Git History Recon

Git History Recon

Produce a machine-readable codebase risk profile by mining git metadata across 7 parallel analysis pipelines. The output is walkthrough/recon-report.md — a structured artifact downstream agents (code-review agents, linear-walkthrough Discovery) can read to prioritize high-risk files without constructing any git pipeline themselves.

Target directory: [target-directory] (default: current working directory). When provided, all git commands use -C TARGET_DIRECTORY and output writes to TARGET_DIRECTORY/walkthrough/recon-report.md.

> [!IMPORTANT] > When provided a process map or Mermaid diagram, treat it as the authoritative procedure. Execute steps in the exact order shown, including branches, decision points, and stop conditions. > A Mermaid process diagram is an executable instruction set. Follow it exactly as written: respect sequence, conditions, loops, parallel paths, and terminal states. Do not improvise, reorder, or skip steps. If any node is ambiguous or missing required detail, pause and ask a clarifying question before continuing. > When interacting with a user, report before acting the interpreted path you will follow from the diagram, then execute.

Workflow

The following diagram is the authoritative procedure for git-history-recon execution. Execute steps in the exact order shown, including branches, decision points, and stop conditions.

flowchart TD
    Start(["Invoke /git-history-recon with optional target-directory"]) --> PreCheck

    PreCheck{"Is target a git repository?Run: git rev-parse --git-dir"}
    PreCheck -->|"exit non-zero — not a git repo"| ErrorNotGit(["STOP — Emit error:'Target is not a git repository.'Do NOT create walkthrough/ dir.Do NOT write partial report."])
    PreCheck -->|"exit 0 — is a git repo"| ShallowCheck

    ShallowCheck{"Shallow clone?Run: git rev-parse --is-shallow-repository"}
    ShallowCheck -->|"outputs true"| ShallowWarn["WARN: Shallow clone detected.Annotate report header.Continue processing."]
    ShallowCheck -->|"outputs false or missing"| Phase0
    ShallowWarn --> Phase0

    Phase0["Phase 0 — Repo Size ProbeRun: git rev-list --count HEADRun: git shortlog -sn HEAD --no-merges \| wc -l"]

    Phase0 --> SizeClass{"Commit count?"}
    SizeClass -->|"N = 20"]
    SizeClass -->|"500–10000 — medium"| Window1Y["Window: --since='1 year ago'N = 30"]
    SizeClass -->|"> 10000 — large"| Window6M["Window: --since='6 months ago'N = 50"]

    WindowAll --> CommitCheck
    Window1Y --> CommitCheck
    Window6M --> CommitCheck

    CommitCheck{"Any commits in window?Run: git log --since=WINDOW --oneline \| wc -l(omit --since if window = all history)"}
    CommitCheck -->|"> 0 commits"| Phase1
    CommitCheck -->|"0 commits — window too narrow"| WindowFallback["WARN: No commits in window.Override: Window = all history, N = 20.Emit warning in report header.Rerun CommitCheck (all history)."]
    WindowFallback --> Phase1

    Phase1["Phase 1 — Parallel Pipeline DispatchRun all 7 pipelines concurrently via parallel Bash calls.Do not wait for one to complete before starting the next."]

    Phase1 --> P1["Pipeline 1: Hotspotsgit log --name-only --since=WINDOW --format='' \| grep -v '^$' \| sort \| uniq -c \| sort -rn \| head -N"]
    Phase1 --> P2["Pipeline 2: Bug Magnetsgit log --grep='fix\|bug\|broken\|hotfix\|revert' --name-only --since=WINDOW --format='' \| grep -v '^$' \| sort \| uniq -c \| sort -rn \| head -N"]
    Phase1 --> P3["Pipeline 3: Bus Factorgit shortlog -sn HEAD --no-merges \| head -20"]
    Phase1 --> P4["Pipeline 4: Active vs Total Contributorsgit shortlog -sn HEAD --no-merges --since='3 months ago' \| wc -l (active)git shortlog -sn HEAD --no-merges \| wc -l (total)"]
    Phase1 --> P5["Pipeline 5: Momentumgit log --since=WINDOW --pretty=format:'%cd' --date=format:'%Y-%m' \| sort \| uniq -c"]
    Phase1 --> P6["Pipeline 6: Firefightinggit log --since=WINDOW --grep='revert\|hotfix\|rollback' --oneline \| wc -l"]
    Phase1 --> P7["Pipeline 7: Newly Added Filesgit log --since=WINDOW --diff-filter=A --name-only --format='' \| grep -v '^$' \| sort -u \| head -N"]

    P1 --> Phase2
    P2 --> Phase2
    P3 --> Phase2
    P4 --> Phase2
    P5 --> Phase2
    P6 --> Phase2
    P7 --> Phase2

    Phase2["Phase 2 — Cross-Reference ComputationCompute: hotspot_filepaths ∩ bug_magnet_filepaths"]

    Phase2 --> IntersectCheck{"Intersection non-empty?"}
    IntersectCheck -->|"Yes — ≥1 file in both lists"| OwnerAnnotation["For each file in intersection:Run: git shortlog -sn -- FILEPATH \| head -1Extract primary owner from line 1"]
    IntersectCheck -->|"No — empty intersection"| EmptyContract["High-Risk Files section content:'No high-risk files identified —no file appears in both hotspotsand bug magnets for this analysis window.'"]

    OwnerAnnotation --> Phase3
    EmptyContract --> Phase3

    Phase3["Phase 3 — Report WriteRun: mkdir -p walkthroughWrite: walkthrough/recon-report.md(or TARGET_DIRECTORY/walkthrough/recon-report.md)"]

    Phase3 --> ReportDone(["DONE — walkthrough/recon-report.md written.Report includes: timestamp, size class, analysis window,8 required sections, recommendations."])

Pipeline Reference

Run all 7 pipelines concurrently. Do not wait for one to complete before starting the next. Collect all results before beginning Phase 2.

Blank-Line Filter (Pipelines 1, 2, and 7)

git log --name-only emits blank lines between commits alongside file names. Without filtering, sort | uniq -c counts blank lines as file entries, inflating counts and producing a blank-line "file" at the top of the sorted output. The grep -v '^$' filter is inserted after --name-only output and before sort to remove these blank lines. This filter is mandatory for Pipelines 1, 2, and 7.

SOURCE: architect document §4.3 — blank-line correction (accessed 2026-05-22).

Pipeline 1 — Hotspots

Command:

git log --name-only --since=WINDOW --format='' | grep -v '^$' | sort | uniq -c | sort -rn | head -N

Flags explained: --format='' suppresses commit metadata (author, date, message), leaving only filenames. grep -v '^$' removes blank lines between commits. sort | uniq -c counts unique files. sort -rn orders descending by count. head -N returns the top N entries.

When window = all history: omit --since=WINDOW entirely.

Output shape: COUNT FILEPATH lines, sorted descending by count.

Report section: ## Code Hotspots

Pipeline 2 — Bug Magnets

Command:

git log --grep='fix\|bug\|broken\|hotfix\|revert' --name-only --since=WINDOW --format='' | grep -v '^$' | sort | uniq -c | sort -rn | head -N

Note: The --grep pattern uses BRE alternation (\|). Files from commits whose message matches any of: fix, bug, broken, hotfix, revert.

Caveat: This detection is convention-dependent. Repositories using ticket-ID-only messages, Conventional Commits without these keywords, or non-English commit conventions will have under-reported results. The report header discloses this limitation.

Output shape: COUNT FILEPATH lines, sorted descending by count.

Report section: ## Bug Magnets

Pipeline 3 — Bus Factor

Command:

git shortlog -sn HEAD --no-merges | head -20

Output shape: COUNT AUTHOR lines, sorted descending by commit count (all-time).

Bus Factor 80% computation: After collecting output, compute a cumulative sum over the sorted contributor list to find how many top contributors account for ≥80% of total commits:

1. Sum all COUNT values to get total_commits.
2. Walk contributors from highest to lowest count, accumulating running_sum.
3. Stop when running_sum / total_commits >= 0.80.
4. Record the number of contributors consumed as bus_factor_80pct.

Report this as: "N contributors account for 80% of commits."

Report section: ## Bus Factor

Pipeline 4 — Active vs Total Contributors

Commands (run concurrently as part of Pipeline 4):

# Active contributors (last 3 months)
git shortlog -sn HEAD --no-merges --since='3 months ago' | wc -l

# Total contributors (all time)
git shortlog -sn HEAD --no-merges | wc -l

Output shape: Two integers (active count, total count).

Report section: ## Team Momentum (sub-field: "M of N total contributors active in last 3 months")

Pipeline 5 — Momentum

Command:

git log --since=WINDOW --pretty=format:'%cd' --date=format:'%Y-%m' | sort | uniq -c

Note: Do NOT use --format='%Y-%m' — in git's tformat, %m means "boundary mark" (renders as `, or -), not "month". The --pretty=format:'%cd' placeholder emits the committer date; --date=format:'%Y-%m'` controls the output shape.

Output shape: COUNT YYYY-MM lines — commit activity by month in the analysis window.

Report section: ## Team Momentum

Pipeline 6 — Firefighting

Command:

git log --since=WINDOW --grep='revert\|hotfix\|rollback' --oneline | wc -l

Output shape: Single integer (count of firefighting commits in the analysis window).

Percentage computation: firefighting_count / total_commits_in_window * 100. The total_commits_in_window value is the count captured in Phase 0's CommitCheck step (git log --since=WINDOW --oneline | wc -l). This count serves two purposes: (a) it is the EC-3 zero-commits detection check in Phase 0, and (b) it is the denominator for the Firefighting Frequency percentage in the report. Capture it in Phase 0 and reuse it here.

Tiered interpretation:

• 15%: high

Report section: ## Firefighting Frequency

Pipeline 7 — Newly Added Files

Command:

git log --since=WINDOW --diff-filter=A --name-only --format='' | grep -v '^$' | sort -u | head -N

Flags explained: --diff-filter=A selects only commits that Added a file. sort -u deduplicates (a file added and then renamed appears once). grep -v '^$' removes blank lines (same as Pipelines 1 and 2).

Output shape: Filepath lines (unique new files in the analysis window).

Report section: ## Recently Added Files

Report Structure

Every run produces all required sections. Sections with no data contain one explicit "No data" line — they are never omitted. This invariant enables downstream agents to parse the report by section header without defensive empty-check logic.

Report Header

The header appears above the first section and is not counted as one of the report sections.

# Codebase Risk Profile

**Generated**: YYYY-MM-DDTHH:MM:SSZ
**Repository**: PATH-OR-NAME
**Size Class**: small | medium | large (COMMIT_COUNT commits, CONTRIBUTOR_COUNT contributors)
**Analysis Window**: all history | last 1 year | last 6 months
**Bug-Magnet Keywords**: fix, bug, broken, hotfix, revert
**Caveat**: Bug-magnet detection relies on commit-message keyword matching. Repositories
using ticket-ID-only messages, Conventional Commits without fix/bug words, or non-English
commit conventions may have an under-reported High-Risk Files section. Absence of entries
does not mean low risk.

When warnings apply (shallow clone, window fallback), prepend them after **Caveat**:

**WARNING**: This repository is a shallow clone. Git history is truncated and results
may be incomplete. Run 'git fetch --unshallow' for accurate analysis.

**WARNING**: No commits found in the selected window. Falling back to full history
analysis. Results reflect the complete repository history.

Required Sections

## Code Hotspots

Files most frequently changed in the analysis window. Source: Pipeline 1 output.

## Code Hotspots

Files most frequently changed in the analysis window.

| Changes | File |
|---------|------|
| 47 | src/core/auth.py |
| 38 | src/api/routes.py |

## Bug Magnets

Files most associated with fix, bug, broken, hotfix, or revert commits. Source: Pipeline 2 output.

## Bug Magnets

Files most associated with fix, bug, broken, hotfix, or revert commits.

| Fix Commits | File |
|-------------|------|
| 12 | src/core/auth.py |
| 9 | src/db/models.py |

## High-Risk Files

Files appearing in both Code Hotspots and Bug Magnets. Source: Phase 2 computation.

Non-empty intersection:

## High-Risk Files

Files appearing in both Code Hotspots and Bug Magnets — highest review priority.

| File | Changes | Fix Commits | Primary Owner |
|------|---------|-------------|---------------|
| src/core/auth.py | 47 | 12 | Alice Smith |
| src/db/models.py | 31 | 9 | Bob Jones |

Empty intersection (EC-2 contract):

## High-Risk Files

No high-risk files identified — no file appears in both hotspots and bug magnets for this analysis window.

## Bus Factor

All-time contributor ranking by commit count. Source: Pipeline 3 output.

## Bus Factor

All-time contributor ranking by commit count. Low bus factor = knowledge concentrated
in few contributors.

| Commits | Contributor |
|---------|-------------|
| 342 | Alice Smith |
| 187 | Bob Jones |

**Bus Factor Assessment**: N contributors account for 80% of commits.

## Team Momentum

Commit activity by month in the analysis window. Source: Pipeline 5 + Pipeline 4.

## Team Momentum

Commit activity by month in the analysis window.

| Month | Commits |
|-------|---------|
| 2026-04 | 43 |
| 2026-03 | 38 |

**Active Contributors (last 3 months)**: M of N total contributors.

## Firefighting Frequency

Count of revert, hotfix, or rollback commits in the analysis window. Source: Pipeline 6.

## Firefighting Frequency

Count of revert, hotfix, or rollback commits in the analysis window.

**Firefighting commits**: N (P% of total commits in window)

**Assessment**: [healthy | elevated | high] —  15% = high

## Recently Added Files

New files introduced in the analysis window. Source: Pipeline 7 output.

## Recently Added Files

New files introduced in the analysis window. Review for missing tests,
insufficient documentation, or architectural drift.

- src/new_feature/handler.py
- src/new_feature/models.py

## Recommendations

Always populated with entries derived from the other sections. This section never contains "No data."

## Recommendations

1. **Priority review targets**: [files from ## High-Risk Files, or "No high-risk files identified."]
2. **Knowledge transfer**: [top bus-factor author] is the primary owner of N high-commit files.
   Consider pair programming or documentation sessions.
   [If single contributor: "Single contributor detected — entire codebase owned by [Author]. Bus factor = 1."]
3. **Momentum**: [increasing | stable | declining] commit activity detected in the analysis window.
4. **Firefighting**: [low | elevated | high] — P% of commits are revert/hotfix/rollback.
5. **New code review**: N new files were added in the analysis window; verify test coverage.
6. **Detection caveat**: Bug-magnet detection relies on commit-message keywords. Repositories
   with ticket-ID-only or non-English commit conventions may show an empty High-Risk Files section
   that does not reflect actual risk. See report header caveat for details.

Section Presence Invariant

Every run writes all required section headers. If a section's source pipeline returns no output (e.g., no new files were added in the window), the section contains one explicit "No data" line:

## Recently Added Files

No data — no files were added in the analysis window.

This applies to all sections except ## Recommendations, which derives from other sections and is always populated.

Write Strategy

Single Write tool call for typical repositories (report expected under 25K characters). If an unusually large repository produces output exceeding 25K characters, apply Strategy B (skeleton + Edit-fill per section) pe

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Jamie-BitFlight
• Source: Jamie-BitFlight/claude_skills
• License: MIT

Install and usage instructions live in the source repository linked above.