<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/architecture/assessments/code-as-a-crime-scene-overview/">
  <id>https://docs.spec-kitty.ai/architecture/assessments/code-as-a-crime-scene-overview/</id>
  <title>Code as a Crime Scene — High-Level Overview</title>
  <updated>2026-09-30T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/architecture/assessments/code-as-a-crime-scene-overview/"/>
  <summary>Pedagogical overview of the Code-as-a-Crime-Scene (CaaCS) auditing technique, with empirical observations from the 2026-05 forensic run on the spec-kitty repository.</summary>
  <content type="html">&lt;span id=&quot;code-as-a-crime-scene--high-level-overview&quot;&gt;&lt;/span&gt;
&lt;blockquote&gt;
&lt;p&gt;Pedagogical overview of the Code-as-a-Crime-Scene (CaaCS) auditing technique, with empirical observations from the 2026-05 run on spec-kitty (extended scope).&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;&lt;strong&gt;Last updated:&lt;/strong&gt; 2026-05-09 (after &lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; scope-expansion pass).
&lt;strong&gt;Companion artefacts:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Doctrine: &lt;code dir=&quot;auto&quot;&gt;packs/built-in/tactics/analysis/forensic-repository-audit.tactic.yaml&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;packs/built-in/procedures/legacy-codebase-triage.procedure.yaml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Empirical run: &lt;code dir=&quot;auto&quot;&gt;docs/archive/plans/engineering-notes/architecture-audits/2026-05-spec-kitty-caacs.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Cross-check vs issue tracker: &lt;code dir=&quot;auto&quot;&gt;docs/archive/plans/engineering-notes/architecture-audits/2026-05-822-crosscheck.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Phase-3 synthesis &amp;#x26; meta: &lt;code dir=&quot;auto&quot;&gt;docs/plans/engineering-notes/architecture-audits/2026-05-phase3-*.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;docs/archive/plans/engineering-notes/architecture-audits/2026-05-caacs-meta-assessment.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;hr&gt;
&lt;h2 id=&quot;1-what-caacs-is&quot;&gt;1. What CaaCS is&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Code as a Crime Scene&lt;/strong&gt; is a forensic technique for understanding a codebase you didn’t write. The premise is borrowed from criminology: investigators don’t read every report on every person ever in a city — they look for &lt;em&gt;patterns of behavior&lt;/em&gt; that point to where the action is. CaaCS does the same thing for software, treating the version-control history as the behavioral log.&lt;/p&gt;
&lt;p&gt;The output is a &lt;strong&gt;prioritized triage&lt;/strong&gt;, not a “rewrite plan.” CaaCS doesn’t tell you what to fix — it tells you &lt;em&gt;where to look first&lt;/em&gt; and &lt;em&gt;what questions to ask when you get there.&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;2-the-core-insight&quot;&gt;2. The core insight&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Behavior over structure.&lt;/strong&gt; A static look at a codebase tells you what it currently &lt;em&gt;is&lt;/em&gt;; the git history tells you what people &lt;em&gt;did&lt;/em&gt; with it. Defects cluster, knowledge concentrates, and architectural debt accumulates in patterns that the file tree by itself cannot show. Forensic recipes make those patterns visible cheaply, &lt;em&gt;before&lt;/em&gt; you commit to reading any file in depth.&lt;/p&gt;
&lt;p&gt;A static reading answers &lt;em&gt;what is here?&lt;/em&gt; CaaCS answers &lt;em&gt;what mattered to the people who built this?&lt;/em&gt;&lt;/p&gt;
&lt;h2 id=&quot;3-origin-and-pedigree&quot;&gt;3. Origin and pedigree&lt;/h2&gt;
&lt;p&gt;The technique was articulated by &lt;strong&gt;Adam Tornhill&lt;/strong&gt; in the books &lt;em&gt;Your Code as a Crime Scene&lt;/em&gt; and &lt;em&gt;Software Design X-Rays&lt;/em&gt;. Tornhill’s &lt;code dir=&quot;auto&quot;&gt;code-maat&lt;/code&gt; tool implements the deeper analyses (temporal coupling, knowledge maps, complexity trends).&lt;/p&gt;
&lt;p&gt;Piechowski’s two blog posts (linked in the audit’s methodology section) are a lighter, recipe-oriented adaptation aimed at Rails legacy audits. They strip the technique to five git invocations and a triage doc, which is the form most teams actually use day-to-day.&lt;/p&gt;
&lt;p&gt;The Microsoft Research paper &lt;em&gt;“Use of Relative Code Churn Measures to Predict System Defect Density”&lt;/em&gt; (Nagappan &amp;#x26; Ball, 2005) is the foundational empirical justification: churn is a good defect predictor.&lt;/p&gt;
&lt;h2 id=&quot;4-the-five-core-recipes&quot;&gt;4. The five core recipes&lt;/h2&gt;
&lt;p&gt;Each recipe is a single git invocation answering a single question. Run them in order; each one sharpens the next.&lt;/p&gt;









































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;#&lt;/th&gt;&lt;th&gt;Question&lt;/th&gt;&lt;th&gt;Recipe (1y window)&lt;/th&gt;&lt;th&gt;Signal&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;1&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Where is the action?&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;git log --format=format: --name-only --since=&quot;1 year ago&quot; | sort | uniq -c | sort -nr | head -20&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Churn hotspots — files most touched&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;2&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Who knows this code?&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;git shortlog -sn --no-merges --since=&quot;1 year ago&quot;&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Bus factor — contributor concentration&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;3&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Where are recurring fixes?&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;git log -i -E --grep=&quot;fix|bug|broken|regress&quot; --name-only --format=&apos;&apos; | sort | uniq -c | sort -nr | head -20&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Bug hotspots — files repeatedly being patched&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;4&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Is the project alive?&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;git log --format=&apos;%ad&apos; --date=format:&apos;%Y-%m&apos; | sort | uniq -c&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Velocity over time&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;5&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Does the team trust its pipeline?&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;git log --oneline --since=&quot;1 year ago&quot; | grep -iE &apos;revert|hotfix|emergency|rollback&apos;&lt;/code&gt;&lt;/td&gt;&lt;td&gt;Firefighting frequency&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The interesting move is &lt;strong&gt;intersecting&lt;/strong&gt; recipes 1 and 3. Files that appear in &lt;em&gt;both&lt;/em&gt; the churn list and the bug-hotspot list are the highest-risk targets — they’re unstable &lt;em&gt;and&lt;/em&gt; known-defective. Tornhill calls this the “principal hot spot” overlay.&lt;/p&gt;
&lt;h2 id=&quot;5-the-question-framework&quot;&gt;5. The question framework&lt;/h2&gt;
&lt;p&gt;The recipes are not load-bearing on their own; the questions are. CaaCS practitioners reframe every recipe as a question because that’s how the technique stays useful when you’re in a codebase whose tools differ from the source post:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;em&gt;Where is risk concentrated?&lt;/em&gt; → recipes 1 + 3, intersected&lt;/li&gt;
&lt;li&gt;&lt;em&gt;Who knows this code?&lt;/em&gt; → recipe 2 + per-file authorship&lt;/li&gt;
&lt;li&gt;&lt;em&gt;Is the project alive?&lt;/em&gt; → recipe 4&lt;/li&gt;
&lt;li&gt;&lt;em&gt;Does the team trust its pipeline?&lt;/em&gt; → recipe 5&lt;/li&gt;
&lt;li&gt;&lt;em&gt;Is anything abandoned?&lt;/em&gt; → last-touch dates + zero-coverage overlay&lt;/li&gt;
&lt;li&gt;&lt;em&gt;Is complexity load-bearing or accidental?&lt;/em&gt; → recipe 1 ∩ complexity overlay (radon for Python, rubycritic for Ruby, etc.)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;When the language changes, the recipes barely change but the &lt;em&gt;tools&lt;/em&gt; do (radon ⇄ rubycritic ⇄ rustdoc-coverage…). The questions stay constant.&lt;/p&gt;
&lt;h2 id=&quot;6-the-output-a-triage-document&quot;&gt;6. The output: a triage document&lt;/h2&gt;
&lt;p&gt;CaaCS doesn’t end with tables. It ends with a &lt;strong&gt;four-bucket triage&lt;/strong&gt; in the spirit of an Eisenhower matrix:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;┌─────────────────────────┬─────────────────────────┐&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ Fix this week           │ Fix this quarter        │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ (hot ∩ buggy ∩          │ (hot OR buggy,          │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│  critical)              │  not both)              │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;├─────────────────────────┼─────────────────────────┤&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ Parallelisable          │ Don&apos;t worry             │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│ (hot but stable —       │ (cold, not buggy,       │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;│  refactor candidates)   │  peripheral)            │&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;└─────────────────────────┴─────────────────────────┘&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;This shape forces a real prioritization decision and separates &lt;em&gt;urgency&lt;/em&gt; from &lt;em&gt;strategic value&lt;/em&gt;.&lt;/p&gt;
&lt;h2 id=&quot;7-limits-and-biases--why-caacs-can-lie-to-you&quot;&gt;7. Limits and biases — why CaaCS can lie to you&lt;/h2&gt;
&lt;p&gt;Forensic methods only see what’s in the data. Six biases consistently bite:&lt;/p&gt;








































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Bias&lt;/th&gt;&lt;th&gt;Effect&lt;/th&gt;&lt;th&gt;Mitigation&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Squash-merge distortion&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Compressed authorship → bus factor under-reports&lt;/td&gt;&lt;td&gt;Inspect upstream merge convention before trusting recipe 2&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Weak commit messages&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Bug-grep underperforms&lt;/td&gt;&lt;td&gt;Sanity-check by spot-reading 10 commits; aim for ≥80% true-positive rate&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Vanity files&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Lockfiles, CHANGELOGs dominate raw counts&lt;/td&gt;&lt;td&gt;Hard exclusion list before running recipes&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;No rename-following&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;History truncates at file rename&lt;/td&gt;&lt;td&gt;Pass &lt;code dir=&quot;auto&quot;&gt;--follow&lt;/code&gt; for per-file work&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;No complexity capture&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Raw churn ≠ complexity&lt;/td&gt;&lt;td&gt;Pair with radon / rubycritic / cloc&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Bus factor ≠ knowledge&lt;/strong&gt;&lt;/td&gt;&lt;td&gt;Low contributor count can mean stable, not abandoned&lt;/td&gt;&lt;td&gt;Require interpretation, not numerical reading&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;These six are encoded as a &lt;code dir=&quot;auto&quot;&gt;failure_modes&lt;/code&gt; block on the spec-kitty &lt;code dir=&quot;auto&quot;&gt;forensic-repository-audit&lt;/code&gt; tactic so that any contributor running the recipe sees the caveats inline.&lt;/p&gt;
&lt;h2 id=&quot;8-where-caacs-sits-among-adjacent-techniques&quot;&gt;8. Where CaaCS sits among adjacent techniques&lt;/h2&gt;









































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Technique&lt;/th&gt;&lt;th&gt;What it sees&lt;/th&gt;&lt;th&gt;What it misses&lt;/th&gt;&lt;th&gt;Relationship to CaaCS&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;Static analysis (linters, complexity)&lt;/td&gt;&lt;td&gt;Current structure&lt;/td&gt;&lt;td&gt;History, intent&lt;/td&gt;&lt;td&gt;Complementary overlay&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;DDD strategic classification&lt;/td&gt;&lt;td&gt;Intentional importance&lt;/td&gt;&lt;td&gt;Actual usage patterns&lt;/td&gt;&lt;td&gt;Complementary — what &lt;em&gt;should&lt;/em&gt; be core vs what &lt;em&gt;is&lt;/em&gt; hot&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Code review&lt;/td&gt;&lt;td&gt;Specific change quality&lt;/td&gt;&lt;td&gt;Pattern-level risk&lt;/td&gt;&lt;td&gt;Different time scale; CaaCS scopes review, doesn’t replace it&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Brown-field interview (#665/#666)&lt;/td&gt;&lt;td&gt;Tribal knowledge, design intent&lt;/td&gt;&lt;td&gt;Quantitative behavior&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Strict complement&lt;/strong&gt; — CaaCS surfaces the &lt;em&gt;what&lt;/em&gt;; the interview answers the &lt;em&gt;why&lt;/em&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Coverage analysis&lt;/td&gt;&lt;td&gt;Test gaps&lt;/td&gt;&lt;td&gt;Why coverage is low&lt;/td&gt;&lt;td&gt;Pair with recipes 1+3 for “hot ∩ buggy ∩ untested” red-list&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;A useful rule: &lt;strong&gt;CaaCS tells you which questions to ask; the other techniques answer them.&lt;/strong&gt;&lt;/p&gt;
&lt;h2 id=&quot;9-what-spec-kittys-doctrine-extension-adds&quot;&gt;9. What spec-kitty’s doctrine extension adds&lt;/h2&gt;
&lt;p&gt;When CaaCS was codified into spec-kitty’s doctrine system, three deliberate extensions:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Wrapped the recipes in an entry/exit-conditioned procedure&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;legacy-codebase-triage.procedure.yaml&lt;/code&gt;) so a contributor running it knows &lt;em&gt;when&lt;/em&gt; it’s the right tool. The Piechowski posts assume the reader has already decided.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Made the DDD overlay an explicit optional step&lt;/strong&gt;, reusing the existing &lt;code dir=&quot;auto&quot;&gt;strategic-domain-classification&lt;/code&gt; tactic. The source posts don’t mention DDD at all; treating the overlay as separate keeps provenance honest and lets the technique be used without DDD on projects that don’t have a context map.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Encoded the six biases as a mandatory &lt;code dir=&quot;auto&quot;&gt;failure_modes&lt;/code&gt; block in the tactic&lt;/strong&gt; so anyone running the recipe sees the caveats inline rather than discovering them by being misled.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;10-empirical-observations-from-the-spec-kitty-run&quot;&gt;10. Empirical observations from the spec-kitty run&lt;/h2&gt;
&lt;p&gt;Two passes, growing scope. The growth is what made the technique credible.&lt;/p&gt;
&lt;h3 id=&quot;first-pass--src-only-757-files-1y-window&quot;&gt;First pass — &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; only (757 files, 1y window)&lt;/h3&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Finding&lt;/th&gt;&lt;th&gt;Reading&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;F1 — 89.5% single-author concentration&lt;/td&gt;&lt;td&gt;Bus factor or maturity? Could not tell&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;F2 — &lt;code dir=&quot;auto&quot;&gt;cli/commands/agent/{tasks,workflow,mission}.py&lt;/code&gt; top of every list&lt;/td&gt;&lt;td&gt;Unambiguous refactor candidate&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Pipeline trust&lt;/td&gt;&lt;td&gt;~0.3% reverts/hotfixes — healthy&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Velocity&lt;/td&gt;&lt;td&gt;accelerating&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Cross-cutting &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt; ↔ &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; couplings&lt;/td&gt;&lt;td&gt;invisible by scope&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Test-coverage overlay&lt;/td&gt;&lt;td&gt;invisible by scope&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;The audit-vs-issue-tracker crosscheck produced &lt;strong&gt;zero STRONG matches&lt;/strong&gt; between the 14 catalogued findings and the 16 currently-open sub-issues under #822. The forensic surface and the operational backlog see different worlds.&lt;/p&gt;
&lt;h3 id=&quot;second-pass--full-corpus-src--tests--kitty-specs&quot;&gt;Second pass — full corpus (&lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;kitty-specs/&lt;/code&gt;)&lt;/h3&gt;

































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Finding&lt;/th&gt;&lt;th&gt;Update&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;F1 bus factor&lt;/td&gt;&lt;td&gt;&lt;strong&gt;89.5% → 95.2%.&lt;/strong&gt; Worse, not better. Tests and mission specs don’t dilute the signal — single author wrote those too. F1 reclassified from “bus-factor or maturity” to definitively &lt;strong&gt;bus factor.&lt;/strong&gt;&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;F2 hotspot list&lt;/td&gt;&lt;td&gt;&lt;strong&gt;Robust under scope expansion.&lt;/strong&gt; Top-19 of the full-corpus table is identical to the src/-only list. First non-&lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; entry doesn’t appear until rank 20.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;F15 (new) — test-update lag&lt;/td&gt;&lt;td&gt;F2 hotspots change with their tests only ~30% of the time. &lt;strong&gt;~70% of changes ship without test updates.&lt;/strong&gt; Empirically grounds the “untested invariants” gap audit (KC-WP3 in the F1 plan).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;F16 (new) — glossary middleware&lt;/td&gt;&lt;td&gt;13.9% test-to-src churn ratio — worst hot-file ratio in the corpus.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;F17 (new) — mission ↔ src/ coupling&lt;/td&gt;&lt;td&gt;Max 5 co-changes/year for any pair. The SDD pipeline separates spec and code commits structurally — invisible in commit history by design.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;F18 (new) — agent_utils/status.py&lt;/td&gt;&lt;td&gt;19.0% test ratio — under-tested hot file.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h3 id=&quot;what-the-second-pass-taught-about-the-technique-itself&quot;&gt;What the second pass taught about the technique itself&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Scope expansion served as an accidental validity test.&lt;/strong&gt; If the bus-factor finding had been an artefact of looking only at production code, broadening to tests and specs would have diluted it. Instead, it sharpened. That’s evidence the signal is &lt;em&gt;robust&lt;/em&gt;, not measurement noise.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The hotspot list survived the scope change unchanged.&lt;/strong&gt; Top-19 identical. F2 is not an artefact of where we looked.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Test coverage proxy via churn ratio works as a low-cost smoke test.&lt;/strong&gt; It found four under-tested hot files in one pass without running pytest-cov.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cross-cutting coupling between mission specs and source is structurally limited&lt;/strong&gt; in spec-kitty (max 5 co-changes/year for any pair) — the SDD pipeline separates them by design. This is itself a finding about the &lt;em&gt;workflow&lt;/em&gt;, not just the code.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;11-further-reading&quot;&gt;11. Further reading&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Books&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Adam Tornhill — &lt;em&gt;Your Code as a Crime Scene&lt;/em&gt; (Pragmatic Bookshelf)&lt;/li&gt;
&lt;li&gt;Adam Tornhill — &lt;em&gt;Software Design X-Rays&lt;/em&gt; (Pragmatic Bookshelf)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Tools&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;code-maat&lt;/code&gt; — Tornhill’s CLI for the deeper analyses (temporal coupling, knowledge maps)&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;cloc&lt;/code&gt; — file/SLOC inventory&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;radon&lt;/code&gt; — Python complexity overlay&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;rubycritic&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;brakeman&lt;/code&gt; — Ruby/Rails complementary overlays&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Papers&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Nagappan &amp;#x26; Ball (2005), &lt;em&gt;“Use of Relative Code Churn Measures to Predict System Defect Density”&lt;/em&gt; — foundational empirical justification&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Adaptations&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Piechowski, &lt;em&gt;“How I audit a legacy Rails codebase”&lt;/em&gt;&lt;/li&gt;
&lt;li&gt;Piechowski, &lt;em&gt;“Git commands before reading code”&lt;/em&gt;&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Internal artefacts&lt;/strong&gt; (this repo)&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Doctrine: &lt;code dir=&quot;auto&quot;&gt;packs/built-in/tactics/analysis/forensic-repository-audit.tactic.yaml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Doctrine: &lt;code dir=&quot;auto&quot;&gt;packs/built-in/procedures/legacy-codebase-triage.procedure.yaml&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Audit (2026-05, two-pass): &lt;code dir=&quot;auto&quot;&gt;docs/archive/plans/engineering-notes/architecture-audits/2026-05-spec-kitty-caacs.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Issue-tracker crosscheck: &lt;code dir=&quot;auto&quot;&gt;docs/archive/plans/engineering-notes/architecture-audits/2026-05-822-crosscheck.md&lt;/code&gt;&lt;/li&gt;
&lt;li&gt;Phase-3 synthesis (issue drafts, backlog triage, F1 knowledge-capture plan, meta-assessment): &lt;code dir=&quot;auto&quot;&gt;docs/plans/engineering-notes/architecture-audits/2026-05-phase3-*.md&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;docs/archive/plans/engineering-notes/architecture-audits/2026-05-caacs-meta-assessment.md&lt;/code&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
