"""Which references to read first (ADR-0007, iteration 5 step 8). A Skill with many references leaves its reader to find the ones a task needs. For a Specialist whose Skills hold enough of them, this asks the decider, one graded question per reference, how much the task needs it, and names the ones it needs in the Specialist's context as `read_first`. It is a place to start, not a limit: the Specialist still loads whatever else it finds it needs. Without a decision nothing is named and the Specialist searches its Skills itself. Measured against live Jev on 2026-10-09, with the 14 infrastructure-code patterns and four tasks: every reference a task's Elements call for scored 1.39 to 1.92, and every one they do not, 0.01 to 0.96, except the Artifact Registry pattern for two designs that run containers (1.28 and 1.38). At 1.25 nothing needed is missed. """ from __future__ import annotations import logging from collections.abc import Mapping from pathlib import Path from app.engine.runtime import Decider, Question logger = logging.getLogger(__name__) NEEDED = ("not needed", "might help", "needed") # A Skill with fewer references than this is quicker read than asked about. MIN_REFERENCES = 4 _TASK_LIMIT = 12_000 _SUMMARY_LIMIT = 300 def references_of(skill_path: Path) -> dict[str, str]: """Each reference file of a Skill with what it says it covers: its title and its first paragraph.""" described: dict[str, str] = {} for file in sorted((skill_path / "references").glob("*.md")): lines = [line.strip() for line in file.read_text().splitlines()] title = next((line.lstrip("# ") for line in lines if line.startswith("#")), "") first = next( (line for line in lines if line and not line.startswith(("#", "-", "|"))), "", ) described[f"references/{file.name}"] = ( f"{title}. {first}".strip(". ")[:_SUMMARY_LIMIT] or file.stem ) return described def routable(skills: Mapping[str, Path]) -> dict[str, dict[str, str]]: """The Skills worth routing within: those with enough references to choose from.""" found = {name: references_of(path) for name, path in skills.items()} return {name: refs for name, refs in found.items() if len(refs) >= MIN_REFERENCES} async def read_first( decider: Decider, task: str, references: Mapping[str, Mapping[str, str]], *, threshold: float = 1.25, scope: str = "", ) -> list[dict[str, str]] | None: """The references the task needs, as `{"skill", "resource"}`. An empty list means none stood out. None means no decision was available.""" asked = { f"{skill}/{resource}": Question( "score", f"How much does this task need a reference on: {covers}?", NEEDED, ) for skill, resources in references.items() for resource, covers in resources.items() } if not task.strip() or not asked: return None answers = await decider.decide(task[:_TASK_LIMIT], asked, scope=scope) if answers is None: return None chosen = [] for key in asked: skill, resource = key.split("/", 1) if float(answers[key].value) >= threshold: chosen.append({"skill": skill, "resource": resource}) logger.info("Read first: %s", [item["resource"] for item in chosen] or "none") return chosen