Omar SobhandClaude Opus 5
4358964c05
55 of 85 role skill bindings pointed at skills that were never authored,
so 10 of 11 team templates bound a smaller context bundle than their role
prompts assumed. Three roles bound nothing at all (gpu.bench_engineer,
threejs.shader_author, threejs.perf_engineer) while their prompts described
procedures they had no way to read.
The loader comment at team_template_loader.rs:167 already diagnosed this —
snake_case slugs in TOML against kebab-case skill files — and it was
half-fixed: the kebab names were corrected, the snake_case ones left.
It was invisible because both existing tests assert authored ⊆ referenced
(30/30, green) and the second explicitly declines to check the other
direction. So the failing half was the half nobody asserted.
Resolved every name by one of three explicit choices:
- 23 skills authored where the role genuinely needed the procedure
(gpu, threejs, research, analysis, frontend, mobile, backend, platform)
- renames onto authored skills where one existed in substance, including
the four-near-duplicate cases that collapse onto one real skill
- 22 aspirational references deleted — a binding an agent cannot read is
a promise, not a capability
Two tests now hold it. The unit test checks referenced ⊆ authored against
the files. The new integration test runs both loaders in boot order and
asserts the bindings survive the trip through the database, which is a
different question: resolution goes through skills_catalog rows, so a skill
file that exists but fails to ingest still leaves the role empty.
Negative controls: the unit test failed naming all 55; the integration test
fails naming the exact role when one name is reverted.
threejs.shader_author and .perf_engineer gained a second and third skill
after the collapse — pin_in_context pins idx < 2, so a role left with one
skill silently pins less than the policy intends.
Co-Authored-By: Claude Opus 5 <[email protected]>
56 lines
2.2 KiB
Markdown
56 lines
2.2 KiB
Markdown
---
|
|
name: git-log-forensics
|
|
description: Reading a repository's history to find when behaviour changed and why, rather than guessing from the current tree.
|
|
when_to_use: You are investigating why code is the way it is, or when a behaviour was introduced.
|
|
tags: [analysis, git]
|
|
---
|
|
|
|
# The history answers questions the tree cannot
|
|
|
|
The current tree shows what is true. It does not show what was tried, what was
|
|
reverted, or which line was load-bearing enough to be touched forty times.
|
|
|
|
## The four commands that answer most questions
|
|
|
|
```bash
|
|
git log -S'<string>' --oneline -- <path> # when did this string appear/vanish
|
|
git log -L'<start>,<end>:<file>' # every change to these lines
|
|
git log --follow -- <file> # survives renames
|
|
git bisect start <bad> <good> # find the commit that changed it
|
|
```
|
|
|
|
`-S` (the "pickaxe") is the most under-used and the most powerful: it searches
|
|
for commits where the *count* of a string changed, so it finds the commit that
|
|
introduced a call, not every commit that mentions it. `-L` gives the biography
|
|
of a specific function.
|
|
|
|
## Churn marks risk
|
|
|
|
```bash
|
|
git log --format= --name-only | sort | uniq -c | sort -rn | head -20
|
|
```
|
|
|
|
Files at the top are either the project's core or its problem area, and the
|
|
commit messages tell you which. A file changed in 200 commits by 15 authors is
|
|
where the next bug will be, whatever the current code looks like.
|
|
|
|
## Read the message, then distrust it
|
|
|
|
A commit message states intent. The diff states what happened. When they
|
|
disagree — "small refactor" touching thirty files, "fix typo" changing a
|
|
condition — the diff is the truth, and the disagreement is itself a finding
|
|
worth recording.
|
|
|
|
## Blame points at the last toucher, not the author
|
|
|
|
`git blame` shows who last modified a line, which after a reformat, a rename or
|
|
a lint pass is whoever ran the tool. Use `-w` (ignore whitespace) and
|
|
`-C` (detect moved code) before drawing any conclusion, and prefer `log -L` when
|
|
you want the line's history rather than its current owner.
|
|
|
|
## What to report
|
|
|
|
A forensic finding is a commit hash, a date, and the reason the change was made
|
|
if the message or its PR gives one. "This check was added in `a1b2c3d` after an
|
|
incident" is actionable. "This code looks defensive" is not.
|