Backed by: state/lib/sweep.ts + state/lib/xano.ts

bug-triage

Reads sweep snapshot (filtering to items matching bug keywords), gh issue list --state=open across active repos, and Xano error-log rows from the last N days. Clusters by stack-trace fingerprint or keyword overlap.

Steps

1. Collect the three sources in parallel.
2. Normalize to {source, ref, text, ts, repo?}.
3. Cluster: exact-match on stack fingerprint first, then fuzzy on

keyword Jaccard ≥ 0.4.

1. Rank clusters by size × recency.
2. Emit state/log/bug-triage/<date>.md.

Eval

score("bug-triage", run_id, {
  score:
    shape_ok && clusters_are_unique ? 1.0 :
    shape_ok ? 0.5 :
    0.0,
  total_signals: total,
  cluster_count: clusters.length,
  unclustered: unclustered.length,
  primary_issue:
    !shape_ok ? "shape-failed" :
    unclustered.length > total * 0.5 ? "clustering-threshold-too-tight" :
    null,
});

clusters_are_unique: no two clusters share the same fingerprint. Shape gate prevents silent clustering failure.

Gotchas

• gh must be authenticated; if not, log the auth failure and continue

with the other two sources rather than hard-failing.

• Jaccard threshold 0.4 is a guess; tune once we have a week of data.

Rubric

criteria:
  - name: output_file_exists
    kind: deterministic
    check: "The skill must produce the file 'state/log/bug-triage/<date>.md'."
  - name: output_contains_clusters
    kind: deterministic
    check: "The 'state/log/bug-triage/<date>.md' file must contain clearly delineated clusters of bug signals."
  - name: cluster_uniqueness
    kind: deterministic
    check: "The evaluation metric 'clusters_are_unique' as defined in the skill's eval section must be true, indicating no two clusters share the same fingerprint."
  - name: data_source_inclusion
    kind: judge
    check: "The generated clusters in 'state/log/bug-triage/<date>.md' must visibly incorporate signals from sweep, GitHub issues, and Xano error logs if available."

bug-triage - loader

Per-turn rules for the bug-triage skill. Full reference: state/skills/bug-triage/SKILL.md. Do not skip these.

Critical Rules

• NEVER hard-fail when gh is unauthenticated - log the auth failure and continue with the other two sources (sweep + Xano)
• ALWAYS cluster by exact stack-fingerprint FIRST, then fall back to fuzzy keyword Jaccard ≥ 0.4 - not the other way around
• ALWAYS rank clusters by size × recency, not size alone - old loud bugs shouldn't drown out fresh ones

Commands

| ui dashboard | state/skills/bug-triage/resources/ui.openui | |invoke: collect sweep snapshot + gh issue list --state=open + Xano error-log, normalize, cluster, write state/log/bug-triage/<date>.md |verify: clusters_are_unique (no two clusters share the same fingerprint) AND shape gate |eval log: state/log/evals.ndjson (skill: "bug-triage")

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/bug-triage/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Jaccard threshold 0.4 is a guess. Tune once a week of data exists. If unclustered.length > total * 0.5, primary_issue is clustering-threshold-too-tight.
• shape_ok is the floor - score 0.5 if shape passes but uniqueness fails; 0.0 if shape itself fails.

Self-Test

An agent reading this should correctly:

1. [ ] Continue triage when gh auth is missing (log + proceed)
2. [ ] Cluster by stack-fingerprint before keyword Jaccard
3. [ ] Flag unclustered > 50% as a tuning issue, not a failure

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] bug-triage: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] bug-triage: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.