/retro builds its narrative from git log only — design/decision work that lives in ADRs and issues is structurally invisible

## Summary

Companion to #1315. That issue is about *who* did the work being miscounted (session-count attribution). This one is about *what* work gets counted at all: `/retro` (both single-repo and `global`) derives its entire narrative from `git log`, so any work that leaves no commit — design captured in ADRs, decisions made in issue threads, research recorded in issue comments — is invisible to it. On an ADR/issue-driven project the retro can confidently draw the *opposite* conclusion about what a period was actually about.

Filing this as an observation + proposal rather than a bug — the current behavior is reasonable for commit-centric repos, and I'm happy to send a PR if the direction sounds right. Verified on gstack 1.60.1.0.

## What `/retro` reads today

Checking the current skill (`retro/SKILL.md`, Steps 5–6 and the global Step 3), the data model is entirely git-derived:

```
git log ... --shortstat # commit + churn totals
git log ... --numstat # per-commit line deltas
git log ... --name-only | uniq -c # hotspot analysis
git log ... | grep '\.(test|spec)\.' # test-file counts
git log ... --format="%s" | grep -oE '[#!][0-9]+' # "referenced issues"
```
plus a `TODOS.md` cross-reference. The only `gh` call in the skill is `gh pr view --json baseRefName` for base-branch detection.

To be precise about the issue awareness that *does* exist (so this isn't misread as "retro ignores issues entirely"): Step 5 greps `#NNN` out of **commit subjects**. So:

- an issue is seen **only if a commit references it**, and even then only as a bare number — the skill never reads the issue's title, body, state, or comments;
- an issue with **zero commits** (a pure design / decision / research issue) is completely invisible;
- **ADRs are never read** — `docs/adr/`, `docs/decisions/`, `ADR`, and `SPEC.md` have no occurrence anywhere in the skill.

The honest one-liner: *retro sees an issue's number when a commit mentions it, never its content, and never sees commitless issues or ADRs at all.*

## Why this misleads

On an ADR/issue-driven project, a large share of a period's highest-leverage work produces **no production code in that window**:

- **design** = writing ADRs + slicing PRD issues — possibly dozens of documents, zero code;
- **research** = benchmark/experiment issues whose real output is the data tables in the comments;
- **decision** = milestone scheduling, dependency graphs, owner rulings — all in issues, no git footprint.

Because retro only sees commits and hotspots, it reads "the hotspot is the tooling directory, therefore the product isn't being worked on" — at exactly the moment the product is getting its single largest design push, which lives entirely in ADRs and issues while implementation is still queued.

## A concrete before/after (my own project)

Repo (public): https://github.com/Akagilnc/ming-salvage-sim — a solo game project I run that is heavily ADR- and issue-driven; design lands as ADRs + milestone issues weeks before any implementation commit. Here's what one `/retro global` window (2026-06-29 → 07-08) produced on the first, git-only pass versus after I re-ran it reading issues + ADRs too:

**First pass — git log + hotspot only:**
> Hotspot is the `orchestrator/` tooling directory (churn ~1650 files); the game package `ming_sim/` saw ~237 touched files. Conclusion: the period was spent building orchestrator tooling; the game itself is just a dogfooding target.

**After also reading issues + ADRs:**
> The period's biggest push *was* the game. Milestone M11 (issue #486) was designed and sliced into 116 ready-for-agent tasks across 10 families, design gates 10/10 passed, captured in ~23 new ADRs (0033–0055) plus a run of PRD issues. A separate benchmark issue (#424) recorded a 4-model cheap-coder cost study — four coder models × four real slices, $2.63–$7 per slice, convergence-round data — entirely in the issue comments. None of that had landed as game implementation commits yet (queued in #487–675), so the hotspot stayed on the tooling dir and the first-pass narrative *inverted* the real story ("game = dogfooding target" was exactly backwards).

Same repo, same window — the git-only view and the git+issue+ADR view reach **opposite** conclusions about what the period was about.

The next window (07-05 → 07-13) confirms the same pattern: I ran that retro with all three sources from the start, and the pattern held — orchestrator hotspot 2395 vs game package 27 touched files, yet the actual game work that window was another ~10 design ADRs (0113–0122), still pre-implementation. A pure git-log retro would have reported "no game work" for the second week running.

This is the same failure mode as #1315 (session counts) and #1999 (test-file glob undercount): the retro's inputs don't fully cover the work, so a confident-looking narrative gets built on a partial view.

## Proposed direction (opt-in)

Add an optional pre-pass so retro reads the two non-git sources before it builds the narrative, gated so commit-centric repos are unaffected:

1. **Trigger only when a signal exists** — the repo has a `docs/adr/` or `docs/decisions/` directory, and/or `gh` is authenticated with issues enabled. Otherwise behave exactly as today (no new hard dependency on `gh`).
2. **ADR scan** — `git log --since= --diff-filter=A --name-only` scoped to `docs/adr/*` / `docs/decisions/*`, read the titles of decision records added in the window.
3. **Issue scan** — `gh issue list --state all --limit N`, filter to `updatedAt` within the window, and optionally `gh issue view ` for a configured milestone/tracker issue. Classify updated issues coarsely (design / tooling / research).
4. **Report structure** — surface these on their own lines and explicitly separate *"implementation shipped (hotspot/commits)"* from *"design/decision advanced (ADRs/issues)"* so the two can't be conflated. Fail open: if `gh` errors or the dirs are absent, silently fall back to today's git-only path.

This keeps the default fast and dependency-free, and only pays the cost on repos that actually track work outside commits.

The raw before/after retro snapshots (git-only first pass vs three-source re-run) are JSON I can paste or share if that's useful. Thanks for gstack — this only surfaced because I lean on `/retro global` weekly across repos, and I'm happy to open a PR for the pre-pass if this direction fits how you'd want retro to grow.

Start in retro/SKILL.md, especially Steps 5–6 and the global Step 3, and review the existing git-derived inputs and gh usage. Define the opt-in ADR and issue pre-pass, keeping the current git-only behavior when signals or gh access are absent. Done means the retro separates implementation shipped from design or decision work and fails open when optional sources cannot be read.

Written by the indexing model from the issue text.