pi-skill-shiori 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 
 This project follows semantic versioning.
 
+## [0.6.2] - 2026-07-02
+
+### Fixed
+
+- Expanded retrieval (`retrieveCandidatesExpanded`) now preserves `[trigger]` badges when query variants also score the skill higher via description tokens.
+
+### Changed
+
+- `Docs/recommendation-surface.md` documents the dogfood review outcome and recommendation to keep badges on default surfaces.
+
 ## [0.6.1] - 2026-07-01
 
 ### Changed

package/Docs/recommendation-surface.md

@@ -60,3 +60,18 @@ Always-visible skills may still appear as recommendations when they match a task
 `/shiori:stats` recommendation feedback records offers, loads, and follow-through by source (`auto-inject`, `command`, `tool`). Metrics do **not** store reason badges or per-reason tallies.
 
 Use badges to understand individual suggestions during a session. Use metrics to see whether recommendations are being loaded after they are offered.
+
+## Dogfood review (0.6.2)
+
+Reviewed the badge rollout across `/shiori:recommend` review mode, auto-inject candidate blocks, and `shiori_recommend` collapsed output using realistic skill policies and natural-language tasks (`browser scraping screenshot`, `auth login`, `vault search markdown`).
+
+### Findings
+
+- **Trust:** Compact badges clarify *why* a skill surfaced when they match the retrieval path. Users can distinguish policy trigger hits from description token matches without reading long `Why:` lines.
+- **Noise:** The three-label vocabulary stays short enough for picker labels and tool summaries. No extra badge is shown when retrieval cannot classify a match.
+- **Friction fixed:** Expanded retrieval (`buildRetrievalQueries`) evaluates per-token variants. A description-only variant could outscore a trigger match and incorrectly replace `[trigger]` with `[description]`. Merge logic now keeps trigger classification when any variant fired a policy trigger.
+- **Deferred:** Broader recommendation-model changes (new badge types, per-reason metrics, confidence scores in default surfaces) stay out of scope.
+
+### Recommendation
+
+Keep reason badges on the default recommendation surfaces. Treat `[trigger]` as the authoritative label whenever policy triggers matched, even if expanded queries also score the description highly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skill-shiori",
-  "version": "0.6.1",
+  "version": "0.6.2",
   "description": "Pi extension that reduces Agent Skill catalog tokens with policy-based skill retrieval and on-demand skill loading.",
   "type": "module",
   "license": "MIT",

package/src/retrieval-expanded.ts

@@ -18,9 +18,7 @@ export function retrieveCandidatesExpanded(
   for (const variant of buildRetrievalQueries(query)) {
     for (const candidate of retrieveCandidates(variant, skills, policy, index)) {
       const previous = byName.get(candidate.skill.name);
-      if (!previous || candidate.score > previous.score) {
-        byName.set(candidate.skill.name, candidate);
-      }
+      byName.set(candidate.skill.name, preferExpandedCandidate(previous, candidate));
     }
   }
 
@@ -28,3 +26,14 @@ export function retrieveCandidatesExpanded(
     .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name))
     .slice(0, max);
 }
+
+/** Keep trigger badges when expanded query variants also score the description higher. */
+function preferExpandedCandidate(
+  previous: SkillCandidate | undefined,
+  candidate: SkillCandidate,
+): SkillCandidate {
+  if (!previous) return candidate;
+  if (previous.reason === "trigger") return previous;
+  if (candidate.reason === "trigger") return candidate;
+  return candidate.score > previous.score ? candidate : previous;
+}