feat: improve issue submission and triage workflow

[rwalworth]

Summary

This PR overhauls the issue submission and triage workflow for the Hiero C++ SDK. It replaces the five skill-level-specific issue submission templates with three problem-type templates (Bug, Feature, Task), adds a /finalize bot command that transitions triaged issues to ready-for-dev state, and adds maintainer and contributor documentation to support the new process.

Key Changes:

• Remove 5 skill-level issue templates; replace with 3 problem-type templates (Bug, Feature, Task)
• Add /finalize bot command that validates labels, updates issue title/body, and swaps status labels
• Extract shared helpers (api.js, logger.js) and refactor assign.js / unassign.js to use them
• Add maintainer triage guide and contributor issue-type guide
• Comprehensive snapshot-based tests for the finalize command (778+ lines)

Motivation

Previously, issue submitters chose a skill-level template themselves. Contributors cannot reliably assess implementation complexity, so difficulty labels were inconsistently applied and the triage step was unclear. The new process separates concerns:

• Submitters describe the problem (Bug, Feature, or Task)
• Maintainers assess complexity, apply skill/priority/kind labels, then run /finalize
• Contributors pick up well-structured, clearly labeled issues via /assign

This makes the contribution experience more predictable for everyone.

---

Changes

Issue Templates

Removed the five skill-level submission templates that asked contributors to self-assess complexity, which led to mislabeled issues:

Removed	Reason
01_good_first_issue_candidate.yml	Skill assessment is now a maintainer responsibility
02_good_first_issue.yml	"
03_beginner_issue.yml	"
04_intermediate_issue.yml	"
05_advanced_issue.yml	"

Added three problem-type templates that focus on describing the issue clearly:

Added/Updated	Type	Purpose
bug.yml	Bug	Report broken or unexpected behavior
feature.yml	Feature	Request a new user-facing SDK capability
task.yml	Task (new)	Propose maintenance, refactoring, or improvement work

All three templates now:

• Auto-apply status: awaiting triage (instead of a skill-level label)
• Include inline examples embedded as hidden HTML comments to guide submitters without cluttering the form
• Require structured fields: description, reproduction steps / proposed approach / implementation steps, expected/actual behavior, acceptance criteria

/finalize Bot Command

New finalize.js command triggered by commenting /finalize on an issue. The command:

1. Acknowledges the comment with a 👍 reaction
2. Verifies the commenter has triage-or-above repository permissions
3. Validates all required labels are correctly applied (all violations collected before responding):
   • status: awaiting triage must be present
   • Exactly 1 skill: label
   • Exactly 1 priority: label
   • Bug/Task: exactly 1 kind: label; Feature: 0 kind: labels
   • Issue type must be Bug, Feature, or Task
4. Builds an updated title with the skill-level prefix (e.g. [Beginner]: Fix thing)
5. Rebuilds the issue body in the standard skill-level template format (preserving submitter content)
6. Swaps status: awaiting triage → status: ready for dev
7. Posts a success comment

All failure paths post informative comments and tag maintainers when manual intervention is needed.

Files Added:

• .github/scripts/commands/finalize.js
• .github/scripts/commands/finalize-comments.js

Shared Helpers Extraction

Extracted reusable logic from assign.js and unassign.js into new shared helper modules:

• helpers/api.js — swapLabels, postComment, acknowledgeComment, hasLabel, getLabelsByPrefix
• helpers/logger.js — createDelegatingLogger for consistent log delegation across commands
• helpers/constants.js — Added READY_FOR_DEV label constant

Refactored assign.js and unassign.js to import from helpers instead of duplicating logic.

Bot Dispatcher Update

Updated bot-on-comment.js to route /finalize to the new handler alongside existing /assign and /unassign commands.

Documentation

File	Description
docs/contributing/issue-types.md	Explains the three issue types and when to use each
docs/maintainers/guidelines-triage.md	Step-by-step triage guide: labeling checklist, /finalize usage, edge cases
CONTRIBUTING.md	Updated to reference the new templates and /finalize workflow

---

Testing

Comprehensive snapshot-based test suite added in test-finalize-bot.js (778 lines).

Test coverage includes:

Scenario	Tests
Permission check — unauthorized (read-only, non-collaborator)	✅
Permission check — API error	✅
Label validation — all violation types (missing skill, extra skill, missing priority, missing kind, extra kind, Feature with kind, wrong status, unknown type)	✅
Multiple simultaneous violations	✅
Title prefix logic — no existing prefix, replace existing prefix, all skill levels	✅
Body reconstruction — all skill levels, original content preservation	✅
Update failure (API error during issue update)	✅
Label swap failure	✅
Successful finalization (all skill levels)	✅

Updated test-assign-bot.js to import helpers from the refactored location.

