brokk-report

name	brokk-report
description	Use when asked for a full legacy codebase analysis, overview report, or comprehensive audit - orchestrates all brokk analysis skills plus git history to produce a prioritized report

brokk-report

Overview

Produce a comprehensive legacy codebase report by running all brokk analysis skills, augmenting with git history, and synthesizing findings into a prioritized action list. The report is a single markdown document suitable for handing to an engineering team.

Prerequisites

rg --version 2>/dev/null || echo "rg MISSING"
git --version 2>/dev/null || echo "git MISSING — history sections will be skipped"

Orchestration Order

Run these in sequence. Each produces a section of the final report.

1. Codebase Overview      (this skill — quick characterisation)
2. Git History            (this skill — evolution and hotspots)
3. brokk-flow-graph       → Entry Points & Flow section
4. brokk-code-smells      → Code Quality section
5. brokk-untested-paths   → Test Coverage section
6. brokk-modeling-inconsistencies → Domain Model section
7. brokk-security-scan    → Security section
8. Synthesis              (this skill — prioritised issues list)

When using parallel subagents, steps 3–7 can run concurrently after step 2 completes.

---

Section 1 — Codebase Overview

Languages & Size

# File counts by extension
rg --files | rg -o "\.[^.]+$" | sort | uniq -c | sort -rn | head -20

# Total lines of code (source only)
rg --files --glob "!*test*" --glob "!*spec*" --glob "!vendor/*" \
   --glob "!node_modules/*" --glob "!dist/*" --glob "!*.{json,yaml,yml,md,lock}" \
   | xargs rg -c "" 2>/dev/null | awk -F: '{s+=$2} END {print s, "total lines"}'

# Top-level directory structure (purpose of each folder)
rg --files | rg -o "^[^/]+" | sort -u

Tech Stack Detection

# Dependency manifests
rg --files | rg "(package\.json|requirements\.txt|Pipfile|go\.mod|pom\.xml|build\.gradle|Gemfile|composer\.json|Cargo\.toml|\.csproj)"

# Frameworks
rg -l "(django|flask|fastapi|express|nestjs|spring|rails|laravel|gin|fiber|dotnet)" \
   --glob "*.{py,js,ts,java,rb,php,go,cs}" | head -5

Read the dependency manifest files to list key frameworks, libraries, and versions.

Entry Points Summary

Run brokk-flow-graph and summarise entry point count by type (HTTP routes, CLI commands, background jobs, event handlers).

---

Section 2 — Git History Analysis

Project Timeline

# First and last commit
git log --oneline --reverse | head -1
git log --oneline | head -1

# Commit frequency by month
git log --date=format:"%Y-%m" --format="%ad" | sort | uniq -c

# Contributors
git shortlog -sn --no-merges | head -20

Churn Hotspots (most frequently changed files)

# Files changed most often in last 12 months
git log --since="12 months ago" --name-only --format="" \
  | sort | uniq -c | sort -rn | head -20

High-churn files are either important (good candidates to understand) or unstable (bug-prone).

Major Changes (breaking points in history)

# Large commits (>50 files changed) — likely refactors or migrations
git log --oneline --shortstat \
  | awk '/files? changed/ {files=$1; commits++; if(files>50) print prev, "→", $0} {prev=$0}'

# Branch merges (major features merged)
git log --merges --oneline --since="2 years ago" | head -30

# Tag history (releases)
git tag --sort=-creatordate | head -20

Recent Activity (last 90 days)

git log --since="90 days ago" --oneline --stat | head -60

Summarise: what areas have been actively worked on recently?

---

Section 3–7 — Delegate to Brokk Skills

For each, run the corresponding skill and capture its output:

• brokk-flow-graph → produces Section 3: Entry Points & Flow
• brokk-code-smells → produces Section 4: Code Quality
• brokk-untested-paths → produces Section 5: Test Coverage
• brokk-modeling-inconsistencies → produces Section 6: Domain Model
• brokk-security-scan → produces Section 7: Security

Summarise each section in 3–5 bullet points at the top, with full details below.

---

Section 8 — Synthesis: Prioritised Issues

After all sections complete, create a unified priority list. Use this scoring:

Factor	Weight
Security risk (CRITICAL/HIGH)	+3
Affects actively-changed code (high churn)	+2
No test coverage	+2
Blocks understanding of system	+1
Easy to fix	+0.5

Rank issues from highest to lowest score. Aim for 10–20 actionable items.

### Priority Action List

| # | Issue | Severity | Effort | Score | Skill |
|---|-------|----------|--------|-------|-------|
| 1 | Hardcoded DB password in config.py | CRITICAL | Low | 5.5 | brokk-security-scan |
| 2 | No tests for billing module (active churn) | HIGH | High | 4 | brokk-untested-paths |
| 3 | SQL injection in user search | CRITICAL | Low | 5 | brokk-security-scan |
...

---

Full Report Template

Emit the report in this structure:

# Legacy Codebase Report: <repo-name>
**Generated:** <date>
**Analysed by:** brokk-report

---

## Executive Summary
<3–5 sentences: what is this codebase, how healthy is it, top 3 concerns>

---

## 1. Codebase Overview
### Languages & Size
### Tech Stack
### Architecture (from brokk-flow-graph summary)

---

## 2. Git History
### Timeline: <first commit> → <last commit> (<N> commits, <N> contributors)
### Churn Hotspots
### Major Changes
### Recent Activity

---

## 3. Entry Points & Flow
<brokk-flow-graph output — Mermaid diagrams + summary table>

---

## 4. Code Quality
<brokk-code-smells output>

---

## 5. Test Coverage
<brokk-untested-paths output>

---

## 6. Domain Model
<brokk-modeling-inconsistencies output>

---

## 7. Security
<brokk-security-scan output>

---

## 8. Prioritised Issues
<Priority Action List table>

---

## Appendix: Tools & Coverage
| Tool | Status | Notes |
|------|--------|-------|
| ripgrep | ✓ installed | |
| eslint | ✓ installed | 42 warnings |
| bandit | ✗ not found | install: pip install bandit |

---

Windows Notes

• git log works natively with Git for Windows
• Replace awk line-counting with: collect rg -c "" output and sum manually
• All rg commands work as-is

Common Mistakes

Mistake	Fix
Running all skills serially when subagents available	Steps 3–7 are independent — parallelise them
Including every linter warning	Only surface Critical/High in executive summary; full detail in appendix
Writing the report before running all sections	Complete all data collection before synthesis
Skipping git history	History reveals why the code is structured the way it is — essential context
Generic executive summary	Make it specific: name actual files, actual counts, actual frameworks