gh-triage

Triage skill over GitHub. Reads open issues and PRs from a set of repos via state/lib/github.ts, clusters them by label, and surfaces items whose most recent activity is older than stale_days (default 7). Prevents the failure mode where a client issue sits untouched for two weeks because it wasn't in anyone's inbox.

Steps

1. Scope - no side effects

• Parse repos input into [{owner, repo}, ...].
• For each repo:
• listPrs(owner, repo, "open") → open PRs.
• getIssues(owner, repo, "open") → open issues (GitHub's issues endpoint

returns PRs too; filter with !item.pull_request so we don't double-count).

• Return a shape:

  { total_open, by_label: { [label]: count },
    stale: [{ repo, number, title, kind, days_since_update, html_url, labels }] }

• No writes. No comments. No CLI state mutation.

2. Gate

• Throw if repos is missing or empty.
• Throw if GITHUB_TOKEN is not in .env.cache (let env() do it).
• stale_days defaults to 7 when not supplied; must be a positive integer.

3. Act (only if the gate passes)

• For each repo, call listPrs and getIssues in parallel.
• Cluster: bucket every open item by each of its label names (one item may

land in multiple buckets - that's fine, it's a view, not a partition).

• Compute staleness: for each item compute

days_since_update = (now - new Date(item.updated_at)) / 86400000. Items with days_since_update > stale_days go into stale, sorted descending by age.

• Return the shape above. The orchestrator chooses whether to post it,

print it, or feed it into a digest.

4. Log + eval

append("chain", { run_id, skill: "gh-triage", action: "triaged",
                  repos: repos.length, total_open, stale_count });
score("gh-triage", run_id, {
  score:
    shape_ok && labels_clustered && stale_sorted ? 1.0 :
    shape_ok ? 0.5 :
    0.0,
  primary_issue:
    !shape_ok ? "shape-mismatch" :
    !labels_clustered ? "cluster-missing" :
    !stale_sorted ? "stale-unsorted" :
    null,
  total_open, stale_count, repo_count: repos.length,
});

Eval

Actor: state/lib/github.ts - the listPrs + getIssues calls that hit the real GitHub REST API and return live data. Auditor: the skill's own shape gate - a deterministic post-processor that checks: (a) top-level keys total_open, by_label, stale exist, (b) every stale entry has days_since_update > stale_days and the array is sorted desc, (c) by_label values are integers matching a re-count of the raw list. Shape gate is pure code, no LLM, no GitHub call - different system than the actor.

Score convention:

Gotchas

• GitHub /issues returns PRs too. The REST endpoint for issues

includes pull requests - every PR has a pull_request key. Filter !item.pull_request when counting pure issues, or you'll double-count every PR.

• Rate limit. Unauthenticated: 60 req/hr. With GITHUB_TOKEN: 5000/hr.

If you triage > 100 repos in a loop you will hit the cap - batch or paginate instead of hammering.

• updated_at vs created_at. Staleness is measured against

updated_at (includes comments, label changes, reviews). Using created_at will flag items that were discussed yesterday as stale.

• Client repos live in different owners. jcameron12/total,

snappy-ai/..., etc. Pass a flat repos list - the skill does not assume one org.

• Never git push --force to main and never push directly to main on

client repos (kernel SKILL.md hard rule). This skill is read-only by design, but if you graduate it into a script that posts comments, the hard rule still applies to any sibling script that writes.

Rubric

criteria:
  - name: output_shape_and_content
    kind: deterministic
    check: "The output JSON strictly conforms to the specified schema: { total_open, by_label: { [label]: count }, stale: [{ repo, number, title, kind, days_since_update, html_url, labels }] }, with correct data types and ranges for all fields."
  - name: stale_items_correctness
    kind: deterministic
    check: "All entries in the 'stale' array have 'days_since_update' greater than 'stale_days' (default 7 if not provided) and are sorted in descending order by 'days_since_update'."
  - name: no_side_effects
    kind: deterministic
    check: "Execute the skill with a mock GitHub API that logs all attempted writes. Verify no writes, comments, or CLI state mutations occurred during execution."
  - name: labels_clustering_accuracy
    kind: deterministic
    check: "The 'by_label' object accurately reflects a recount of all open items, where each item contributes to its respective label counts, and the 'total_open' count matches the sum of distinct open issues and PRs."

gh-triage - loader

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

Critical Rules

• GitHub /issues returns PRs too. The REST endpoint includes pull requests - every PR has a pull_request key. Filter !item.pull_request when counting pure issues, or you'll double-count every PR.
• Staleness is updated_at, not created_at. updated_at includes comments, label changes, reviews. Using created_at will flag items that were discussed yesterday as stale.
• Never git push --force to main, never push directly to main on client repos. This skill is read-only by design; if graduated into a script that posts comments, the hard rule still applies to any sibling script that writes.
• Rate limit: unauthenticated 60/hr, with GITHUB_TOKEN 5000/hr. Triage > 100 repos in a loop will hit the cap - batch or paginate.

Commands

| ui dashboard | state/skills/gh-triage/resources/ui.openui | |invoke: prose skill - for each {owner, repo}: listPrs(owner, repo, "open") + getIssues(owner, repo, "open") in parallel |verify: shape gate - total_open + by_label + stale exist; every stale entry has days_since_update > stale_days; array sorted desc; by_label integers match a re-count |eval log: state/log/evals.ndjson (auto eval - skill: "gh-triage")

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/gh-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

• Client repos live in different owners (jcameron12/total, snappy-ai/..., etc.). Pass a flat repos list - no implicit org assumption.
• An item may land in multiple label buckets (it's a view, not a partition) - that's fine, don't deduplicate

Self-Test

An agent reading this should correctly:

1. [ ] Filter !item.pull_request on /issues results to avoid PR double-count
2. [ ] Measure staleness against updated_at, not created_at
3. [ ] Refuse to add a git push --force step even in a graduated script

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] gh-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)] gh-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.