Git history analysis
Contract
| Field |
Bound contract |
| Trigger |
User asks about recent engineering work, what the team is working on, or planning or roadmap preparation. |
| Authority |
Human-gated: previews the Slack destination and posting consequence before the optional remote Slack post; otherwise reversible local: writes only a report under reports/git_history_analysis/; rollback is deleting the report. No remote mutation. No force-push or PR creation. |
| Side effect |
Writes a categorized commit-breakdown report to reports/git_history_analysis/. Optionally posts a summary to Slack only on explicit human confirmation. |
| Done |
Report saved with commit breakdown, active branches, key insights, risks, and follow-up questions. |
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
- 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.
- 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.
- 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.
- 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.
- 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.
- 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).
- Group commits by directory or component to identify the most active areas. Done when: commits grouped by directory/component with active areas identified.
- 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.
- Note in-progress work from active branches not yet merged to the default branch. Done when: in-progress work from unmerged active branches noted.
- 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.
- 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.
- 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.
Failure and recovery
- Not a git repository or no commits in range: stop, state the blocker, do not write a report. No mutation occurs.
- Ambiguous repository path or missing time period: ask the user; do not guess or widen scope.
- Incomplete or unclear data: note the gap in the report; never fabricate commits, counts, or insights.
- Slack post failure: the report remains saved and the done predicate holds for the report. State the Slack failure and do not retry without explicit human confirmation.
- Never swallow errors or claim the done predicate holds when the report is missing or incomplete.
Output
A report at reports/git_history_analysis/git_analysis_YYYY-MM-DD.md ordered: title and period header, TL;DR, active features in progress, recently completed (merged to the default branch), commit breakdown by type, most active areas, key insights, risks and observations, follow-up questions. Evidence-driven: cite specific commits, branches, or metrics; separate facts from interpretations; note incomplete data. No author attribution.
1---2name: git-history-analysis3description: Use when the user asks about recent engineering work, what the team is working on, planning or roadmap material, or an explicitly requested Slack summary. Not for remote or irreversible changes.4---56# Git history analysis78## Contract910| Field | Bound contract |11|---|---|12| Trigger | User asks about recent engineering work, what the team is working on, or planning or roadmap preparation. |13| Authority | Human-gated: previews the Slack destination and posting consequence before the optional remote Slack post; otherwise reversible local: writes only a report under reports/git_history_analysis/; rollback is deleting the report. No remote mutation. No force-push or PR creation. |14| Side effect | Writes a categorized commit-breakdown report to reports/git_history_analysis/. Optionally posts a summary to Slack only on explicit human confirmation. |15| Done | Report saved with commit breakdown, active branches, key insights, risks, and follow-up questions. |1617## Inputs1819- 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.20- Time period: optional. Defaults to the last 2 weeks (14 days).21- Filters: optional path or branch filters to narrow the scope.2223## Procedure24251. 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.262. 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.273. Collect commit history from the repository root, adjusting `--since` to the requested period and appending `-- <filters>` when path filters are specified:28 ```bash29 git --no-pager log --since="2 weeks ago" --pretty=format:"%h|%ad|%s" --date=short --stat -- <filters>30 ```31 Omit `-- <filters>` when no path filters are supplied. Done when: commit history collected for the requested period from the repository root.324. Collect active branches (work in progress), filtering out merged branches and dynamically resolving the default branch instead of hardcoding `main`:33 ```bash34 default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)35 git --no-pager branch -r --no-merged origin/$default_branch --sort=-committerdate | grep -E "<filters>" | head -2036 ```37 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.385. Collect recent merges to the default branch (completed work), dynamically resolving the default branch and appending `-- <filters>` when path filters are specified:39 ```bash40 default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo main)41 git --no-pager log --since="2 weeks ago" --merges --pretty=format:"%h|%ad|%s" --date=short origin/$default_branch -- <filters>42 ```43 Omit `-- <filters>` when no path filters are supplied. Done when: recent merges to the default branch collected for the requested period.446. 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).457. Group commits by directory or component to identify the most active areas. Done when: commits grouped by directory/component with active areas identified.468. 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.479. Note in-progress work from active branches not yet merged to the default branch. Done when: in-progress work from unmerged active branches noted.4810. 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.4911. 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.5012. 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.5152## Failure and recovery5354- Not a git repository or no commits in range: stop, state the blocker, do not write a report. No mutation occurs.55- Ambiguous repository path or missing time period: ask the user; do not guess or widen scope.56- Incomplete or unclear data: note the gap in the report; never fabricate commits, counts, or insights.57- Slack post failure: the report remains saved and the done predicate holds for the report. State the Slack failure and do not retry without explicit human confirmation.58- Never swallow errors or claim the done predicate holds when the report is missing or incomplete.5960## Output6162A report at `reports/git_history_analysis/git_analysis_YYYY-MM-DD.md` ordered: title and period header, TL;DR, active features in progress, recently completed (merged to the default branch), commit breakdown by type, most active areas, key insights, risks and observations, follow-up questions. Evidence-driven: cite specific commits, branches, or metrics; separate facts from interpretations; note incomplete data. No author attribution.
OutlineDriven