agentic-context-engine: Skill for Claude Code

Stage 1: Kayba API Analysis (Fetch-Only Mode)

Fetch pre-computed insights from the Kayba API. Traces have already been uploaded and analyzed — this stage only pulls results.

Inputs

• TRACES_FOLDER — passed by the orchestrator but ignored in this stage. Traces are already uploaded and analyzed on the Kayba side. Do NOT upload, validate, or read trace files.

Process

Step 1: Setup

Ensure eval/ directory exists at the project root.

Step 2: Fetch insights

kayba insights list --json > eval/insights.json

If kayba is not found in PATH, search common locations (.venv/bin/kayba, project virtualenvs). If found, use the full path. If not found anywhere, report the error and stop.

If KAYBA_API_KEY is not set, report the error and stop.

Step 3: Insight quality gate

Read eval/insights.json and run quality checks before building the summary:

1. Empty check: if the insights array is empty (0 insights returned), report this as a warning. Write a minimal summary noting "0 insights generated" and stop — downstream stages cannot proceed without insights.
2. Duplicate detection: compare insight content fields pairwise. If two insights cover substantially the same behavior (same section, overlapping evidence traces, similar corrective action), flag them as potential duplicates in the summary. Do not remove them — just annotate.
3. Evidence coverage: for each insight, check if the evidence field references specific traces (e.g., "task_7 turn 4"). Insights with no trace-specific evidence are lower quality — flag as "low-evidence" in the summary.
4. Vote signal: insights with status: "accepted" and helpful > 0 have been human-validated. Insights with status: "new" and helpful: 0, harmful: 0 are unvalidated — note this distinction in the summary.

Log the quality gate result: "Insight quality: {total} insights, {accepted} accepted, {new_unvalidated} unvalidated, {duplicates} potential duplicate pairs, {low_evidence} low-evidence"