git-history-analysis

Git history analysis

Contract

Inputs

• Repository path: required. Defaults to the current working directory when omitted. Only analyze the user's application repositories; do not analyze this agent's own repository.
• Time period: optional. Defaults to the last 2 weeks (14 days).
• Filters: optional path or branch filters to narrow the scope.

Procedure

1. Bind scope before mutation: confirm the repository path and time period. If the path is ambiguous or absent and no default is acceptable, stop and ask; do not guess. Done when: the repository path and time period are confirmed, or the run stopped to ask.
2. Verify the path is a git repository with commits in the requested range. If not, stop and report the blocker; do not write a partial report. Done when: the path is a git repository with commits in range, or the run stopped with the blocker reported.
3. Collect commit history from the repository root, adjusting --since to the requested period and appending -- <filters> when path filters are specified:

   git --no-pager log --since="2 weeks ago" --pretty=format:"%h|%ad|%s" --date=short --stat -- <filters>
   

   Omit -- <filters> when no path filters are supplied. Done when: commit history collected for the requested period from the repository root.
4. Collect active branches (work in progress), filtering out merged branches and dynamically resolving the default branch instead of hardcoding main:

   default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)
   git --no-pager branch -r --no-merged origin/$default_branch --sort=-committerdate | grep -E "<filters>" | head -20
   

   Apply branch-name filters before head so filtering cannot discard branches beyond the first twenty. Path filters are a different concern: collect them with git log --all --oneline -- <paths> in their own step, never by grepping branch names. Done when: active unmerged branches listed, sorted by most recent commit.
5. Collect recent merges to the default branch (completed work), dynamically resolving the default branch and appending -- <filters> when path filters are specified:

   default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)
   git --no-pager log --since="2 weeks ago" --merges --pretty=format:"%h|%ad|%s" --date=short origin/$default_branch -- <filters>
   

   Omit -- <filters> when no path filters are supplied. Done when: recent merges to the default branch collected for the requested period.
6. Categorize commits by conventional-commit prefix: feat: features, fix: bug fixes, refactor: code improvements, docs: documentation, test: testing, chore: maintenance. Adapt the prefix set when the repository uses different conventions. Done when: every commit is categorized by prefix (adapted to the repo's conventions).
7. Group commits by directory or component to identify the most active areas. Done when: commits grouped by directory/component with active areas identified.
8. Surface patterns: which features receive the most attention, whether any area shows high bug-fix activity, and the balance between new features and maintenance. Done when: patterns surfaced across features, bug-fix activity, and feature/maintenance balance.
9. Note in-progress work from active branches not yet merged to the default branch. Done when: in-progress work from unmerged active branches noted.
10. Do not attribute work to individuals. Omit author names from the report; describe work by branch, component, and commit type. Done when: the report contains no author names; work described by branch, component, and commit type.
11. Write the report to reports/git_history_analysis/git_analysis_YYYY-MM-DD.md using the Output format. Done when: the report file exists at the dated path using the Output structure.
12. If the user explicitly requests a Slack summary, confirm the destination and post only after explicit human confirmation. This branch is optional and is not required for the done predicate. Done when: a Slack summary is posted only after explicit human confirmation, or the branch is skipped.