Promote attune-rag alias-expansion-sweep aliases into upstream frontmatter

[silversurfer562]

Context

attune-rag completed an alias-expansion-sweep (docs/specs/alias-expansion-sweep/) that closed a 41pp R@3 gap on paraphrased developer queries against the bundled help corpus. The mechanism:

• Diagnostic-1 (attune-rag/docs/specs/embedding-retriever/diagnostic-1.md) measured KeywordRetriever collapsing on paraphrased queries (P@1 97.5% → 11.25%, R@3 100% → 28.75%).
• Diagnostic-3 (diagnostic-3.md) proved that hand-authored multi-token aliases on a single feature closed +50pp R@3 with zero baseline regression and zero new dependency.
• The sweep then applied that lever across 6 feature clusters (PRs #94–#99), landing paraphrased R@3 at 70% exactly (M13 acceptance criterion).

These aliases currently live in attune-rag/src/attune_rag/corpus/aliases_override.json as a temporary home — that override mechanism was built so the sweep could ship without requiring a new attune-help release per cluster. The long-term home is attune-help frontmatter so the aliases ship with the templates themselves.

What this issue tracks

Promote the 89 proven aliases (across 6 templates) from attune-rag's override file into upstream attune-help frontmatter. One attune-help release; six file edits; no behavior change. After the upstream release lands and attune-rag pins to the new attune-help version, attune-rag's aliases_override.json entries become redundant and can be deleted.

Inventory — 89 aliases across 6 templates

Source: attune-rag/src/attune_rag/corpus/aliases_override.json

concepts/tool-bug-predict.md (20 aliases)

Append to existing frontmatter aliases: list:

- dangerous code
- harmful patterns
- weak points
- fragile code
- code landmines
- danger zones
- what could go wrong
- silent failures
- fails silently
- hidden bugs
- PR risk review
- dangerous PR
- diff risk
- diff bite
- worrisome code
- shaky code
- commit risk
- production risk
- code that bites
- review risky changes

concepts/tool-security-audit.md (14 aliases)

Frontmatter currently has empty aliases: []. Add:

- unsafe input
- input handling
- leaked credentials
- leaked tokens
- exposed secrets
- attackers break in
- attack surface
- exploit surface
- exploit code
- security check
- service compromised
- compromised system
- risky function calls
- potentially attackable

concepts/tool-release-prep.md (14 aliases)

Append to existing frontmatter aliases: list:

- before pushing
- before pushing out
- before release
- push to users
- push to the world
- push code out
- push package
- push out the release
- ship to production
- ship to users
- release gate
- release checklist
- version bump
- tag a release

concepts/tool-smart-test.md (14 aliases)

Frontmatter currently has empty aliases: []. Add:

- safety nets
- build safety nets
- safety net for code
- untouched module
- untouched code
- untested code
- shore up coverage
- shore up tests
- functions need assertions
- assertions for functions
- missing tests
- test coverage gaps
- no tests yet
- code with no tests

concepts/tool-fix-test.md (13 aliases)

Append to existing frontmatter aliases: list:

- suite is red
- red test suite
- tests are red
- red after merge
- broken after merge
- figure out failures
- figure out why tests fail
- diagnose test failures
- diagnose failures
- blocking my merges
- blocking merges
- merges blocked
- fix broken suite

concepts/tool-code-quality.md (15 aliases)

Frontmatter currently has empty aliases: []. Add:

- once-over module
- give once-over
- module once-over
- quick once-over
- evaluate craftsmanship
- evaluate code changes
- code craftsmanship
- raise the bar
- raise code bar
- raise quality bar
- clean module
- keep code clean
- module clean code
- code health check
- polish code

Constraints to honor when promoting

1. Global alias uniqueness. attune-help's frontmatter parser (or its consumers like attune-rag's DirectoryCorpus) raises DuplicateAliasError if any alias appears on two templates. The 89 aliases above were chosen so they don't collide with each other or with existing frontmatter aliases as of attune-help 0.11.0. A pre-merge check should re-verify against whatever main is at promotion time.
2. Each alias must be 2+ tokens after stemming. attune-rag's KeywordRetriever.MIN_ALIAS_OVERLAP = 2 requires at least two query-token overlaps before crediting an alias. Single-token aliases get silently dropped. Every alias above was pre-validated with attune_rag.retrieval._tokenize.
3. Stemmer-aware authoring. A few real footguns from the sweep — e.g., "diff bites" stems to {diff, bit} (not {diff, bite}) and lost the intended overlap with "bite me" queries; corrected to "diff bite". When adding new aliases later, verify each candidate with _tokenize() first.
4. No removal or rewording of existing frontmatter aliases. Promotion is purely additive.

After promotion lands

1. attune-help releases a new patch/minor with these aliases in frontmatter.
2. attune-rag bumps its attune-help>=X.Y.Z,<X.(Y+1) floor pin.
3. attune-rag removes the corresponding entries from aliases_override.json (the file can either go away entirely or stay as a stub for future temporary additions — design call at that point).
4. attune-rag re-runs docs/specs/embedding-retriever/run_diagnostic_1.py against the new attune-help to verify the paraphrased R@3 ≥ 70% result is preserved end-to-end.

Related

• attune-rag spec: docs/specs/alias-expansion-sweep/ — see tasks.md M13.4 for the originating tracking entry.
• attune-rag deferred spec: docs/specs/embedding-retriever/ — kept as the artifact bundle and revival path if a future diagnostic finds the alias lever insufficient.