chore(agents): create github-triage skill for Conventional Commit label triage and auditing
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
- Domain
- cli, developer-experience, documentation, tooling
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
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, readingdocs/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 whetherrepo-settingsandrepo-lintwere recognized monorepo packages, whether private workspace packages (-private) should receive public scope labels, or whether new labels needed to be created.
- #142 & #150:
- The Limits of Pure Automation: A purely deterministic script cannot reliably
--fixlabels end-to-end:- Regex cannot resolve unrecognized scopes (e.g. knowing whether
canon-clerk lspbelongs underscope: clior a newscope: 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 titledfeat:does not trigger a false SemVer minor release). - Regex cannot detect community or status labels (
blocked,help wanted,good first issue).
- Regex cannot resolve unrecognized scopes (e.g. knowing whether
- 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 editcommands 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
- 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.ymlanddocs/conventional-commits.md. - 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.
- Deterministic Scripts: Extract raw issue metadata, parse Conventional Commit syntax, validate against
- Strict Canon Alignment:
.canons/agent-skills/agent-skills-must-target-runtime-execution.md:SKILL.mdmust 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:*andscope:*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/fixlabels on-privatepackages).
- How Conventional Commit titles map to GitHub labels:
- 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>.logif >8KB.
- Fetches open/recent issues and pull requests via
4. Acceptance Criteria Checklist
- Scaffold
.agents/skills/github-triage/SKILL.mdcompliant with allagent-skillscanons. - Implement
.agents/skills/github-triage/scripts/triage-audit.shwith pure bash, unadorned TSV output, and 8KB shunting. - Add execution permissions (
chmod +x) and verify against live repository state. - Update
AGENTS.mdandllms.txtto 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
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from PAIR-code/canon-clerk
-
scope: canons scope: cli type: ci
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
PAIR-code/canon-clerk#334 ·
Maintainers usually reply within 1 day
-
scope: canons type: refactor
Difficulty 2/5 1-3 hours Newbie friendliness 70/100
PAIR-code/canon-clerk#297 ·
Maintainers usually reply within 1 day
-
scope: canons type: chore
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
PAIR-code/canon-clerk#229 ·
Maintainers usually reply within 1 day
-
scope: canons type: chore
Difficulty 1/5 1-3 hours Newbie friendliness 85/100
PAIR-code/canon-clerk#228 ·
Maintainers usually reply within 1 day
-
scope: canons type: spec
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
PAIR-code/canon-clerk#105 ·
Maintainers usually reply within 1 day
All issues in PAIR-code/canon-clerk
Similar issues
-
priority: low
Difficulty 1/5 1-3 hours Newbie friendliness 83/100
storytold/vectorcraft#8387 · 2 comments ·
Maintainers usually reply within 1 day
-
area:desktop kind:test priority:p3 ready
Difficulty 2/5 1-3 hours Newbie friendliness 91/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
obi1kenobi/cargo-semver-checks#1814 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 85/100
BurntSushi/jiff#715 ·
Maintainers usually reply within 1 day