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

```bash
# 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

```bash
# 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

```bash
# Promote to next logical stage
markitect wish promote 86

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

### Convert to Regular Issue

```bash
# 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
```markdown
## 💡 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
```markdown
## 📝 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
```bash
markitect wish create "Export to PDF" \
  --description "Allow users to export markdown documents to PDF format" \
  --stage discussion
```

### Example 2: Full Workflow
```bash
# 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
```bash
# 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
```bash
# 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

```bash
# 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.