poimen-memory/tasks/M3.7.3-skill-matching.md

M3.7.3 — GET /memory/skills?task= — match a subset to the work

Field	Value
Phase	M3.7 — Tool context
Size	M — 1–3 days
Status	⬜ Not started
Flags	—
Spec	inlined below
Blocks	M3.7.6
Depends	M3.5.5, M3.2, M2.1

Goal

Given a task, return the few skills that apply, so the orchestrator stops cloning the same static list for every piece of work.

Facts (inlined — no spec read needed)

GET /memory/skills?task=fix+the+kubectl+parsing+in+the+pod+debugger&project=homelab
→ 200 [{"name":"infra-root-causes","score":0.81,
        "matched_on":"when_to_use","when_to_use":"When troubleshooting cluster…"}]

Match on description and when_to_use, never on the body. Anthropic's own skill guidance, encoded in the installed grafana-core:skill-authoring rubric, makes description the field that decides whether a skill fires. Bodies are long, full of example output, and match everything — a skill whose body mentions kubectl in passing would be selected for every Kubernetes task. Matching the field the author wrote for this purpose also gives authors a lever they can reason about.

Embed the metadata, rerank the shortlist. Same two-stage shape as mem query (M3.3): embed description + when_to_use, cosine-recall a shortlist, then rerank against the task text with bge-reranker-base (M3.2). The corpus is small enough that recall could be exhaustive, but the reranker is what separates "mentions Kubernetes" from "is about diagnosing a failing pod".

Empty is a valid answer and must stay cheap. Most tasks match no skill. The endpoint returns [], not the closest thing it found, and the caller proceeds with tools and knowledge alone. A floor applies here for the same reason it does in M3.6.5: a plausible-but-wrong skill actively steers the implementer.

_drafts/ stays excluded. M3.5.5's rule is unchanged and load-bearing — matching must not become a side channel that loads an unpromoted skill.

Deterministic ties. Two skills at the same score sort by name, so an orchestrator that caches on the response is not invalidated by rank flapping between identical requests.

Steps

1. Extend the M3.5.5 handler with ?task= and ?limit= (default 3).
2. Build the match index over description + when_to_use for promoted skills.
3. Recall then rerank against the task text; apply the score floor.
4. Return score and matched_on so a bad match is diagnosable without a rerun.
5. Rebuild the index on skill promotion; no restart required.
6. ?task= absent keeps the existing full-catalog behaviour exactly.

Acceptance

• A Kubernetes debugging task matches the infra skill; an unrelated task does not.
• Draft skills never appear.
• No match returns [] with 200.
• Omitting task returns the full catalog, byte-identical to today.
• Equal scores order deterministically.

Verify

Harness: vault fixture with 6 promoted skills across distinct domains plus 2 drafts. Live reranker for scoring; deterministic embedder elsewhere.

Integration test — tests/it_skill_matching.rs:

1. a1_relevant_match — a pod-debugging task returns the infra skill first.
2. a2_irrelevant_no_match — "update the README changelog" returns [].
3. a3_drafts_excluded — a task whose text matches a draft's description verbatim returns [].
4. a4_body_not_matched — a skill whose body mentions kubectl but whose description is about something else is not returned for a kubectl task. This is the assertion that proves the field restriction.
5. a5_no_task_unchanged — omit task; assert byte-identical to M3.5.5's existing fixture output.
6. a6_floor_applies — a weakly-related task returns [] rather than the best-of-bad.
7. a7_deterministic_ties — two identically-described skills; assert stable name-ordered output across 10 calls.
8. a8_reranker_reorders — capture pre- and post-rerank order; assert they differ on at least one fixture task, proving the reranker is wired.
9. a9_promotion_visible — promote a draft, re-query without restart; assert it is now matchable.

Command: cargo test -p mem-api skill_matching

False pass:

• Fixtures whose descriptions share no vocabulary. Any embedder separates unrelated topics; assertion 4 needs a deliberate body/description conflict, and assertion 6 needs a genuinely borderline task, or both pass with a keyword LIKE.
• Asserting only that the right skill is present. Returning all 6 sorted also contains the right one; assert the length and the floor.

Traps

• Indexing skill bodies "for better recall". It inverts the design: bodies are where every skill looks alike, and the author's description stops being the control surface it was written to be.
• Tuning the floor against the same fixtures used to assert matching. It converges on a threshold that fits six skills and fails on sixty; hold out tasks.
• Rebuilding the index per request. It is small, but this endpoint sits in the path of every task the orchestrator runs.

---

Background: DESIGN.md — tool context, skills · M3.5.5