chore(agents): create github-triage skill for Conventional Commit label triage and auditing

Open
#151 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
55/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
bash, github

Research direction

Start by comparing the existing .agents/skills/github-issues and github-pr skills, then read .github/labels.yml, docs/conventional-commits.md, and the referenced agent-skill and agent-script canons. Implement the specified SKILL.md and scripts/triage-audit.sh, update AGENTS.md and llms.txt, set execution permissions, and verify against the live repository state using the acceptance checklist.

Written by the indexing model from the issue text.

Description

scope: agents type: chore

1. Problem & Motivation

During a routine maintenance request to triage and backfill missing labels from issue #142 onward, the executing AI assistant encountered substantial friction, high turn latency, and excessive context consumption:

  • Cognitive Cold Start & Taxonomy Discovery: The assistant started with zero context regarding Canon Clerk's orthogonal Conventional Commit taxonomy (type:* for intent, scope:* for monorepo surface). It required more than 10 exploratory tool calls (git grep, reading .github/labels.yml, reading .github/workflows/pr-title-lint.yml, reading docs/conventional-commits.md, and inspecting historical commits like #130) merely to discover the repository's labeling invariants.
  • Ambiguity Around Evolving & Private Scopes: Recent issues introduced components not yet codified in .github/labels.yml:
    • #142 & #150: refactor(repo-settings): ...
    • #144: feat(lsp): ...
    • #149: feat(repo-lint): ...
      Without an operational runbook, the assistant had to conduct commit history archeology to determine whether repo-settings and repo-lint were recognized monorepo packages, whether private workspace packages (-private) should receive public scope labels, or whether new labels needed to be created.
  • The Limits of Pure Automation: A purely deterministic script cannot reliably --fix labels end-to-end:
    • Regex cannot resolve unrecognized scopes (e.g. knowing whether canon-clerk lsp belongs under scope: cli or a new scope: lsp).
    • Regex cannot enforce SemVer safety per .canons/conventional-commits/feat-commits-must-deliver-user-facing-features.md (e.g. verifying that an internal tooling change titled feat: does not trigger a false SemVer minor release).
    • Regex cannot detect community or status labels (blocked, help wanted, good first issue).
  • Operational Vacuum: Conversely, having no diagnostic tooling forced the assistant to manually fetch issues, parse titles one by one, cross-reference them by hand, and invoke individual gh issue edit commands sequentially.

The friction stemmed not from CLI mechanics, but from the absence of an agent operational runbook and a diagnostic extraction script working in tandem.


2. Core Invariants & Governance Tenets

  1. Orthogonal Matrix Decoupling: Issues and pull requests MUST be labeled with their intent (type:*) and, where applicable, their monorepo surface (scope:*) strictly adhering to .github/labels.yml and docs/conventional-commits.md.
  2. Division of Labor (Deterministic Extraction vs. Semantic Judgment):
    • Deterministic Scripts: Extract raw issue metadata, parse Conventional Commit syntax, validate against .github/labels.yml, and report deltas.
    • AI Agents: Grounded in SKILL.md, resolve semantic ambiguities, verify SemVer applicability, handle unknown scopes, and execute reviewed label changes.
  3. Strict Canon Alignment:
    • .canons/agent-skills/agent-skills-must-target-runtime-execution.md: SKILL.md must be an operational runbook for live execution, omitting redundant narrative.
    • .canons/agent-scripts/agent-scripts-must-orchestrate-composite-recipes.md: Companion scripts must orchestrate multi-step CLI operations.
    • .canons/agent-scripts/agent-scripts-must-be-pure-shell.md: Pure POSIX shell scripts (sh/bash), avoiding external language runtimes.
    • .canons/agent-scripts/agent-scripts-must-shunt-output-above-8kb.md: Output exceeding 8KB must shunt to /tmp/.

3. Proposed Solution: github-triage Skill

Scaffold a dedicated agent skill under .agents/skills/github-triage/ (harmonized with github-issues and github-pr):

3.1 Operational Runbook (.agents/skills/github-triage/SKILL.md)
  • Provide immediate, in-context reference for the type:* and scope:* matrix.
  • Codify standard resolution rules:
    • How Conventional Commit titles map to GitHub labels: type(scope): summary $\rightarrow$ type: <type>, scope: <scope>.
    • How to handle unrecognized scopes (e.g. apply type:* immediately; prompt maintainers on proposed scope labels).
    • Rules for private packages (e.g. avoiding public release-triggering feat/fix labels on -private packages).
  • Document the 4-step triage workflow: Scan $\rightarrow$ Audit $\rightarrow$ Review $\rightarrow$ Apply.
3.2 Companion Diagnostic Script (scripts/triage-audit.sh)
  • Implements a composite POSIX shell recipe:
    • Fetches open/recent issues and pull requests via gh.
    • Matches titles against ^(\w+)(?:\(([^)]+)\))?:.
    • Cross-references against .github/labels.yml.
    • Emits an unadorned TSV table:
      NUMBER | TYPE | SCOPE | STATUS | MISSING_LABELS | UNRECOGNIZED_SCOPES
    • Supports filtering (e.g. --unlabeled, --since <number>, --prs).
    • Shunts output to /tmp/triage-audit-<timestamp>.log if >8KB.

4. Acceptance Criteria Checklist

  • Scaffold .agents/skills/github-triage/SKILL.md compliant with all agent-skills canons.
  • Implement .agents/skills/github-triage/scripts/triage-audit.sh with pure bash, unadorned TSV output, and 8KB shunting.
  • Add execution permissions (chmod +x) and verify against live repository state.
  • Update AGENTS.md and llms.txt to register the new skill for assistant discovery.
Dominant language
Rust
Stars
0
Forks
1
Avg merge
1h 6m
Merged PRs (30d)
50

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from PAIR-code/canon-clerk

All issues in PAIR-code/canon-clerk

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.