markitect-main/docs/wishlist.md

Feature Wishlist System - Issue #85

The Feature Wishlist system provides a structured approach for capturing, discussing, and refining feature ideas before they become formal development tasks.

Overview

The wishlist system helps teams:

• Capture Ideas: Preserve creative insights that emerge during discussions
• Organize Thoughts: Structure rough ideas before formal specification
• Facilitate Discussion: Provide dedicated space for collaborative refinement
• Prevent Loss: Ensure good ideas aren't forgotten
• Gradual Refinement: Allow concepts to mature over time

Workflow Stages

1. 💡 Discussion Stage (wish/discussion)

• Purpose: Initial idea capture and brainstorming
• Activities: Gather thoughts, explore possibilities, ask questions
• Output: Refined understanding of the concept

2. 📝 Draft Stage (wish/draft)

• Purpose: Create initial specification and requirements
• Activities: Document detailed requirements, identify dependencies
• Output: Draft implementation plan

3. ✅ Ready Stage (wish/ready)

• Purpose: Prepare for conversion to regular development issue
• Activities: Final review, priority assignment, resource planning
• Output: Well-formed issue ready for development

4. 🗄️ Archived Stage (wish/archived)

• Purpose: Preserve ideas that won't be pursued currently
• Activities: Document decision rationale, mark for future consideration
• Output: Archived record with context

CLI Commands

Create a Wishlist Item

# Basic wish creation
markitect wish create "Smart document templates"

# With description and priority
markitect wish create "Real-time collaboration" \
  --description "Enable multiple users to edit documents simultaneously" \
  --priority high \
  --stage discussion

List Wishlist Items

# List all wishlist items
markitect wish list

# Filter by stage
markitect wish list --stage discussion
markitect wish list --stage ready

# Different output formats
markitect wish list --format json
markitect wish list --format simple

Promote Wishlist Items

# Promote to next logical stage
markitect wish promote 86

# Promote to specific stage
markitect wish promote 86 --stage ready

Convert to Regular Issue

# Convert ready wish to regular issue
markitect wish convert 86

# Convert with custom title
markitect wish convert 86 --title "Implement smart document templates"

Labels and Organization

Core Labels

• wish - Primary wishlist identifier
• wish/discussion - Currently being discussed
• wish/draft - Has initial specification draft
• wish/ready - Ready for development
• wish/archived - Archived or rejected

Additional Labels

• priority/low|medium|high - Priority levels
• effort/small|medium|large - Estimated effort
• category/ui|api|infrastructure - Feature categories

Issue Templates

Discussion Stage Template

## 💡 Feature Wish

**Summary**: [Brief description of the idea]

## Current Thinking

*What's the initial idea or inspiration?*

## Potential Benefits

*Why might this be valuable?*

## Questions to Explore

*What aspects need more thought?*

## Related Concepts

*Are there similar ideas or existing features this relates to?*

Draft Stage Template

## 📝 Feature Specification Draft

**Summary**: [Refined description]

## Requirements

### Functional Requirements
- [ ] Requirement 1
- [ ] Requirement 2

### Non-Functional Requirements
- [ ] Performance expectations
- [ ] Compatibility requirements

## Implementation Approach

*High-level approach and key considerations*

## Dependencies

*What other features or changes are needed?*

## Success Criteria

*How will we know this feature is successful?*

Best Practices

Creating Good Wishes

1. Start Small: Begin with simple, focused ideas
2. Be Specific: Include concrete examples when possible
3. Ask Questions: Identify what needs exploration
4. Link Related: Connect to existing features or issues

Discussion Guidelines

1. Stay Open: All ideas deserve consideration
2. Ask Clarifying Questions: Help refine the concept
3. Share Examples: Provide concrete use cases
4. Consider Alternatives: Explore different approaches

Promotion Criteria

Discussion → Draft

• Clear understanding of the problem
• Identified potential solutions
• Community interest confirmed

Draft → Ready

• Detailed requirements documented
• Implementation approach defined
• Dependencies identified
• Success criteria established

Ready → Regular Issue

• Complete specification
• Priority and effort estimated
• Development resources available

Examples

Example 1: Simple Wish Creation

markitect wish create "Export to PDF" \
  --description "Allow users to export markdown documents to PDF format" \
  --stage discussion

Example 2: Full Workflow

# 1. Create initial wish
markitect wish create "Smart document templates"

# 2. List and review wishes
markitect wish list --stage discussion

# 3. Promote after discussion
markitect wish promote 86 --stage draft

# 4. Add detailed specification (manual editing)

# 5. Promote when ready
markitect wish promote 86 --stage ready

# 6. Convert to development issue
markitect wish convert 86

Example 3: Wish Filtering

# Show only high-priority ready items
markitect wish list --stage ready | grep "priority/high"

# Export all wishes for analysis
markitect wish list --format json > wishlist-export.json

Integration with Development Process

Connecting to Regular Issues

• Converted wishes automatically reference original wishlist item
• Original wish is closed with link to new issue
• Maintains traceability from idea to implementation

Project Planning

• Use wish/ready items for sprint planning
• Filter by priority and effort for roadmap planning
• Track conversion rate from wishes to implemented features

Community Engagement

• Encourage team members to create wishes freely
• Use wishlist for user feedback and feature requests
• Regular review meetings to promote wishes through stages

Reporting and Analytics

Useful Queries

# Count wishes by stage
markitect wish list --format json | jq 'group_by(.labels[].name | select(startswith("wish/"))) | map({stage: .[0].labels[].name, count: length})'

# Find oldest wishes needing attention
markitect wish list --stage discussion --format json | jq 'sort_by(.created_at) | .[0:5]'

# Track conversion success rate
# (Count of converted wishes vs total wishes created)

Metrics to Track

• Creation Rate: How many wishes are being created
• Promotion Rate: How quickly wishes move through stages
• Conversion Rate: Percentage of wishes that become regular issues
• Stage Distribution: Where wishes tend to accumulate

Troubleshooting

Common Issues

"No wishlist items found"

• Check if labels were created properly: tea label list | grep wish
• Verify issue has correct labels

"Failed to promote wish"

• Ensure issue exists and you have permissions
• Check if labels are properly configured

Convert command fails

• Verify wish is in ready stage
• Check issue permissions and repository access

Recovery Commands

# Manually add wish labels to existing issue
tea issue edit 86 --labels "wish,wish/discussion"

# Fix missing stage labels
tea issue edit 86 --labels "wish,wish/draft,priority/medium"

Maintenance

Regular Tasks

1. Weekly Review: Check wishes in discussion stage
2. Monthly Promotion: Move mature wishes to next stage
3. Quarterly Cleanup: Archive stale or obsolete wishes
4. Annual Analysis: Review wishlist effectiveness and process improvements

Automated Maintenance (Future)

• Auto-archive wishes inactive for 6+ months
• Remind assignees of wishes ready for promotion
• Generate wishlist health reports

The Feature Wishlist system transforms ad-hoc idea management into a structured, trackable process that ensures valuable insights are captured, refined, and eventually implemented.