repo-intel

repo-intel — native repository intelligence

extend op-cell: add situational awareness before planning, review, onboarding, or risk triage. The skill answers temporal, social, graph, symbol, and project-shape questions with native tool recipes only; no prebuilt artifact is required.

All signal recipes are in references/signals.md. Run the smallest recipe set that answers the user's query, then report the evidence shape directly: file, count, score, owner, last-seen, callers, callees, or manifest field.

When to Apply

• The user asks for git-history intelligence: hotspots, coldspots, bugspots, churn, recent activity, stale areas, file history.
• The user asks for social risk: ownership, bus factor, stale owners, contributor concentration.
• The user asks for code coupling: files that co-change, risky refactor surfaces, hidden module boundaries.
• The user asks for symbol intelligence: entry points, exported symbols, callers, callees, dependents, impact.
• The user asks for repo health: activity, high-churn/bug-fix overlap, owner staleness, entry-point clarity, manifest/tooling shape.
• The user is about to refactor, review, onboard, or choose a next area and needs evidence before touching code.

When NOT to Apply

• The ask is a single known symbol lookup and the answer is already in context.
• The ask needs runtime profiling, production telemetry, or benchmark evidence rather than repository-history evidence.
• The directory is not a git repository and the user specifically asked for history-derived signals. Degrade to manifests/symbols only and state that history signals are unavailable.
• The user asks for a complete architecture map. Use repo-intel only for entry points, hotspots, ownership, and dependence evidence; do not invent architecture from churn.

Workflow

1. Detect scope. Resolve the repo root with git rev-parse --show-toplevel; run recipes from that root. If the user names a path, keep every command path-scoped.
2. Detect graph index availability. Prefer codegraph for symbol/dependent/entry-point questions when indexed: codegraph_explore, codegraph_search, codegraph_callers, codegraph_callees, codegraph_impact, codegraph_files. If unavailable or stale, degrade to ast-grep plus git grep fallbacks from references/signals.md.
3. Pick signals, not a bundle. Match the user's noun to the query menu. Avoid whole-repo digest unless the question asks for broad orientation or synthesis.
4. Run native recipes on demand. Use git-history commands for temporal/social signals; codegraph or AST/text fallbacks for symbol signals; manifest reads for project metadata; npx -y repomix --compress for compressed whole-repo context.
5. Normalize evidence. Suppress generated-file noise for bug attribution and churn summaries: *.d.ts, *.snap, lockfiles, generated/, codegen/, dist/, build/, vendor/.
6. Grade certainty. HIGH = git/codegraph direct evidence. MEDIUM = AST/text fallback with exact file:line hits. LOW = inferred repo-health synthesis from multiple signals.
7. Report compactly. Lead with the answer, then a ranked table. Include the command family used, formula, and cutoff window when scores appear.

Query Menu

Query	Primary evidence	Output
hotspots [path]	git --no-pager log --format churn, 90-day recent window	files ranked by score = (recentChanges*2 + totalChanges)/(totalChanges+1)
bugspots [path]	fix/hotfix commit subjects + changed files, generated suppression	files ranked by bug-fix density
coupling <file>	commits touching target and co-changing files	related files with common commit count + Jaccard/target ratios
ownership <path>	per-file/path author commits	primary owner, owner shares, stale owner flags
bus-factor [path]	commit ownership concentration, bots ignored when identifiable	people required to cover 80% of commits + at-risk paths
contributors [path]	git shortlog -sne + per-author last seen	contributors, commits, recent/stale status
recency [path]	last commit per file/author	active/cold/stale files and owners
entry-points	codegraph entry-point exploration; manifest and AST fallbacks	scripts, commands, main functions, service starts
`symbols <file	name>`	codegraph search/explore; AST fallback
dependents <symbol>	codegraph callers/impact; AST/text fallback	files/symbols that call/import/reference the target
metadata	manifest reads	stack, package manager, CI/test scripts, workspace shape
digest	npx -y repomix --compress	compressed repo packet for synthesis
health	hotspots + bugspots + bus factor + recency + metadata	evidence-backed repo health summary

Interpretation Rules

• Hotspot is not bad by itself. It means high change pressure. Risk appears when hotspot overlaps with bugspots, stale owners, weak tests, or broad dependents.
• Bugspot is a defect signal, not blame. It counts fix-classified commits touching a file after generated-file suppression.
• Coupling above 0.5 target ratio is suspicious. If two files change together in most target commits, review them as one refactor surface.
• Bus factor is path-sensitive. A repo-level bus factor can look safe while src/payments/ is single-owner.
• Staleness is snapshot-relative. Compare author/file lastSeen to the repo's last commit; stale means more than 90 days older than that point, not older than wall-clock today.
• Symbol fallbacks are weaker than codegraph. git grep proves references exist; it does not prove call semantics.

Degradation Note

Git history is the stable baseline for this skill. Codegraph is optional and improves symbol, caller, callee, impact, and entry-point precision when the repo is indexed. When codegraph is unavailable, use ast-grep for structural matches and git grep for exact text references; mark those answers MEDIUM and include the fallback command.

Anti-patterns

• Running every recipe. Choose the minimal evidence set; repo-intel is a scalpel, not a census.
• Treating churn as quality. Churn is pressure; only combined signals justify risk claims.
• Ignoring generated files. Schema or snapshot churn can swamp real bugspots.
• Using wall-clock staleness. Always anchor the 90-day window to the repo's last commit.
• Conflating ownership with authority. Ownership means observed change history, not design responsibility.
• Reporting ungrounded health labels. Every health claim needs at least two cited signals.

Validation Gates

• For a ranked table, state the formula and path scope.
• For bugspots, state that generated-file suppression was applied.
• For bus-factor, separate repo-level and path-level risk.
• For symbol/dependent answers, state whether codegraph or fallback evidence was used.
• For repo health, include at least: activity recency, top hotspot, top bugspot, bus factor, and one manifest/tooling fact.