| name | interpreting-tool-output |
| description | Reference for mapping raw tool output (code-maat, hercules, git-of-theseus, git-fame, git-truck, repowise) to warehouse tables, tool-specific quirks, and cross-check rules. Use when debugging warehouse mismatches, investigating why two tools report different values for the same metric, deciding which canonical source to trust, or querying a specific warehouse table to compare per-tool entries โ distinct from open-ended dashboard drill-down (asker) or writing narrative copy (axes). |
Quick reference โ where to look first
| Question / metric | Canonical source | Cross-check | Warehouse table(s) |
|---|
| Per-author LOC ownership | git-fame | git-truck | ownership_share |
| File hotspots | code-maat (revs) + walker (revs) | repowise | file_metrics |
| Hidden coupling between files | code-maat | hercules | coupling_pairs |
| Code aging โ snapshot now | git-of-theseus | (none) | code_age_buckets |
| Code aging โ over time | hercules | (none) | burndown_series |
| Bus factor | code-maat | repowise | bus_factor (computed downstream) |
| Dead code / "why" findings | repowise | (none) | repowise_findings |
| Per-commit file-author edges | walker (in-tree) | (none) | commit_file_authors |
Pick the per-tool reference for details:
references/code-maat.md โ coupling matrices, soc, ownership โ coupling_pairs, bus_factor, file_metricsreferences/hercules.md โ burndown matrices โ burndown_series, supplementary coupling_pairsreferences/git-of-theseus.md โ cohort survival โ code_age_bucketsreferences/git-fame.md โ per-author LOC + commits + files โ ownership_share (canonical)references/git-truck.md โ file tree with top contributor โ ownership_share (cross-check only)references/repowise.md โ typed findings via MCP โ repowise_findings, augments bus_factor and file_metrics
Plus the cross-source disagreement policy: references/cross-check-policy.md.
Quick rules
- If a card asks "who owns this code," prefer
ownership_share rows where source = 'git-fame'. Git-truck is byte-size-proxied and name-based, not email-based โ keep it for the "Health" cross-check tab only.
- If a card asks "how is the codebase aging," there are two answers:
code_age_buckets is a snapshot (git-of-theseus, quick tier); burndown_series is a time series (hercules, full tier). Use the time series when it's available.
- Disagreements between tools writing to the same logical metric are not bugs โ they are recorded as
tool_failures rows of class data_sanity and shown on the dashboard's Health tab. See references/cross-check-policy.md.
Where the per-tool wrappers live
Source code: src/code_diligence/tools/<tool>.py. Each module exposes run_<tool>(repo_path) and persist_<tool>(conn, repo_id, records). Both are exercised by tests under tests/tools/.
