PAIR-code / PAIR-code/deliberate-lab

agents(skills): add issue-triage skill for maintainer issue classification and hygiene

Open
#1,259 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area:git area:workspace
Dominant language
TypeScript
Stars
96
Forks
40
Avg merge
2d 11h
Merged PRs (30d)
20

Description

Problem

Deliberate Lab receives bug reports, feature requests, and meta-tooling proposals from a diverse set of contributors, researchers, and maintainers. Across the backlog of open issues:

  • Over 80% lack Conventional Commit prefixes or scopes, using unstructured phrases (e.g. "Agents will skip the stage without answering questions").
  • Issues frequently lack ADR 0004 layer labels (runtime:*, area:*), or carry legacy catch-all labels like process.
  • Issue titles authored by AI coding agents frequently suffer from prefix drift (e.g. using feat(skills) or fix(build) rather than agents(skills) or build(lint)).
  • Descriptions often omit key context needed for implementation (e.g. whether a bug touches participant UX vs. experimenter UX, reproduction steps, or edge-case expectations).

Currently, maintainers must manually read each issue, mentally map it against repository taxonomy, construct conventional titles, and apply labels by hand via separate terminal commands.


Proposed Solution

Introduce a dedicated issue-triage pairing skill (.agents/skills/issue-triage/SKILL.md) that equips an AI agent to inspect and triage any GitHub issue on command.

1. Invocation

Trigger phrases:

  • "Let's triage issue "
  • "Triage issue "
  • "Audit issue "
2. The 4-Point Triage Rubric

Upon invocation, the agent inspects the issue losslessly using gh-issue-view.sh (per ADR 0003) and evaluates it against four standardized criteria:

  1. Architectural Layer Classification (ADR 0004):
    • Identifies which of the 6 repository layers the issue touches:
      • Product/Runtime: runtime:participant-ux, runtime:experimenter-ux, runtime:agents, runtime:backend
      • Developer/Operational: area:workspace, area:git, area:build, area:test, area:ci-deploy
  2. Conventional Title & Prefix Hygiene (#1258):
    • Transforms unstructured or misnamed titles into canonical type(scope): description.
    • Enforces runtime gating: feat: and fix: reserved strictly for user-facing product runtime.
    • Enforces developer tooling types: agents(...) for skills/workspace/decisions, build(...) for lint/build, chore(...) for repo-wide governance.
  3. Label Applicability & Audit:
    • Recommends labels to add (e.g. specific area:* or runtime:* tags).
    • Recommends legacy or conflicting labels to remove (e.g. retiring generic process).
  4. Clarity, Completeness & Repro Audit:
    • Evaluates whether problem statement, reproduction steps, expected behavior, and scope are clear.
    • Formulates targeted clarifying questions for the author if critical details or edge cases are underspecified.
3. Mandatory Human Authorization Gate
  • The skill presents a compact, formatted triage summary with the proposed title and label diff.
  • The agent strictly waits for explicit maintainer approval before executing any mutations (gh issue edit, gh issue comment).
  • When approved, updates are applied in a single shot.

Related Context
  • ADR 0003 (0003-agent-tooling-output-standards.md)
  • ADR 0004 (0004-repository-layer-taxonomy.md)
  • #1247 (Maintainer PR evaluation protocol)
  • #1258 (Adoption of agents(...) Conventional Commit prefix)

Contributor guide

Open the contributing guide

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.

Research direction

Create .agents/skills/issue-triage/SKILL.md and first read ADR 0003, ADR 0004, #1247, and #1258. Use the stated gh-issue-view.sh workflow and document the four-point rubric, invocation phrases, and human authorization gate before gh issue edit or gh issue comment. Done means the skill produces a compact title and label diff, asks clarification questions when needed, and waits for explicit approval before mutations.

Written by the indexing model from the issue text.

Assessment

Tech stack
github, markdown
Domain
developer-experience, tooling
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
72/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.