Tools

trusty-git-analytics — documentation

Developer-productivity analytics CLI / DB. Crate name: tga (crates/trusty-git-analytics/). Walks local git repositories, classifies every commit into a work category via a multi-tier cascade, and emits per-author / per-week / DORA / velocity / quality reports.

This directory is the single source of truth for trusty-git-analytics design, requirements, research, and user/developer documentation. The crate README.md and rustdoc stay in-crate; everything else lives here (see ADR-0001).

Documentation map

Subdir	What's here
`spec/`	Canonical, authoritative specification set — the what / why / gap layer reconciled against the live code and ticket backlog: `PRD.md`, `ARCHITECTURE.md`, `COMPONENTS.md`. Start here. It sits above `requirements/` and supersedes it where they disagree.
`requirements/`	Detailed source specification ported from the Python predecessor: overview, configuration schema, database schema, CLI commands, classification cascade, collection, reporting, and Rust architecture. The field-by-field reference the `spec/` set links into. Some sections have drifted from the code (taxonomy, DB migration list, CLI surface, DORA/effort/quality additions) — where `spec/` and `requirements/` disagree, `spec/` is authoritative. Start at `requirements/index.md`.
`developer/`	Contributor docs: architecture, developer guide, configuration reference, migration from Python, publishing.
`user/`	End-user docs: user guide.
`decisions/`	Crate-specific ADRs (Nygard format): SQLite tuning, performance hotspots, Bitbucket PR provider. Workspace-wide ADRs live in `docs/adr/`.
`regression-testing/`	Versioned performance/quality snapshots (`v{VERSION}-{DATE}.md`), the Rust-vs-Python `comparison.md`, and the methodology in `regression-testing/README.md`.
`research/`	Investigation and design documents: commit-effort scoping spec, per-engineer drilldown.
`sessions/`	Engineering-session narratives (none yet).

Where to start

Understanding the system? spec/README.md → spec/PRD.md → spec/ARCHITECTURE.md (canonical), then requirements/ for field-level detail.
Using the CLI? user/user-guide.md.
Contributing? developer/developer-guide.md and developer/architecture.md.
Understanding a past decision? decisions/ (crate-specific) or docs/adr/ (workspace-wide).

Conventions

Subdirs follow the workspace documentation conventions described in the root CLAUDE.md. The spec/ set is the canonical what/why/gap layer, reconciled against the live crates/trusty-git-analytics/src/ tree; the requirements/ set is the detailed field-level source that originally mirrored the API contract of the gitflow-analytics Python predecessor and now serves as reference beneath spec/. research/ files are dated point-in-time investigations.