Issue Refinement Guidelines

Best practices for transforming unclear issues into well-defined, ready-to-work tasks.

Self-Contained Issue Descriptions

Keep all essential information in the issue description, not scattered in comments.

Why this matters:
- Anyone picking up the issue has everything they need immediately
- No need to read through lengthy comment threads
- Reduces time to understand the task
- Prevents missed information buried in comments
- Developers can prepare themselves better for what needs to be done
How to achieve this:
- Update the issue description directly during refinement
- Consolidate insights from comments into the description
- Use "Compare with previous version" to track what changed
- Preserve the original context while adding clarity

Completeness Standards

An issue is complete when it includes:

All necessary context
- Background information
- Related issues or dependencies
- Links to relevant documentation or designs
Clear technical details
- Specific requirements and constraints
- Technical approach or implementation hints (if known)
- Environment or configuration details (if applicable)
Actionable acceptance criteria
- Specific, measurable outcomes
- Test scenarios or success conditions
- Clear definition of "done"
Proper metadata
- Correct type and scope labels
- Time estimation
- Blocking issues linked (if any)

Best Practices

You are the pilot, AI is the co-pilot
- AI assists with structure and completeness
- You provide domain knowledge and technical accuracy
- Always proofread and correct AI-generated content
Use AI for:
- Structuring issue descriptions consistently
- Identifying missing information
- Generating comprehensive acceptance criteria
- Improving clarity and readability
Don't rely on AI for:
- Technical accuracy without verification
- Architectural decisions
- Understanding project-specific context
- Making refinement decisions

Verification Requirements

After AI-assisted refinement:

Proofread thoroughly
- Check for technical inaccuracies
- Verify all details are correct
- Ensure terminology is consistent with project glossary
Validate completeness
- All template sections filled appropriately
- No placeholder text remains
- All questions answered
Check technical accuracy
- Implementation approach is feasible
- Dependencies are correctly identified
- Estimates are reasonable

When to Add `status::ready`

Only add status::ready when:

Issue is complete without critical uncertainties
- All information needed for implementation is present
- No ambiguous requirements remain
- Technical approach is clear
You are confident in the refinement
- No significant questions or assumptions
- All edge cases considered
- Scope is well-defined

When to Wait for PM Review

Do NOT add status::ready if:

Uncertainties exist that need PM review
- Multiple valid interpretations possible
- Product decisions required
- Scope or priority unclear
Significant assumptions were made
- You made important interpretation decisions
- Technical approach needs validation
- Impact on other features unclear

Use clear headers in your refinement comment:

"✅ Refinement Complete - No Action Needed"

Everything was clear
Refinement went smoothly
No uncertainties or questions
Ready for implementation

"⚠️ Refinement Complete - Review Required"

Uncertainties exist
PM review and confirmation needed
Multiple interpretation options documented
Assumptions that need validation

Refinement Summary

What to Include

Your refinement comment should include:

Changes summary
- What was changed during refinement
- What details were added
- How structure was improved
Additions
- New acceptance criteria
- Additional technical details
- Linked dependencies
- Time estimation rationale
Assumptions and interpretations
- Any decisions you made
- Reasoning behind interpretations
- Areas where you made judgment calls
Questions and uncertainties (if any)
- Highlight areas where you weren't 100% sure
- Present alternative interpretations
- Identify decisions that need PM input
- Flag potential impacts or risks

Tagging

Always tag at the end of your comment:

@author - Original issue creator
@product_manager - For product decisions and validation

Handling Current Iteration Issues

Special Attention Required

If an issue in the current iteration creates questions:

Inform Project Manager immediately
Provide comprehensive context:
- What information is missing
- What is unclear
- Options for how it could be solved
- Whether there are overlapping issues
- What existing documentation says about it
Do not add status::ready
- Wait for PM reply with clarifications
- Continue refinement after information is collected

Time Sensitivity

Current iteration issues need faster turnaround
Prioritize these over backlog refinement
Communicate blockers or delays immediately
Escalate if information can't be obtained quickly

Template Alignment

Ensure the correct template is used for the issue type
Fill all template sections appropriately
Remove unused template sections
Maintain consistent structure

Label Verification

Check type label is correct
Verify scope label(s) are accurate
Ensure no incorrect labels remain
Add missing process labels if needed

Time Estimation

Provide realistic time estimates
Consider complexity and unknowns
Account for testing and review time
Consult experienced team members if uncertain
Break into subtasks if too large to estimate

Linking and Dependencies

Identify and link blocking issues
Reference related issues
Link to relevant documentation
Note any cross-team dependencies

Quality Checklist

Before completing refinement:

Issue description is self-contained and complete
All template sections are filled appropriately
Type and scope labels are correct
Time estimation is set and reasonable
Acceptance criteria are clear and measurable
Dependencies and blockers are identified
Technical details are accurate
No ambiguous requirements remain
Appropriate status::ready or need for PM review determined
Refinement comment written with clear status and summary
Author and Product Manager tagged

PermaplanT