Implement /assign self-assignment for good first issue issues

[rtibbles]

❌ This issue is not open for contribution. Visit Contributing guidelines to learn about the contributing process and how to find suitable issues.

Overview

Implement the /assign self-assignment mechanism for good first issue issues, as agreed in #47.

Complexity: High
Target branch: main

Context

Issue #47 proposed a /assign slash command for contributor self-assignment on help wanted issues. After discussion, the scope was narrowed and refined:

• Self-assignment is restricted to issues labeled both help wanted and good first issue (not all help wanted issues)
• Bot posts guidance as an issue comment when good first issue label is applied, rather than modifying issue headers
• When a contributor comments on a help wanted issue that is NOT good first issue, the bot declines and explains that only good first issue issues support self-assignment
• Notifications for bot activity go to #support-dev-notifications, not #support-dev
• The existing keyword detection for assignment requests is preserved for non-good first issue issues
• Contributors are limited to 2 assigned issues across all community repos, with a 7-day cooldown on recently unassigned issues
• Implementation extends the existing contributor-issue-comment script

The Change

1. Guidance comment on good first issue labeling

When the good first issue label is applied to an issue, the bot posts a comment explaining:

• The issue can be self-assigned via /assign
• Contributors should link open PRs to assigned issues
• The 2-issue limit and 7-day cooldown on recently dropped issues
• Link to the contributing guidelines

This is triggered via the manage-issue-header workflow, which already handles label events.

2. /assign command handling in contributor-issue-comment

When a contributor comments /assign on an issue:

• If the issue is help wanted + good first issue + unassigned + contributor is under the limit: assign them and post a confirmation
• If the issue is help wanted + good first issue + unassigned + contributor is at the limit: decline with a message listing their current assignments and recently dropped issues with remaining cooldown days
• If the issue is help wanted + NOT good first issue: decline explaining that only good first issue issues support self-assignment
• If the issue is help wanted + assigned to someone else: existing BOT_MESSAGE_ALREADY_ASSIGNED behavior
• If the issue is NOT help wanted: existing BOT_MESSAGE_ISSUE_NOT_OPEN behavior

3. Keyword-based assignment requests on good first issue issues

When existing keyword detection ("can I work on this", etc.) triggers on a good first issue issue, the bot reply includes guidance about the /assign command so the contributor can follow up with it.

4. Cross-repo limit checking

To enforce the 2-issue limit, query assigned issues across all community repos (kolibri, studio, kolibri-design-system, le-utils, .github, ricecooker). For the 7-day cooldown, query issue timeline events for recent unassignment events.

5. Slack notifications to #support-dev-notifications

Three new notification categories:

• Assignment requested (contributor commented /assign)
• Assignment approved (bot assigned the contributor)
• Assignment rejected (at limit or ineligible)

Self-assignment activity does not trigger #support-dev notifications.

How to Get There

Manual testing in the test-actions repo. To test against this branch, temporarily update the reusable workflow references in test-actions to point to the feature branch instead of main.

Note: this requires write permissions to test-actions, so manual testing may be reserved for reviewers.

• To trigger /assign handling: comment /assign on an issue labeled help wanted + good first issue
• To trigger the guidance comment: add the good first issue label to an issue
• To trigger keyword detection on good first issue: comment with assignment-request keywords (e.g. "can I work on this")
• To test the limit: assign a test contributor to 2 issues across community repos, then attempt /assign on a third
• To test the cooldown: unassign a test contributor from an issue, then attempt /assign within 7 days

Out of Scope

• Self-assignment on help wanted issues that are not also good first issue (future consideration — could be enabled after observing contributor progression)
• Changes to issue headers — guidance is delivered via bot comments, not header modifications
• A custom /unassign command — contributors can unassign themselves via the GitHub UI

Acceptance Criteria

Guidance comment on good first issue labeling

• When the good first issue label is applied to an issue, the bot posts a guidance comment explaining the /assign command, the 2-issue limit, the 7-day cooldown, the need to link PRs to assigned issues, and a link to the contributing guidelines
• If a previous guidance comment from the bot already exists on the issue, it is deleted before posting the new one

/assign command handling

• Commenting /assign on an unassigned help wanted + good first issue issue assigns the commenter and posts a confirmation message
• Commenting /assign on an unassigned help wanted + good first issue issue when the contributor has 2+ assigned issues (across all community repos) or recently dropped issues within the 7-day cooldown is declined with a message listing both current assignments and recently dropped issues with remaining cooldown days
• Commenting /assign on a help wanted issue that is NOT good first issue is declined with a message explaining that only good first issue issues support self-assignment
• Commenting /assign on an already-assigned help wanted issue triggers the existing BOT_MESSAGE_ALREADY_ASSIGNED behavior
• Commenting /assign on a non-help wanted issue triggers the existing BOT_MESSAGE_ISSUE_NOT_OPEN behavior
• /assign comments from core team members and close contributors are ignored (no bot response)

Keyword-based assignment requests

• Existing keyword detection on good first issue issues includes guidance about the /assign command in the bot reply
• Existing keyword detection behavior on non-good first issue issues is unchanged

Slack notifications

• Assignment requested, approved, and rejected events are sent to #support-dev-notifications
• Self-assignment activity does not trigger #support-dev notifications
• Existing Slack notification behavior for non-/assign comments is unchanged

Documentation

• docs/community-automations.md is updated with the new /assign behavior and decision matrix

References

• Proposal: Auto-assign contributors to help wanted issues via /assign command #47 — Original proposal and discussion
• test-actions repo — Manual testing environment
• Contributing guidelines — Linked from bot messages

AI usage

This issue was drafted iteratively with Claude Code, section by section. Claude explored the existing codebase (contributor-issue-comment.js, constants.js, manage-issue-header.js, workflows, and docs) to understand the current automation architecture, then drafted each section based on my input. I reviewed and edited each section before moving to the next. The acceptance criteria reflect decisions made in the #47 discussion between myself and MisRob — Claude synthesized those into structured criteria which I verified for accuracy and completeness.