🧠 Advanced

This issue is well-suited for contributors who are very familiar with the Hiero C++ SDK and enjoy working with its core abstractions and design patterns.

Advanced Issues often involve:

• Exploring and shaping SDK architecture
• Reasoning about trade-offs and long-term impact
• Working across multiple modules or systems
• Updating tests, examples, and documentation alongside code

The goal is to support thoughtful, high-impact contributions in a clear and collaborative way.

---

---

🐞 Problem Description

The current issue submission workflow requires contributors to select a skill-level template (Good First Issue, Beginner, Intermediate, Advanced) when creating a new issue. This is fundamentally backwards: a contributor submitting an issue has no way to assess what skill level it will require to implement. Skill difficulty can only be evaluated by someone already deeply familiar with the codebase — a maintainer.

As a result, issues are often mislabeled, contributors pick up work that is too complex or too simple for their current level, and the triage process lacks a clear, enforced handoff point between "submitted" and "ready for a contributor to pick up."

There is also no structured way for maintainers to finalize an issue after triage. Currently, a maintainer must manually update the issue title, apply labels, and ensure the description matches the skill-level template — this is tedious, inconsistently done, and easy to forget.

Affected areas:

• .github/ISSUE_TEMPLATE/ — all five skill-level templates, plus bug.yml and feature.yml
• .github/scripts/bot-on-comment.js — the slash command dispatcher
• .github/scripts/commands/ — where new /finalize command logic will live
• .github/scripts/helpers/constants.js — shared label constants
• docs/contributing/ — contributor-facing documentation (currently missing issue type guidance)
• docs/maintainers/ — maintainer workflow documentation

---

💡 Proposed / Expected Outcome

Replace the skill-level issue templates with three type-based templates — Bug, Feature, and Task — that any contributor can use to submit an issue without needing to know its difficulty. These templates auto-apply a status: awaiting triage label to signal to maintainers that the issue needs review.

Introduce a /finalize bot command, restricted to contributors with triage-or-above
repository permissions, that:

1. Validates that all required labels have been correctly applied (skill, priority, kind for bugs/tasks, status) and posts a descriptive comment listing any violations if not
2. Updates the issue title to include the appropriate skill-level prefix (e.g., [Beginner]: ...)
3. Reformats the issue body into the structured skill-level template format — reserving the submitter's original content while adding the standard skill-level boilerplate sections (intro, about-this-level callout, contribution guide, additional info)
4. Swaps status: awaiting triage → status: ready for dev

Additionally, add comprehensive contributor-facing documentation explaining what constitutes a Bug, Feature, and Task, and update maintainer documentation to describe the full triage workflow including how and when to use /finalize.

Label enforcement rules (applied by /finalize):

Label group	Rule
skill:	Exactly 1 required
priority:	Exactly 1 required
kind:	Exactly 1 for Bug and Task; 0 for Feature
scope:	Any number (not enforced)
status:	Exactly 1 required; must be status: awaiting triage

---

🧠 Implementation & Design Notes

Files to delete

Remove the five existing skill-level templates — these are replaced by the three new type-based templates:

• .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

New / updated issue templates

All three templates should be comprehensive (with examples, like the current skill templates) and use consistent H2 markdown section headers so /finalize can parse and extract content.

• bug.yml — sections: Description, Steps to Reproduce, Expected Behavior, Actual Behavior, Environment (version/OS/compiler inputs), Acceptance Criteria, Additional Information.
  Labels: ['status: awaiting triage']. Type: Bug.

• feature.yml — sections: Problem Description, Proposed Solution, Alternatives Considered, Implementation Notes, Acceptance Criteria, Additional Information.
  Labels: ['status: awaiting triage']. Type: Feature.

• task.yml — sections: Description of the Task, Proposed Approach, Implementation Steps, Acceptance Criteria, Additional Information.
  Labels: ['status: awaiting triage']. Type: Task.

/finalize command — new files

• .github/scripts/commands/finalize.js — main handler
• .github/scripts/commands/finalize-comments.js — comment builders and per-skill-level boilerplate constants

Permission check: Use github.rest.repos.getCollaboratorPermissionLevel(). The response role_name field returns read | triage | write | maintain | admin. Allow triage and above. Treat HTTP 404 as unauthorized.

Body reconstruction: Parse the existing issue body by splitting on ## headers to extract each section's content. Rebuild the body in skill-level template format:

1. Skill-level intro block (e.g., "🧠 Advanced" textarea boilerplate)
2. [!IMPORTANT] about-this-level callout block
3. User's sections (description, solution, implementation steps, acceptance criteria) — preserved as-is
4. Standard contribution guide boilerplate
5. Additional information (preserved from submitted body, or default boilerplate if empty)

Dispatcher update

• .github/scripts/bot-on-comment.js — add /finalize regex and dispatch to handleFinalize
• .github/scripts/helpers/constants.js — add AWAITING_TRIAGE: 'status: awaiting triage'

Docs

• docs/contributing/issue-types.md — contributor guide: what is a Bug vs Feature vs Task, with examples of each
• docs/maintainers/guidelines-triage.md — maintainer triage workflow: when to triage, which labels to apply, how to use /finalize

Tests

• .github/scripts/tests/test-finalize-bot.js — follow the same pattern as test-assign-bot.js

Key test cases: unauthorized user, missing/extra skill labels, missing priority, wrong kind for issue type, missing status: awaiting triage, multiple violations reported in one comment, successful finalize for each skill level (title + body + labels updated), API error handling.

---

✅ Acceptance Criteria

• The five skill-level issue templates are removed; three new type-based templates (Bug, Feature, Task) replace them, each auto-applying status: awaiting triage
• Each new template is as comprehensive as the current skill templates, with examples and an Acceptance Criteria section
• /finalize is implemented and dispatched from bot-on-comment.js
• /finalize enforces all label rules and posts a descriptive comment listing all violations when any are found
• /finalize is restricted to contributors with triage-or-above repository permissions
• /finalize updates the issue title with the correct skill-level prefix
• /finalize reformats the issue body into the skill-level template format, preserving the submitter's content and appending contribution guide / additional info boilerplate
• /finalize swaps status: awaiting triage → status: ready for dev
• AWAITING_TRIAGE is added to constants.js
• docs/contributing/issue-types.md is created with comprehensive descriptions of Bug, Feature, and Task
• docs/maintainers/guidelines-triage.md is created and documents the full triage workflow
• test-finalize-bot.js covers all key cases and passes
• All existing bot tests continue to pass

---

📚 Additional Context, Links, or Prior Art

This issue tracks a deliberate structural improvement to the contribution workflow for the Hiero C++ SDK. The design draws on the existing /assign and /unassign bot infrastructure (.github/scripts/commands/) and follows the same patterns established there.

Related files for context:

• .github/scripts/commands/assign.js — reference implementation for a bot command
• .github/scripts/commands/assign-comments.js — reference for comment builder pattern
• .github/scripts/tests/test-assign-bot.js — reference for test structure
• docs/maintainers/guidelines-difficulty-overview.md — skill level documentation that /finalize boilerplate should draw from