code-quality-trends

name	code-quality-trends
description	Use when checking code quality trends, tech debt accumulation, TODO/FIXME growth, test coverage ratios, PR size distribution, or generating a code quality report. Trigger phrases: code quality, code trends, tech debt trends, quality report.
category	qa
capabilities	["trend-tracking","static-analysis"]
input_types	["git-diff","code-path","repo"]
output_types	["code","report"]
complexity	moderate
cost_profile	low
maturity	beta
metadata_source	inferred

Code Quality Trends Report

Produce a monthly trends report tracking code quality signals across repositories using Sourcegraph and GitHub CLI tools. The report measures TODO/HACK/FIXME accumulation, test file ratios, and PR merge patterns.

Configuration

See _shared/report-config.md for the standard config resolution pattern.

Config schema (~/.claude/skills/code-quality-trends/config.json):

• repos: list of repository name strings (Sourcegraph-compatible format)
• lookback_days: number (default: 30)

Required scope: at least one repos entry.

Arguments

• repos: list of repository names to track (Sourcegraph-compatible format)
• lookback_days: how far back to analyze (default: 30)

Workflow

1. Measure TODO/HACK/FIXME accumulation. For each repo:

   • Use keyword_search with query repo:^{repo}$ (TODO|HACK|FIXME) to count current occurrences.
   • Use diff_search with pattern="TODO|HACK|FIXME", added=true, after="{lookback_days} days ago", useRegex=true to count newly added markers in the period.
   • Use diff_search with pattern="TODO|HACK|FIXME", removed=true, after="{lookback_days} days ago", useRegex=true to count removed markers in the period.
   • Net change = added - removed. Positive = accumulating debt. Negative = paying down debt.

2. Measure test file ratio. For each repo:

   • Use keyword_search with query repo:^{repo}$ file:test type:path count:all to count test files.
   • Use keyword_search with query repo:^{repo}$ file:\.(py|java|ts|js|go|kt|scala)$ type:path count:all to count source files (exclude test files).
   • Compute ratio: test files / (source files - test files). Report as percentage.

3. Analyze PR size distribution. For each repo, use gh CLI:

   • gh pr list --repo {repo} --state merged --limit 100 --json additions,deletions,number,title,mergedAt filtered to the lookback period.
   • Classify PRs: small (<50 lines), medium (50-250), large (250-1000), extra-large (>1000).
   • Compute: median PR size, percentage of XL PRs, total PRs merged.

4. Measure PR merge rates and review turnaround. For each repo, use gh CLI:

   • gh pr list --repo {repo} --state merged --limit 100 --json createdAt,mergedAt,number filtered to lookback period.
   • Compute: median time-to-merge (createdAt to mergedAt), PRs merged per week.
   • gh pr list --repo {repo} --state open --json createdAt,number,title to count stale open PRs (open > 7 days).

5. Check for large files or binary additions. Use diff_search with pattern matching large additions (files with >500 added lines in a single commit) during the period. Flag as potential code quality concern.

6. Generate report. Output markdown:

## Code Quality Trends — {date}
Repos: {repo list} | Period: last {lookback_days} days

### Summary
- Total PRs merged: {N} | Median PR size: {N} lines | XL PRs (>1000 lines): {N}%
- TODO/HACK/FIXME net change: {+/-N} | Current total: {N}
- Test file ratio: {N}%

### Tech Debt Markers (TODO/HACK/FIXME)
| Repo | Current Total | Added | Removed | Net Change | Trend |
|---|---|---|---|---|---|
(Per-repo breakdown with trend arrow)

### Test Coverage Ratio
| Repo | Test Files | Source Files | Ratio | Assessment |
|---|---|---|---|---|
(Per-repo breakdown)

### PR Size Distribution
| Repo | Small (<50) | Medium (50-250) | Large (250-1K) | XL (>1K) | Median |
|---|---|---|---|---|---|
(Per-repo breakdown)

### PR Velocity
| Repo | Merged/Week | Median Time-to-Merge | Stale Open PRs |
|---|---|---|---|
(Per-repo breakdown)

### Flags
(Any concerning signals: growing debt, shrinking test ratio, many XL PRs, stale PRs)

7. Post to #team-digests channel if configured, never to a primary team channel.

8. Terminate. Report is complete when all repos have all metrics computed.

Design Principles

1. Team-level only. Aggregate to team level — it is the right granularity for a periodic digest. Individual-level detail (PRs per person, TODOs per author) is too noisy for a team report.
2. Deterministic math first, LLM narrates only. All counts, ratios, and distributions must be computed from actual search results and PR data. The LLM writes prose around the numbers but never invents counts or estimates ratios.
3. Pair metrics with counter-metrics. Never report PR velocity without PR size. Fast merges on huge PRs may indicate insufficient review. High test ratio without TODO trends misses the full picture.

Golden Rules

1. Count, don't estimate. Every number comes from a Sourcegraph search or gh CLI result. Never say "approximately" — run the query and report the actual count.
2. Net change matters more than absolute count. 500 TODOs is not inherently bad; +50 TODOs this month is a trend worth flagging.
3. PR sizes are lines changed (additions + deletions), not file count.
4. Use regex for debt markers. TODO|HACK|FIXME must be searched with useRegex=true to catch all variants.
5. Filter PRs to the lookback window. Don't include PRs merged before the reporting period.
6. Check ALL repos, not a sample.

Anti-Rationalization Counter-Table

Excuse	Reality
"I estimated the TODO count from a sample of files."	Run the actual keyword_search. Sampling gives wrong numbers.
"PR sizes aren't available so I skipped that section."	The gh CLI returns additions and deletions for every PR. Compute the sum.
"Test ratio is hard to measure so I described it qualitatively."	Count test files. Count source files. Divide. It's arithmetic, not judgment.
"The repo has too many PRs to analyze all of them."	Use --limit 100 and note the sample size. 100 PRs is a representative sample for monthly trends.
"I listed the metrics but didn't flag any concerns."	The Flags section exists to surface concerning trends. If debt is growing or test ratio is shrinking, say so.

Termination Labels

Label	Meaning
report_complete	All repos analyzed, all metrics computed, flags identified
report_partial	Some repos analyzed but search or CLI errors prevented full coverage — noted which
no_repos_configured	No repos specified — need config.json or user input
api_error	Sourcegraph or GitHub API unreachable

Self-Review Checklist

• TODO/HACK/FIXME counts come from actual Sourcegraph searches (not estimates)
• Net change computed from diff_search added vs removed counts
• Test file ratio computed from actual file counts
• PR size distribution computed from gh CLI data with additions+deletions
• PR velocity includes time-to-merge AND stale open PR count
• All configured repos were analyzed
• Flags section surfaces any concerning trends