pi-skill-shiori 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 This project follows semantic versioning.
 
+## [0.6.0] - 2026-06-29
+
+### Added
+
+- Bounded recommendation reason badges (`[trigger]`, `[description]`, `[low match]`) on recommended skills in auto-inject, `/shiori:recommend`, and `shiori_recommend` surfaces.
+- `Docs/recommendation-surface.md` describing badge vocabulary, a multi-skill example, and how badges relate to Always Visible Skill policy and recommendation metrics.
+- Tests for reason present, absent, low-confidence, and badge formatting.
+
+### Changed
+
+- Candidate summaries use compact badges instead of freeform `Why:` lines in the default Shiori surfaces.
+
 ## [0.5.0] - 2026-06-28
 
 ### Added

package/Docs/recommendation-surface.md

@@ -0,0 +1,62 @@
+# Recommendation surface
+
+This document describes how Pi Skill Shiori surfaces recommended skills and the bounded reason badges shown with each match.
+
+## Reason badges
+
+Shiori attaches a compact reason badge to each recommended skill. The vocabulary is intentionally small:
+
+| Badge | Meaning |
+|---|---|
+| `[trigger]` | A policy `triggers.include` phrase matched the user task. |
+| `[description]` | Skill name/description tokens matched strongly enough to pass `candidateInjection.minScore`. |
+| `[low match]` | The skill passed `minScore` but sits near the threshold; treat as a weaker suggestion. |
+
+When Shiori cannot classify a match, it omits the badge instead of inventing a freeform explanation.
+
+## Where badges appear
+
+- **Auto-inject candidates** in the system prompt (`## Pi Skill Shiori Candidates`)
+- **`/shiori:recommend` review mode** notifications and follow-up picker labels
+- **`shiori_recommend` tool** collapsed result line (badges only, no long reports)
+- **Pre-load summaries** when skills are queued for the agent
+
+Badges are labels, not confidence scores. Numeric scores remain available in expanded detail views when needed.
+
+## Example: multiple surfaced skills
+
+Task: `browser scraping screenshot`
+
+Possible matches:
+
+```text
+Matched 2 skill(s): playwright-cli [trigger], gstack-browse [description]
+```
+
+Auto-inject candidate block:
+
+```text
+## Pi Skill Shiori Candidates
+
+Relevant skills:
+- playwright-cli [trigger]: Browser automation, web scraping, screenshots. Load: shiori_load_skill({ skill: "playwright-cli" })
+- gstack-browse [description]: Headless browser QA for scripted flows. Load: shiori_load_skill({ skill: "gstack-browse" })
+```
+
+A near-threshold match degrades gracefully:
+
+```text
+- notes-helper [low match]: Search markdown notes in the vault. Load: shiori_load_skill({ skill: "notes-helper" })
+```
+
+## Relation to Always Visible Skill
+
+`alwaysVisible` controls which skills stay in the Skill Catalog during Zero-Catalog Mode. Reason badges apply only to **recommended** (`triggerable`) skills surfaced by retrieval — not to always-visible catalog entries.
+
+Always-visible skills may still appear as recommendations when they match a task; their badge explains the retrieval reason, not catalog visibility.
+
+## Relation to recommendation metrics
+
+`/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.

package/README.md

@@ -221,7 +221,7 @@ This writes a generated review file next to `.pi/skill-shiori.yml`. Review it be
 | `/shiori:bootstrap` | Generate a review draft policy from discovered skill descriptions. |
 | `/shiori:reload` | Ask what to reload, then rebuild Shiori’s skill inventory and optionally ask Pi to reload runtime resources. Code changes may still need full restart. |
 | `/shiori:recommend` | Ask what you need help with, then either pre-load matches and queue the task for the agent or review recommendations only. Planning phrases (e.g. `計画を立てたい`) return the dev-plan intake template without dumping SKILL bodies. |
-| `/shiori:stats` | Show operational counters. |
+| `/shiori:stats` | Show operational counters and a compact recommendation quality summary. |
 
 ## Tool
 
@@ -267,6 +267,59 @@ retrievalBackend: sqlite-fts
 code: prompt-boundary-v3
 ```
 
