docs: Round 6b results — Kotlin capture fix + minimal coarsening

This commit is contained in:
tobjend 2026-07-12 01:05:19 +02:00
parent d65b78bdf1
commit 8540947eec

View file

@ -152,6 +152,37 @@ depends on how rich the highlights.scm is.
---
## Round 6b: Kotlin Capture Fix + Minimal Coarsening
**Hypothesis:** Kotlin's highlights.scm uses bare captures (`conditional`,
`exception`, `repeat`) while `BEHAVIORAL_PREFIXES` expected dotted forms
(`keyword.conditional`, etc.). All Kotlin structural context was being dropped.
**Method:** Added bare captures to BEHAVIORAL_PREFIXES. Dropped ATTR, TYPE,
VAR from coarsening (too noisy). Only coarsen RETURN, IF, EXCEPTION, LOOP.
**Result:**
| Codebase | Raw coverage | Coarsened coverage | Cross-pkg contexts |
|----------|-------------|-------------------|-------------------|
| RAGSAK k=3 | 18.5% | 6.0% | 87 (was 69) |
| Flask k=2 | 4.5% | 15.8% | 35 (was 54) |
| Flask k=3 | 17.1% | 17.3% | 28 (was 40) |
Key cross-package patterns (coarsened):
- `('IF', 'isEmpty', 'isEmpty')` — 8 RAGSAK packages (null-check convention)
- `('IF', 'isNullOrBlank', 'isNullOrBlank')` — 6 RAGSAK packages
- `('RETURN', 'render_template', 'render_template')` — 5 Flask packages
- `('IF', 'RETURN')` — 8 RAGSAK packages (guard clause pattern)
**Verdict:** The 4 high-signal categories (RETURN, IF, EXCEPTION, LOOP) DO
reveal cross-package conventions. Coarsening trades per-package coverage for
cross-package reach. Whether this is useful depends on the use case:
- For code completion: raw is better (specific method names)
- For documentation: coarsened is better (structural conventions)
---
## What We Learned (Summary)
1. **Per-package grouping is too sparse.** 1-3 sequences per package isn't