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.

Status: Draft

Rationale

Issues go through triage first (see Triage workflow). Some issues are clear enough after triage to go directly to the backlog as status::ready. Others need refinement when they have incomplete information or unclear requirements.

The refinement process ensures that:

  • All necessary context and technical details are present
  • Time estimates are plausible
  • Labels and metadata are correctly assigned
  • Issues are actionable and ready for development
  • Issues are self-contained and solvable from the issue description alone

This reduces ambiguity, prevents rework, and helps contributors understand what needs to be done. By keeping all essential information in the issue description rather than scattered in comments, we ensure that anyone picking up the issue has everything they need to solve it without having to read through lengthy comment threads. Furthermore, it allows developers to prepare themselves better for what is to be done in less time.

Quick Reference

Issue Selection Priority:

  1. Issues tagged during triage or by Project Manager (status::refine)
  2. Issues in current iteration that lack clarity
  3. Version upgrade issues
  4. Cleanup tasks
  5. 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

1. Tag Issues for Refinement

Who: Triager, Project Manager, or Product Manager

When: During triage OR during iteration planning when issues need more detail/clarity

Actions:

  • During triage: If issue has incomplete information or unclear requirements, add status::refine label
  • During iteration planning: If issue review reveals missing details or lack of clarity, add status::refine label
  • Issues that are clear enough after triage can go directly to backlog without refinement

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

2. Assign Refinement Work

Who: Refiner

When: At the beginning of each iteration (Friday)

Actions:

  • Go to the refinement boards (PermaplanT and infrastructure repository)
  • Review all issues with status::refine label
  • Assign issues individually to Refiner Helpers and Refiner
  • Distribute workload evenly across the team

Result: Each issue with status::refine has an assignee responsible for refining it

3. Select Issue to Refine

Who: Refiner or Refiner Helper

When: During designated refinement time

Actions:

  • Check refinement board (PermaplanT and infrastructure repository) for issues assigned to you with status::refine label
  • Prioritize issues with 1.0::must_have label
  • 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

4. Prepare for AI-Assisted Refinement

Who: Refiner or Refiner Helper

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

5. Refine Issue with AI Assistant

Who: Refiner or Refiner Helper 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

6. Update Issue in GitLab

Who: Refiner or Refiner Helper

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
  • Add status::ready ONLY if refinement is complete without critical uncertainties
    • If uncertainties exist that need PM review: do NOT add status::ready, wait for PM confirmation
  • 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")

7. Notify Product Manager

Who: Refiner or Refiner Helper

When: After updating issue

Actions:

  • Write a comment in the refined issue tagging the Product Manager
  • Use one of these headers to indicate the refinement status:
    • "✅ Refinement Complete - No Action Needed": Everything was clear, refinement went smoothly
    • "⚠️ Refinement Complete - Review Required": Uncertainties exist, immediate PM review needed
  • Provide a short summary including:
    • What was changed during refinement
    • What was added (details, acceptance criteria, etc.)
    • Any assumptions or interpretations made
    • Especially: Highlight any areas where you were not 100% sure of the correct interpretation

Result: Product Manager is notified about the refinement with clear summary of changes and any uncertainties

Special Cases

Unclear Issues in Current Iteration

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

  1. 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
  • don't set status::ready but wait for reply
  1. When enough information is collected continue with refinement.

Examples

Example 1: Standard Issue Refinement

Step 1: Project Manager tags issue #123 with status::refine during iteration planning
Step 2: Refiner assigns issue #123 to Refiner Helper at beginning of iteration (Friday)
Step 3: Refiner Helper selects issue #123 from their assigned issues on refinement board
Step 4: Refiner Helper opens Issue Creation Assistant and gathers issue template
Step 5: AI assistant asks clarifying questions about scope and environment
Step 6: Refiner Helper reviews and copies refined description to GitLab
Step 7: Refiner Helper adds status::ready and scope::backend label, sets 8h estimate, notifies Product Manager with "✅ Refinement Complete - No Action Needed" comment
Result: Issue #123 is ready for development with clear requirements

Example 2: Current Iteration Issue Needs Clarification

Step 1: Triager tags issue #456 with status::refine during triage
Step 2: Refiner assigns issue #456 to Refiner Helper at beginning of iteration (Friday)
Step 3: Refiner Helper reviews issue #456 but lacks critical information about database schema changes
Step 4: Refiner Helper 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 5: Product Manager provides schema details in comment
Step 6: Refiner Helper continues with refinement using new information and marks ready
Step 7: Refiner Helper notifies Product Manager with "✅ Refinement Complete - No Action Needed" comment
Result: Issue clarified and refined for immediate work

Example 3: Refinement with Uncertainties

Step 1: Triager tags issue #789 with status::refine during triage
Step 2: Refiner assigns issue #789 to Refiner at beginning of iteration (Friday)
Step 3: Refiner selects issue #789 from their assigned issues on refinement board
Step 4: Refiner uses Issue Creation Assistant to refine the issue
Step 5: AI assistant helps structure the issue, but Refiner identifies ambiguity in user interaction flow
Step 6: Refiner completes refinement with two possible interpretation options documented
Step 7: Refiner sets 12h estimate, does NOT add status::ready, notifies Product Manager with "⚠️ Refinement Complete - Review Required" comment highlighting:
        - Assumption: User can edit settings from both profile page AND settings menu
        - Uncertainty: Whether these should be kept in sync or independent
        - Needs PM decision before implementation starts
Step 8: Product Manager reviews and confirms interpretation, adds status::ready
Result: Issue refined and verified, ready for implementation after PM clarification
  • 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

Open Points

Notes