+## Recommendation reason badges
+
+Recommended skills show compact reason badges so you can see why Shiori surfaced them:
+
+- `[trigger]` — a policy trigger phrase matched
+- `[description]` — skill name/description tokens matched strongly
+- `[low match]` — passed `minScore` but near the threshold
+
+Badges appear in auto-inject candidates, `/shiori:recommend` review mode, pre-load summaries, and the `shiori_recommend` tool line. Unclassified matches omit the badge instead of showing a long explanation.
+
+Example with multiple surfaced skills:
+
+```text
+Matched 2 skill(s): playwright-cli [trigger], gstack-browse [description]
+```
+
+See [`Docs/recommendation-surface.md`](Docs/recommendation-surface.md) for how badges relate to Always Visible Skill policy and recommendation feedback metrics.
+
+## Recommendation feedback metrics
+
+`/shiori:stats` includes session-local recommendation feedback so operators can tune trigger rules from real outcomes instead of guesswork.
+
+Recorded (bounded, in-memory for the current Pi session):
+
+- recommendation offers and candidate slot counts per source (`auto-inject`, `command`, `tool`)
+- load follow-through when recommended skills are pre-loaded or later loaded via `shiori_load_skill`
+- abandoned recommendation flows (candidates shown but not loaded, e.g. review-only mode)
+- zero-candidate queries (obvious misses)
+- per-skill offered/loaded tallies (up to 50 skill names, oldest entries dropped first)
+
+Not recorded:
+
+- user prompts, task descriptions, or transcript bodies
+- skill `SKILL.md` contents
+- filesystem paths beyond skill names already visible in policy/inventory
+
+Retention boundary:
+
+- counters reset when the Pi session ends
+- no disk persistence or cross-session analytics in this slice
+- inspect the compact summary at the top of `/shiori:stats`, with full JSON below
+
+Example summary line:
+
+```text
+Recommendation feedback (session-local, no prompts stored)
+offers: 4 | candidate slots: 7 | loaded: 3
+abandoned: 1 | zero-candidate queries: 2 | follow-through: 42.9%
+auto-inject: offers=2, loaded=1, zeroHits=1
+command: offers=1, loaded=2, zeroHits=1
+top skills: auth-helper(1/2), deploy-kit(1/1)
+```
+
 ## Development
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skill-shiori",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Pi extension that reduces Agent Skill catalog tokens with policy-based skill retrieval and on-demand skill loading.",
   "type": "module",
   "license": "MIT",
@@ -27,6 +27,7 @@
     "LICENSE",
     "SECURITY.md",
     "CHANGELOG.md",
