Issue Refinement Workflow

Purpose: Transform unclear or incomplete issues into well-defined, ready-to-work tasks with proper scope, labels, and estimates.

Audience: Refiners responsible for refining issues before implementation.

Rationale

Issues often start with incomplete information or unclear requirements. The refinement process ensures that:

All necessary context and technical details are present
Time estimates are accurate
Labels and metadata are correctly assigned
Issues are actionable and ready for development

This reduces ambiguity, prevents rework, and helps contributors understand what needs to be done.

Quick Reference

Issue Selection Priority:

Issues suggested by Project Manager (status: refine)
Issues in current iteration that lack clarity
Version upgrade issues
Cleanup tasks
Very old issues

Refinement Checklist:

✅ Issue description is complete and clear
✅ Labels include status::ready
✅ Time estimation is set
✅ Blocking issues are linked (if any)
✅ Acceptance criteria are defined

Workflow Steps

Who: Project Manager or Product Manager When: When new issues are created or issues need refinement in iteration planning Actions:

During issue review for iteration planning it becomes clear that issue needs refinement
Add status::refine label to issues that should be refined

Result: Issues tagged with status::refine are ready for refiners to pick up

2. Select Issue to Refine

Who: Refiner When: During designated refinement time Actions:

Check refinement board for issues with status::refine and the label 1.0::must_have
Select issues based on priority order (see Quick Reference)
If unclear issues are in current iteration and cannot be refined in time, inform Project Manager in the issue

Result: Issue selected for refinement

Who: Issue Refiner When: After selecting issue Actions:

Open new browser window to access issue templates
Copy the existing issue description
Open the Issue Creation Assistant tool (./tools/pm/issue_creation_assistant.md)
Copy the appropriate GitLab issue template

Result: Ready to use AI assistant for refinement

4. Refine Issue with AI Assistant

Who: Refiner with AI Assistant When: During refinement process Actions:

Provide issue description and template to AI assistant (Claude works well)
Answer clarifying questions asked by the assistant
Review generated issue description
Verify technical accuracy and completeness

Result: AI-generated refined issue description ready for review

5. Update Issue in GitLab

Who: Refiner When: After AI refinement complete Actions:

Copy refined issue description to GitLab issue
Proofread and correct any mistakes
Check if correct scope is set
Verify labels are correct (ensure status::ready is added)
Confirm time estimation is set
Link any blocking issues if applicable

Result: Issue updated with refined description (old version visible via "Compare with previous version")

6. Update Iteration Planning Issue

Who: Refiner When: After updating issue Actions:

Add the refined issue to the list of refined issues in the iteration planning issue

Result: Iteration planning issue contains comprehensive list of all refined issues

Special Cases

Unclear Issues in Current Iteration

If an issue in the current iteration creates any questions for refining:

Inform Project Manager in the issue, providing:

what information is missing in an issue comment
what is unclear
options how it could be solved
if there are any issues with (partly) overlap
if existing documentation (use cases etc.) say something about it

When enough information is collected continue with refinement.

Examples

Step 1: Refiner selects issue #123 with status::refine from refinement board
Step 2: Refiner opens Issue Creation Assistant and gathers issue template
Step 3: AI assistant asks clarifying questions about scope and environment
Step 4: Refiner reviews and copies refined description to GitLab
Step 5: Refiner adds status::ready and scope::backend label, sets 8h estimate, notifies Project Manager
Result: Issue #123 is ready for development with clear requirements

Example 2: Current Iteration Issue Needs Clarification

Step 1: Refiner reviews issue #456 in current iteration
Step 2: Issue lacks critical information about database schema changes
Step 3: Refiner informs Product Manager in issue comment:
        - Missing: which tables are affected
        - Options: modify existing schema OR create new tables
        - Existing use cases mention table "plants" but unclear if other tables needed
Step 4: Product Manager provides schema details in comment
Step 5: Refiner continues with refinement using new information and marks ready
Result: Issue clarified and refined for immediate work

Issue Creation Assistant Tool (./tools/pm/issue_creation_assistant.md)
GitLab Issue Templates (.gitlab/issue_templates/)
Labels documentation

Troubleshooting

Common Issues

Problem: Issue template doesn't match the issue type Solution: Select the correct template from GitLab's issue templates directory before using AI assistant

Problem: AI assistant generates technically incorrect information Solution: Thoroughly proofread and correct the generated description - you are the pilot, AI is the co-pilot

Problem: Unable to determine appropriate time estimate Solution: Consult with more experienced team members or break issue into smaller, estimable subtasks

PermaplanT