repo-activity-summary

Repo Activity Summary

Answer "what's been happening in this repo" from local git history — no network, no tokens, no setup.

Trigger conditions

Use this skill when the user asks:

• "What has this repo been working on recently?"
• "What technologies does this project use?"
• "Where are the high-churn files / hotspots?"
• "Who's contributing and what are they working on?"
• "Is this project actively maintained?"
• Before onboarding onto an unfamiliar codebase.

Do not use this skill for file-level blame or provenance — use investigating-repository-history for that.

Quick start

python3 scripts/activity_summary.py --repo-dir . --days 90

Flag	Default	Description
--repo-dir	.	Path to the git repository
--days	90	Days of history to analyze
--author	(all)	Filter to one author
--format	markdown	markdown, json, or text
--max-commits	500	Cap for very active repos
--branch	(current)	Branch / revision to analyze (must not start with -)
--output / -o	(stdout)	Write the report to a file (UTF-8)
--classify-threshold	0.25	If the share of unclassified commits exceeds this fraction, mark work-type classification unreliable and emit subject samples
--max-unclassified-samples	40	Cap on unclassified commit subjects included in the report
--raw-subjects	off	Emit every filtered commit subject with sha and date for agent-side classification
--version	—	Print version (1.1.0) and exit

What it produces

A structured report with:

1. Overview — commit count, date range, contributors, lines added/deleted
2. Technologies — languages and frameworks inferred from file paths (heuristic)
3. Work type breakdown — feature / bugfix / refactor / docs / infra / release / … (keyword heuristic)
4. Unclassified subjects — when keyword classification is unreliable, the raw subjects so the agent can classify them
5. Churn hotspots — most frequently modified files and directories (lockfiles/generated paths excluded)
6. Contributor patterns — per-author commits, lines, and primary focus
7. Velocity — commits/week, active days, average commit size (same noise filter as churn)
8. Project health — test modules (by basename/path convention), CI, docs, recency

How it works

1. Collects commits via git log --numstat --no-renames with an explicit UTC --since timestamp
2. Filters bots (GitHub-style [bot] names and known automation identities) and keeps the filtered count
3. Detects technologies from extensions, exact manifest filenames, and path segments — never bare path substrings; requires a manifest hit or at least two source files
4. Classifies work types with precompiled word-boundary regexes and scored multi-label tie-break; does not present a large "Other" bucket as a finding
5. Ranks files/directories by modification frequency
6. Aggregates per-author stats using the same classifier
7. Checks for test modules, CI config, documentation, and last activity date

Agent guidance

• Prefer the facts in the report (counts, paths, subjects, dates) over the keyword labels.
• When classification.unreliable is true, or the unclassified share is high, classify from the emitted subjects (or re-run with --raw-subjects) instead of trusting the work-type percentages.
• Technology labels are path heuristics, not an import graph — verify against manifests when it matters.

Limitations

• Shallow clones (--depth 1) limit the analysis window.
• Technology detection is a heuristic (extensions, manifests, path segments — not imports or lockfile graphs). Labels are hints.
• Work-type classification is a keyword heuristic, not ground truth. Conventional-commit prefixes classify well; free-form subjects often do not. When the unclassified share exceeds --classify-threshold (default 25%), the report says so and emits subjects for the agent to classify.
• Average commit size and churn exclude lockfiles and common generated/vendor paths; the report states this filter.
• Summarizes activity, not code quality.