+    "Docs",
     "src"
   ],
   "scripts": {

package/src/index.ts

@@ -8,6 +8,7 @@ import type { SkillIndex } from "./indexer.js";
 import { loadRecommendedSkills } from "./load-skills.js";
 import { formatPlanningKickoffMessage, isPlanningIntent } from "./planning-kickoff.js";
 import { createStats } from "./metrics.js";
+import { createRecommendationFeedback } from "./recommendation-feedback.js";
 import { getPolicyPath, loadPolicy } from "./policy.js";
 import {
   formatCandidateDetail,
@@ -16,6 +17,7 @@ import {
   formatRecommendKickoffMessage,
   suppressSkillCatalog,
 } from "./prompt.js";
+import { formatReasonBadgeSuffix } from "./recommendation-reason.js";
 import { retrieveCandidatesExpanded } from "./retrieval-expanded.js";
 import type { SkillRecord } from "./types.js";
 
@@ -40,6 +42,7 @@ export default function piSkillShiori(pi: ExtensionAPI) {
   let inventoryRoots: string[] = [];
   let warnedAlwaysVisibleMissing = new Set<string>();
   const stats = createStats();
+  const recommendationFeedback = createRecommendationFeedback();
 
   async function reload(cwd: string): Promise<SkillIndex> {
     const policy = await loadPolicy(cwd);
@@ -126,8 +129,16 @@ export default function piSkillShiori(pi: ExtensionAPI) {
     }
 
     const candidates = retrieveCandidatesExpanded(event.prompt, current.skills, current.policy, current);
-    if (candidates.length === 0) stats.zeroCandidateCount += 1;
-    else stats.candidateHitCount += 1;
+    if (candidates.length === 0) {
+      stats.zeroCandidateCount += 1;
+      recommendationFeedback.recordZeroCandidates("auto-inject");
+    } else {
+      stats.candidateHitCount += 1;
+      recommendationFeedback.recordRecommendation(
+        "auto-inject",
+        candidates.map((candidate) => candidate.skill.name),
+      );
+    }
 
     const injection = formatCandidateInjection(candidates);
     const candidateSection = injection ? `\n\n## Pi Skill Shiori Candidates\n\n${injection}\n` : "";
@@ -153,7 +164,13 @@ export default function piSkillShiori(pi: ExtensionAPI) {
       const current = await ensureIndex(ctx.cwd);
       const policy = withRecommendLimits(current);
       const candidates = retrieveCandidatesExpanded(params.task, current.skills, policy, current);
+      const candidateNames = candidates.map((candidate) => candidate.skill.name);
       const loaded = await loadRecommendedSkills(candidates);
+      recommendationFeedback.recordRecommendation(
+        "tool",
+        candidateNames,
+        loaded.map((entry) => entry.candidate.skill.name),
+      );
       const summary = formatLoadedSkillsSummary(loaded);
       const blocks = loaded.map(({ candidate, content }) => ({
         type: "text" as const,
@@ -163,11 +180,16 @@ export default function piSkillShiori(pi: ExtensionAPI) {
         content: summary
           ? [{ type: "text", text: summary }, ...blocks]
           : [{ type: "text", text: "No matching skills for that task." }],
-        details: { query: params.task, matches: candidates.map((c) => c.skill.name) },
+        details: {
+          query: params.task,
+          matches: candidates.map((c) => `${c.skill.name}${formatReasonBadgeSuffix(c.reason)}`),
+        },
       };
     },
     renderResult(result, { expanded }, theme) {
-      const details = result.details as { query?: string; matches?: string[] } | undefined;
+      const details = result.details as
+        | { query?: string; matches?: string[] }
+        | undefined;
       const names = details?.matches?.join(", ") ?? "none";
       const collapsed = `${theme.fg("success", "✓ Shiori")} ${theme.bold(names)}`;
       if (!expanded) return new Text(collapsed, 0, 0);
@@ -193,6 +215,7 @@ export default function piSkillShiori(pi: ExtensionAPI) {
       if (!record) throw new Error(`Skill not found: ${params.skill}`);
       const content = await readFile(record.path, "utf8");
       stats.loadedSkillCount += 1;
+      recommendationFeedback.recordSkillLoaded(record.name);
       const details: ShioriLoadDetails = {
         skill: record.name,
         path: record.path,
@@ -305,12 +328,18 @@ export default function piSkillShiori(pi: ExtensionAPI) {
 
       const policy = withRecommendLimits(current);
       const candidates = retrieveCandidatesExpanded(query, current.skills, policy, current);
+      const candidateNames = candidates.map((candidate) => candidate.skill.name);
       const planning = isPlanningIntent(query);
       const reviewOnly = action === RECOMMEND_REVIEW_ONLY;
       const loaded = planning || reviewOnly ? [] : await loadRecommendedSkills(candidates);
+      recommendationFeedback.recordRecommendation(
+        "command",
+        candidateNames,
+        loaded.map((entry) => entry.candidate.skill.name),
+      );
       const summary = planning || reviewOnly
         ? candidates.length > 0
-          ? `Matched ${candidates.length} skill(s): ${candidates.map((c) => c.skill.name).join(", ")}`
+          ? `Matched ${candidates.length} skill(s): ${candidates.map((c) => `${c.skill.name}${formatReasonBadgeSuffix(c.reason)}`).join(", ")}`
           : ""
         : formatLoadedSkillsSummary(loaded);
 
@@ -341,14 +370,16 @@ export default function piSkillShiori(pi: ExtensionAPI) {
       }
 
       const choice = await ctx.ui.select("Follow up on a recommendation:", [
-        ...candidates.map((candidate) => candidate.skill.name),
+        ...candidates.map((candidate) => `${candidate.skill.name}${formatReasonBadgeSuffix(candidate.reason)}`),
         "Done",
       ]);
       if (!choice || choice === "Done") {
         return;
       }
 
-      const selected = candidates.find((candidate) => candidate.skill.name === choice);
+      const selected = candidates.find(
+        (candidate) => choice === `${candidate.skill.name}${formatReasonBadgeSuffix(candidate.reason)}`,
+      );
       if (!selected) {
         return;
       }
@@ -369,9 +400,20 @@ export default function piSkillShiori(pi: ExtensionAPI) {
   });
 
   pi.registerCommand("shiori:stats", {
-    description: "Show Pi Skill Shiori operational counters",
+    description: "Show Pi Skill Shiori operational counters and recommendation feedback",
     handler: async (_args, ctx) => {
-      ctx.ui.notify(JSON.stringify(stats, null, 2), "info");
+      const payload = {
+        ...stats,
+        recommendationFeedback: recommendationFeedback.summarize(),
+      };
+      ctx.ui.notify(
+        [
+          recommendationFeedback.formatSummary(),
+          "",
+          JSON.stringify(payload, null, 2),
+        ].join("\n"),
+        "info",
+      );
     },
   });
 

package/src/prompt.ts

@@ -1,4 +1,5 @@
 import { normalizeAlwaysVisible } from "./always-visible.js";
+import { formatReasonBadgeSuffix } from "./recommendation-reason.js";
 import type { SkillCandidate, SkillRecord, SuppressionStatus } from "./types.js";
 
 export interface CatalogSuppressionResult {
@@ -39,7 +40,7 @@ export function formatCandidateInjection(candidates: SkillCandidate[]): string {
   for (const candidate of candidates) {
     const desc = compactDescription(candidate.skill.description, COMPACT_DESCRIPTION_LIMIT);
     lines.push(
-      `- ${candidate.skill.name}: ${desc} Reason: ${candidate.why}. Load: shiori_load_skill({ skill: "${candidate.skill.name}" })`,
+      `- ${candidate.skill.name}${formatReasonBadgeSuffix(candidate.reason)}: ${desc} Load: shiori_load_skill({ skill: "${candidate.skill.name}" })`,
     );
   }
   return lines.join("\n");
@@ -70,8 +71,8 @@ export function formatRecommendKickoffMessage(
 
   for (const { candidate, content } of loaded) {
     lines.push(
-      `### Skill: ${candidate.skill.name}`,
-      `Score: ${candidate.score.toFixed(2)} | Why: ${candidate.why}`,
+      `### Skill: ${candidate.skill.name}${formatReasonBadgeSuffix(candidate.reason)}`,
+      `Score: ${candidate.score.toFixed(2)}`,
       `Path: ${candidate.skill.path}`,
       "",
       content.trim(),
@@ -87,17 +88,16 @@ export function formatLoadedSkillsSummary(loaded: Array<{ candidate: SkillCandid
   const lines = [`Pre-loaded ${loaded.length} skill(s):`];
   for (const { candidate } of loaded) {
     const desc = compactDescription(candidate.skill.description, COMPACT_DESCRIPTION_LIMIT);
-    lines.push(`- ${candidate.skill.name} (${candidate.score.toFixed(2)}): ${desc}`);
+    lines.push(`- ${candidate.skill.name}${formatReasonBadgeSuffix(candidate.reason)} (${candidate.score.toFixed(2)}): ${desc}`);
   }
   return lines.join("\n");
 }
 
 export function formatCandidateDetail(candidate: SkillCandidate): string {
   return [
-    candidate.skill.name,
+    `${candidate.skill.name}${formatReasonBadgeSuffix(candidate.reason)}`,
     `Description: ${candidate.skill.description}`,
     `Score: ${candidate.score.toFixed(2)}`,
-    `Why: ${candidate.why}`,
     `Path: ${candidate.skill.path}`,
     `Load: shiori_load_skill({ skill: "${candidate.skill.name}" })`,
   ].join("\n");

package/src/query.ts

@@ -28,10 +28,19 @@ const TERM_ALIASES: Record<string, string[]> = {
 };
 
 /** Whole-prompt intents → English queries that match planning skills in descriptions. */
-const INTENT_QUERY_PACKS: Array<{ test: RegExp; queries: string[] }> = [
-  {
-    test: /計画|プラン|立てたい|planning/i,
-    queries: [
+const INTENT_QUERY_PACKS: Array<{ test: RegExp; queries: string[] }> = [
+  {
+    test:
+      /\bx\s+(?:api|data|export|follower|monitor|post|search|social|timeline|tweet)\b|\b(?:twitter|tweet|timeline|follower)\b|social(?:\s+media)?/i,
+    queries: [
+      "tweet search social media data",
+      "twitter timeline follower export",
+      "x api tweet monitor",
+    ],
+  },
+  {
+    test: /計画|プラン|立てたい|planning/i,
+    queries: [
       "to-prd PRD plan",
       "to-issues breakdown plan",
       "grill me plan design",

package/src/recommendation-feedback.ts

@@ -0,0 +1,177 @@
+export type RecommendationSource = "auto-inject" | "command" | "tool";
+
+export interface SourceFeedbackCounts {
+  offers: number;
+  candidateSlots: number;
+  loaded: number;
+  zeroHits: number;
+}
+
+export interface SkillFeedbackCounts {
+  offered: number;
+  loaded: number;
+}
+
+export interface RecommendationFeedbackSummary {
+  totalOffers: number;
+  totalCandidateSlots: number;
+  totalLoaded: number;
+  totalAbandoned: number;
+  zeroCandidateQueries: number;
+  followThroughRate: number | null;
+  bySource: Record<RecommendationSource, SourceFeedbackCounts>;
+  topSkills: Array<{ name: string; offered: number; loaded: number }>;
+  retention: {
+    maxSkillEntries: number;
+    skillEntries: number;
+  };
+}
+
+const SOURCES: RecommendationSource[] = ["auto-inject", "command", "tool"];
+const MAX_SKILL_ENTRIES = 50;
+
+function emptySourceCounts(): SourceFeedbackCounts {
+  return { offers: 0, candidateSlots: 0, loaded: 0, zeroHits: 0 };
+}
+
+function emptyBySource(): Record<RecommendationSource, SourceFeedbackCounts> {
+  return {
+    "auto-inject": emptySourceCounts(),
+    command: emptySourceCounts(),
+    tool: emptySourceCounts(),
+  };
+}
+
+export interface RecommendationFeedback {
+  recordRecommendation(source: RecommendationSource, candidates: string[], loaded?: string[]): void;
+  recordZeroCandidates(source: RecommendationSource): void;
+  recordSkillLoaded(skillName: string): void;
+  summarize(): RecommendationFeedbackSummary;
+  formatSummary(): string;
+}
+
+export function createRecommendationFeedback(): RecommendationFeedback {
+  const bySource = emptyBySource();
+  const bySkill = new Map<string, SkillFeedbackCounts>();
+  const recentAutoInjectCandidates = new Set<string>();
+
+  let totalOffers = 0;
+  let totalCandidateSlots = 0;
+  let totalLoaded = 0;
+  let totalAbandoned = 0;
+  let zeroCandidateQueries = 0;
+
+  function bumpSkill(name: string, field: "offered" | "loaded"): void {
+    const current = bySkill.get(name) ?? { offered: 0, loaded: 0 };
+    current[field] += 1;
+    bySkill.set(name, current);
+    while (bySkill.size > MAX_SKILL_ENTRIES) {
+      const oldest = bySkill.keys().next().value;
+      if (oldest === undefined) break;
+      bySkill.delete(oldest);
+    }
+  }
+
+  function recordLoadedSkills(source: RecommendationSource, loaded: string[]): void {
+    for (const name of loaded) {
+      bumpSkill(name, "loaded");
+      bySource[source].loaded += 1;
+      totalLoaded += 1;
+      recentAutoInjectCandidates.delete(name);
+    }
+  }
+
+  return {
+    recordRecommendation(source, candidates, loaded = []) {
+      if (candidates.length === 0) {
+        this.recordZeroCandidates(source);
+        return;
+      }
+
+      totalOffers += 1;
+      totalCandidateSlots += candidates.length;
+      const sourceCounts = bySource[source];
+      sourceCounts.offers += 1;
+      sourceCounts.candidateSlots += candidates.length;
+
+      for (const name of candidates) {
+        bumpSkill(name, "offered");
+        if (source === "auto-inject") {
+          recentAutoInjectCandidates.add(name);
+        }
+      }
+
+      if (loaded.length > 0) {
+        recordLoadedSkills(source, loaded);
+      } else if (source !== "auto-inject") {
+        totalAbandoned += 1;
+      }
+    },
+
+    recordZeroCandidates(source) {
+      zeroCandidateQueries += 1;
+      bySource[source].zeroHits += 1;
+    },
+
+    recordSkillLoaded(skillName) {
+      if (!recentAutoInjectCandidates.has(skillName)) {
+        return;
+      }
+      recordLoadedSkills("auto-inject", [skillName]);
+    },
+
+    summarize() {
+      const followThroughRate =
+        totalCandidateSlots > 0 ? Number((totalLoaded / totalCandidateSlots).toFixed(3)) : null;
+
+      const topSkills = [...bySkill.entries()]
+        .map(([name, counts]) => ({ name, ...counts }))
+        .sort((a, b) => b.offered - a.offered || a.name.localeCompare(b.name))
+        .slice(0, 10);
+
+      return {
+        totalOffers,
+        totalCandidateSlots,
+        totalLoaded,
+        totalAbandoned,
+        zeroCandidateQueries,
+        followThroughRate,
+        bySource,
+        topSkills,
+        retention: {
+          maxSkillEntries: MAX_SKILL_ENTRIES,
+          skillEntries: bySkill.size,
+        },
+      };
+    },
+
+    formatSummary() {
+      const summary = this.summarize();
+      const rate =
+        summary.followThroughRate === null ? "n/a" : `${(summary.followThroughRate * 100).toFixed(1)}%`;
+      const lines = [
+        "Recommendation feedback (session-local, no prompts stored)",
+        `offers: ${summary.totalOffers} | candidate slots: ${summary.totalCandidateSlots} | loaded: ${summary.totalLoaded}`,
+        `abandoned: ${summary.totalAbandoned} | zero-candidate queries: ${summary.zeroCandidateQueries} | follow-through: ${rate}`,
+      ];
+
+      for (const source of SOURCES) {
+        const counts = summary.bySource[source];
+        if (counts.offers === 0 && counts.zeroHits === 0) continue;
+        lines.push(
+          `${source}: offers=${counts.offers}, loaded=${counts.loaded}, zeroHits=${counts.zeroHits}`,
+        );
+      }
+
+      if (summary.topSkills.length > 0) {
+        const skillLine = summary.topSkills
+          .slice(0, 5)
+          .map((skill) => `${skill.name}(${skill.loaded}/${skill.offered})`)
+          .join(", ");
+        lines.push(`top skills: ${skillLine}`);
+      }
+
+      return lines.join("\n");
+    },
+  };
+}

package/src/recommendation-reason.ts

@@ -0,0 +1,43 @@
+import type { RecommendationReasonKind, SkillCandidate } from "./types.js";
+
+/** Score within this margin above minScore is treated as low-confidence. */
+export const LOW_CONFIDENCE_MARGIN = 0.08;
+
+export const RECOMMENDATION_REASON_LABELS: Record<RecommendationReasonKind, string> = {
+  trigger: "trigger",
+  description: "description",
+  "low-confidence": "low match",
+};
+
+export type RecommendationMatchSource = "trigger" | "description";
+
+export function classifyRecommendationReason(
+  source: RecommendationMatchSource,
+  score: number,
+  minScore: number,
+): RecommendationReasonKind {
+  if (source === "trigger") return "trigger";
+  return score < minScore + LOW_CONFIDENCE_MARGIN ? "low-confidence" : "description";
+}
+
+export function formatReasonBadge(reason: RecommendationReasonKind | null | undefined): string {
+  if (!reason) return "";
+  const label = RECOMMENDATION_REASON_LABELS[reason];
+  return label ? `[${label}]` : "";
+}
+
+export function formatReasonBadgeSuffix(reason: RecommendationReasonKind | null | undefined): string {
+  const badge = formatReasonBadge(reason);
+  return badge ? ` ${badge}` : "";
+}
+
+export function attachRecommendationReason(
+  candidate: Omit<SkillCandidate, "reason">,
+  source: RecommendationMatchSource,
+  minScore: number,
+): SkillCandidate {
+  return {
+    ...candidate,
+    reason: classifyRecommendationReason(source, candidate.score, minScore),
+  };
+}

package/src/retrieval.ts

@@ -1,3 +1,4 @@
+import { attachRecommendationReason } from "./recommendation-reason.js";
 import type { ShioriPolicy, SkillCandidate, SkillRecord } from "./types.js";
 
 interface RetrievalIndex {
@@ -51,22 +52,30 @@ function evaluateSkill(
   const includes = skillPolicy?.triggers?.include ?? [];
   const matchedInclude = includes.find((trigger) => includesNormalized(normalizedQuery, trigger));
   if (matchedInclude) {
-    return {
-      skill,
-      score: 0.95,
-      why: `matched trigger "${matchedInclude}"`,
-    };
+    return attachRecommendationReason(
+      {
+        skill,
+        score: 0.95,
+        why: `matched trigger "${matchedInclude}"`,
+      },
+      "trigger",
+      policy.candidateInjection.minScore,
+    );
   }
   if (exactTriggerOnly) return undefined;
 
   const text = normalize(`${skill.name} ${skill.description} ${includes.join(" ")}`);
   const tokenScore = scoreTokens(normalizedQuery, text);
   if (tokenScore < policy.candidateInjection.minScore) return undefined;
-  return {
-    skill,
-    score: tokenScore,
-    why: "matched skill description",
-  };
+  return attachRecommendationReason(
+    {
+      skill,
+      score: tokenScore,
+      why: "matched skill description",
+    },
+    "description",
+    policy.candidateInjection.minScore,
+  );
 }
 
 function normalize(input: string): string {

package/src/types.ts

@@ -39,10 +39,13 @@ export interface SkillRecord {
   source: string;
 }
 
+export type RecommendationReasonKind = "trigger" | "description" | "low-confidence";
+
 export interface SkillCandidate {
   skill: SkillRecord;
   score: number;
   why: string;
+  reason: RecommendationReasonKind | null;
 }
 
 export interface ShioriStats {