git-codebase-preflight

name	git-codebase-preflight
description	Audits a repository through git history before reading source files. Use when inheriting a codebase, starting a review, planning a refactor, or deciding which files to inspect first.
license	MIT
metadata	{"author":"Anton Novoselov","version":"1.0"}

Inspect a repository through git history before opening source files, so you can decide where to look first and what kinds of risks to expect.

Review process:

1. Run the churn hotspot commands from references/churn-hotspots.md.
2. Run the ownership commands from references/ownership-signals.md.
3. Run the bug-cluster commands from references/bug-clusters.md.
4. Run the commit-activity commands from references/activity-trends.md.
5. Run the firefighting commands from references/firefighting-signals.md.
6. Cross-reference the results and rank the first files, folders, teams, and time periods to inspect.

If doing partial work, load only the relevant reference files.

Core Instructions

• Start with git history before opening code when the user is new to the repository, asks for an audit, or wants to plan a refactor.
• Prefer a 6 to 12 month window for active repositories and a 1 year window for stable repositories, unless the user specifies otherwise.
• Treat churn as a signal, not a verdict. High churn may reflect active product work rather than bad architecture.
• Treat authorship counts as directional, not absolute. Squash-merge workflows can hide real contributors.
• Treat bug-fix commit filtering as approximate. Weak commit messages reduce signal quality.
• Cross-reference churn hotspots with bug clusters before declaring a file high-risk.
• Use directory-level churn when file-level results are too noisy or when the user needs a faster first pass.
• Use new-file and deleted-file patterns to distinguish growth from instability.
• Use recent per-file authorship to see who currently carries a risky area.
• Use activity by month to infer momentum, staffing changes, and release batching, but call these interpretations hypotheses rather than facts.
• Use large recent commits as inspection targets when you suspect risky big-bang changes.
• Use revert and hotfix frequency as a proxy for delivery stress, testing gaps, or weak release processes.
• After the git pass, recommend a concrete reading order: the first files, folders, or time periods to inspect next.
• If the user asks for a review, findings should focus on risk signals and next inspection targets, not generic repository summaries.
• By default, create git-codebase-preflight-report.md in the current working directory.
• Also return a concise summary in chat unless the user explicitly asks for file-only output.
• If the user explicitly asks not to generate a file, do the analysis in chat only.

Output Format

If the user asks for a preflight review, organize findings into these sections:

1. Hotspots - top churn files and any overlap with bug-fix patterns.
2. Ownership - key contributors, whether they are still active, and any bus-factor concerns.
3. Change Shape - whether the area is growing, being deleted, or getting reorganized.
4. Momentum - what the monthly commit pattern suggests.
5. Firefighting - whether reverts or hotfixes appear normal or frequent.
6. Next Reads - the first files or areas to inspect in code.

For each important signal:

1. Include the exact command used.
2. Summarize the output in plain language.
3. State the confidence level or caveat if the signal is noisy.
4. Recommend what to inspect next because of it.

If the user asks you to run this workflow on the current repository, run the commands directly instead of returning a generic checklist.

Default deliverable behavior:

1. Create git-codebase-preflight-report.md with the full structured write-up.
2. Return a concise summary in chat with the highest-signal findings.
3. Skip creating the file only if the user explicitly asks for a chat-only run.

If the output is large:

1. Summarize the most important findings in chat.
2. Avoid dumping raw command output unless it materially supports the conclusion.
3. Put the detailed findings in git-codebase-preflight-report.md.

Example output:

Hotspots

app/services/billing.rb is both high-churn and bug-adjacent.

Command:

git log --format=format: --name-only --since="1 year ago" | sort | uniq -c | sort -nr | head -20

Interpretation:

• This file appears near the top of the churn list, which means the team changes it repeatedly.
• If the same file also appears in bug-fix commits, it should be the first code file to inspect.

Ownership

One contributor dominates the history, but is missing from recent activity.

Command:

git shortlog -sn --no-merges --since="6 months ago"

Interpretation:

• This suggests knowledge concentration risk.
• Confirm whether squash merges are masking real authorship before drawing a stronger conclusion.

Next Reads

1. app/services/billing.rb
2. app/models/subscription.rb
3. Deployment or release automation touching rollback paths

End of example.

References

• references/churn-hotspots.md - commands and heuristics for identifying the most frequently changed files.
• references/ownership-signals.md - commands and caveats for contributor concentration and recent maintainers.
• references/bug-clusters.md - commands for mapping bug-fix commits to likely defect hotspots.
• references/activity-trends.md - monthly commit trend analysis and interpretation patterns.
• references/firefighting-signals.md - revert, hotfix, emergency, and rollback signals in recent history.