Test Plan:

• All existing assign/unassign bot tests pass
• All finalize bot tests pass (snapshot-verified)
• Bot dispatcher routes /finalize correctly

---

Files Changed Summary

Added (7 files)

• .github/scripts/commands/finalize.js
• .github/scripts/commands/finalize-comments.js
• .github/scripts/helpers/api.js
• .github/scripts/helpers/logger.js
• .github/ISSUE_TEMPLATE/task.yml
• docs/contributing/issue-types.md
• docs/maintainers/guidelines-triage.md

Modified (8 files)

• .github/ISSUE_TEMPLATE/bug.yml
• .github/ISSUE_TEMPLATE/feature.yml
• .github/scripts/bot-on-comment.js
• .github/scripts/commands/assign.js
• .github/scripts/commands/unassign.js
• .github/scripts/helpers/constants.js
• .github/scripts/tests/test-assign-bot.js
• CONTRIBUTING.md

Removed (5 files)

• .github/ISSUE_TEMPLATE/01_good_first_issue_candidate.yml
• .github/ISSUE_TEMPLATE/02_good_first_issue.yml
• .github/ISSUE_TEMPLATE/03_beginner_issue.yml
• .github/ISSUE_TEMPLATE/04_intermediate_issue.yml
• .github/ISSUE_TEMPLATE/05_advanced_issue.yml

---

Breaking Changes

None for SDK consumers. This PR touches only GitHub workflow tooling (issue templates, bot scripts, and documentation). There are no changes to the C++ SDK source, public API, or build system.

Existing issues already labeled status: ready for dev are unaffected. New issues will now use the three-template system and require maintainer triage before becoming available for contributors.

[github-actions]

Hey @rwalworth 👋 thanks for the PR!
I'm your friendly PR Helper Bot 🤖 and I'll be riding shotgun on this one, keeping track of your PR's status to help you get it approved and merged.

This comment updates automatically as you push changes -- think of it as your PR's live scoreboard!
Here's the latest:

---

PR Checks

✅ DCO Sign-off -- All commits have valid sign-offs. Nice work!

---

✅ GPG Signature -- All commits have verified GPG signatures. Locked and loaded!

---

✅ Merge Conflicts -- No merge conflicts detected. Smooth sailing!

---

✅ Issue Link -- Linked to #1278 (assigned to you).

---

🎉 All checks passed! Your PR is ready for review. Great job!

[exploreriii]

I really like this so many things about this idea, and can see it improves many things. I will need more time to consider this for a review, because there are some situations that have me thinking and understand what sort of costs can be involved. I assume these are not very important right now though

[rwalworth]

I really like this so many things about this idea, and can see it improves many things. I will need more time to consider this for a review, because there are some situations that have me thinking and understand what sort of costs can be involved. I assume these are not very important right now though

Thanks for the detailed review @exploreriii - really helpful!

On the "costs" question, I think we're in good shape on all fronts:

• API rate limits: Each /finalize invocation makes ~4–5 GitHub REST API calls. GITHUB_TOKEN in Actions allows 1,000 requests/hr per repository, which means we'd need 200+ finalizations in a single hour before coming close to the limit. That's not a realistic concern for typical triage activity.
• Bot maintenance: This shouldn't be a significant ongoing burden. A lot of the complexity is now extracted into shared helpers (api.js, logger.js), and the snapshot tests mean we'll catch regressions early without needing to manually revisit the logic. Once the implementation stabilizes, there's not much reason to touch it.
• Workflow complexity: For the most part, this is how we already handle issue submissions but now it's streamlined and more correct. The old approach of having contributors self-select a skill level was backwards; they don't know what skill level the issue is, and those labels carry real meaning for the backlog. This gives the project team proper control over how issues are categorized, prioritized, and surfaced to contributors - which directly affects the roadmap and contributor experience.

Happy to dig into any specifics if something is still giving you pause!

[gsstoykov]

Overall looks good.
Btw is the plan to enforce people to use these commands and etc. We should keep in mind that a random person hopping in the SDK would just want to see an issue and contribute not having to know all this stuff.

[rwalworth]

Overall looks good. Btw is the plan to enforce people to use these commands and etc. We should keep in mind that a random person hopping in the SDK would just want to see an issue and contribute not having to know all this stuff.

The /finalize command is meant to be a tool that the project team can use during triage before an issue becomes ready for contributors. By the time a contributor can take an issue in the backlog, it's already been finalized and structured.

From a contributor's perspective, the experience will be exactly the same as before:

1. Find an issue labeled status: ready for dev
2. Comment /assign (which is directly stated in every issue template)
3. Submit a PR

There won't be much of a visible change for contributors outside of using the new templates to submit issues - which now no longer allow the issue submitter to decide on the skill level of the issue.