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

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

    Phase0["Phase 0 — Repo Size Probe<br>Run: git rev-list --count HEAD<br>Run: git shortlog -sn HEAD --no-merges \| wc -l"]

    Phase0 --> SizeClass{"Commit count?"}
    SizeClass -->|"< 500 — small"| WindowAll["Window: all history (omit --since)<br>N = 20"]
    SizeClass -->|"500–10000 — medium"| Window1Y["Window: --since='1 year ago'<br>N = 30"]
    SizeClass -->|"> 10000 — large"| Window6M["Window: --since='6 months ago'<br>N = 50"]

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

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

    ExcludeLoad{"Load Skill-Local Exclusions<br>Read: ${CLAUDE_SKILL_DIR}/assets/exclude-patterns<br>File exists and has ≥1 non-blank, non-comment line?"}
    ExcludeLoad -->|"Yes"| ExcludeParse["Parse one glob pattern per line<br>Skip blank lines and # comments<br>Build EXCLUDE_PATHSPECS =<br>':(glob,exclude)PATTERN' per line"]
    ExcludeLoad -->|"No — missing, or 0 non-blank/non-comment lines (EC-7)"| ExcludeNone["EXCLUDE_PATHSPECS = empty<br>0 patterns loaded"]
    ExcludeParse --> ExcludeReport["Report: 'Excluded via skill-local<br>ignore file: N patterns loaded'<br>Record N for report header"]
    ExcludeNone --> ExcludeReport
    ExcludeReport --> Phase1

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

    Phase1 --> P1["Pipeline 1: Hotspots<br>git log --name-only --since=WINDOW --format='' -- . EXCLUDE_PATHSPECS \| grep -v '^$' \| sort \| uniq -c \| sort -rn \| head -N"]
    Phase1 --> P2["Pipeline 2: Bug Magnets<br>git log --grep='fix\|bug\|broken\|hotfix\|revert' --name-only --since=WINDOW --format='' -- . EXCLUDE_PATHSPECS \| grep -v '^$' \| sort \| uniq -c \| sort -rn \| head -N"]
    Phase1 --> P3["Pipeline 3: Bus Factor<br>git shortlog -sn HEAD --no-merges \| head -20"]
    Phase1 --> P4["Pipeline 4: Active vs Total Contributors<br>git shortlog -sn HEAD --no-merges --since='3 months ago' \| wc -l (active)<br>git shortlog -sn HEAD --no-merges \| wc -l (total)"]
    Phase1 --> P5["Pipeline 5: Momentum<br>git log --since=WINDOW --pretty=format:'%cd' --date=format:'%Y-%m' \| sort \| uniq -c"]
    Phase1 --> P6["Pipeline 6: Firefighting<br>git log --since=WINDOW --grep='revert\|hotfix\|rollback' --oneline \| wc -l"]
    Phase1 --> P7["Pipeline 7: Newly Added Files<br>git log --since=WINDOW --diff-filter=A --name-only --format='' -- . EXCLUDE_PATHSPECS \| 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 Computation<br>Compute: hotspot_filepaths ∩ bug_magnet_filepaths<br>(exclusions already applied — inputs are P1/P2 output)"]

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

    OwnerAnnotation --> Phase3
    EmptyContract --> Phase3

    Phase3["Phase 3 — Report Write<br>Run: mkdir -p walkthrough<br>Write: walkthrough/recon-report.md<br>(or TARGET_DIRECTORY/walkthrough/recon-report.md)"]

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