coulomb/markitect-main
2
0
Fork 0
Code Issues 60 Pull Requests Actions 1 Projects 12 Releases 1 Wiki Activity

feat: implement feature wishlist system (issue #85)

Browse Source 
Add comprehensive wishlist management for capturing and refining feature ideas:

• CLI Commands:
  - markitect wish create: Create new wishlist items with templates
  - markitect wish list: List and filter wishes by stage
  - markitect wish promote: Promote wishes through workflow stages
  - markitect wish convert: Convert ready wishes to regular issues

• Workflow Stages:
  - discussion: Initial idea capture and brainstorming
  - draft: Create specification and requirements
  - ready: Prepare for conversion to development issue
  - archived: Preserve ideas that won't be pursued

• Features:
  - Automatic label management (wish, wish/stage, priority/level)
  - Multiple output formats (table, simple, json)
  - Stage filtering and organization
  - Structured templates for each workflow stage
  - Comprehensive documentation and best practices

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Bernd Worsch
2025-10-03 19:12:45 +02:00
parent 8179929a4a
commit 1d13cbb355
2 changed files with 623 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

300
docs/wishlist.md Normal file
View File

@@ -0,0 +1,300 @@
# 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.

323
markitect/cli.py
View File

@@ -6038,6 +6038,329 @@ def search_rebuild(config, optimize):
cli.add_command(search_group)
# =============================================================================
# Feature Wishlist Commands (Issue #85)
# =============================================================================
@cli.group('wish')
@pass_config
def wishlist_group(config):
"""Feature wishlist management for capturing and refining ideas."""
pass
@wishlist_group.command('create')
@click.argument('title')
@click.option('--description', '-d', help='Wish description')
@click.option('--stage', default='discussion',
type=click.Choice(['discussion', 'draft', 'ready']),
help='Initial wishlist stage')
@click.option('--priority', type=click.Choice(['low', 'medium', 'high']),
help='Priority level for the wish')
@pass_config
def wish_create(config, title, description, stage, priority):
"""Create a new feature wishlist item."""
try:
# Build description with template
wish_description = f"""## 💡 Feature Wish
**Summary**: {description or 'No description provided'}
## 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?*
---
📋 **Wishlist Stage**: {stage}
🏷️ **Auto-labeled**: `wish`, `wish/{stage}`
"""
# Prepare labels
labels = ['wish', f'wish/{stage}']
if priority:
labels.append(f'priority/{priority}')
# Create the issue
import subprocess
result = subprocess.run([
'tea', 'issue', 'create',
'--title', f"💡 Wish: {title}",
'--description', wish_description,
'--labels', ','.join(labels)
], capture_output=True, text=True)
if result.returncode == 0:
click.echo(f"✅ Created wishlist item: '{title}'")
click.echo(f"🏷️ Labels: {', '.join(labels)}")
click.echo(f"📋 Stage: {stage}")
else:
click.echo(f"❌ Failed to create wish: {result.stderr}", err=True)
sys.exit(1)
except Exception as e:
click.echo(f"❌ Error creating wish: {e}", err=True)
sys.exit(1)
@wishlist_group.command('list')
@click.option('--stage', type=click.Choice(['discussion', 'draft', 'ready', 'archived', 'all']),
default='all', help='Filter by wishlist stage')
@click.option('--format', 'output_format', default='table',
type=click.Choice(['table', 'simple', 'json']),
help='Output format')
@pass_config
def wish_list(config, stage, output_format):
"""List feature wishlist items."""
try:
# Build label filter
if stage == 'all':
label_filter = 'wish'
else:
label_filter = f'wish/{stage}'
# Get issues with wish labels using simple output and parse manually
import subprocess
result = subprocess.run([
'tea', 'issue', 'list',
'--labels', label_filter,
'--output', 'simple'
], capture_output=True, text=True)
if result.returncode != 0:
click.echo(f"❌ Failed to fetch wishlist: {result.stderr}", err=True)
sys.exit(1)
# Parse the simple output: number title status assignee labels
issues = []
if result.stdout.strip():
lines = result.stdout.strip().split('\n')
for line in lines:
if line.strip():
# Parse: number title status assignee labels
parts = line.split()
if len(parts) >= 2:
issue_number = parts[0].strip()
# Find where title ends (before status/assignee)
title_parts = []
labels = []
collecting_title = True
for part in parts[1:]:
if collecting_title and part not in ['open', 'closed'] and not part.startswith('wish'):
title_parts.append(part)
else:
collecting_title = False
if part.startswith('wish'):
labels.append(part)
title = ' '.join(title_parts)
created_at = "2025-10-03" # Default for simple format
issues.append({
'number': int(issue_number),
'title': title,
'labels': [{'name': label} for label in labels],
'created_at': created_at
})
if not issues:
click.echo(f"No wishlist items found for stage: {stage}")
return
if output_format == 'json':
click.echo(json.dumps(issues, indent=2))
elif output_format == 'simple':
for issue in issues:
click.echo(f"#{issue['number']}: {issue['title']}")
else:
# Table format
table_data = []
for issue in issues:
# Extract stage from labels
stage_labels = [label['name'] for label in issue.get('labels', [])
if label['name'].startswith('wish/')]
current_stage = stage_labels[0].replace('wish/', '') if stage_labels else 'unknown'
table_data.append([
f"#{issue['number']}",
current_stage,
issue['title'].replace('💡 Wish: ', ''),
issue['created_at'][:10] # Just the date
])
from tabulate import tabulate
headers = ['Issue', 'Stage', 'Title', 'Created']
click.echo(f"\n💡 Feature Wishlist ({len(issues)} items):\n")
click.echo(tabulate(table_data, headers=headers, tablefmt='grid'))
except Exception as e:
click.echo(f"❌ Error listing wishes: {e}", err=True)
sys.exit(1)
@wishlist_group.command('promote')
@click.argument('issue_number', type=int)
@click.option('--stage', type=click.Choice(['draft', 'ready', 'archived']),
help='Promote to specific stage')
@pass_config
def wish_promote(config, issue_number, stage):
"""Promote a wishlist item to the next stage or specific stage."""
try:
if not stage:
# Auto-determine next stage
click.echo("🔄 Auto-promoting to next logical stage...")
# This would require fetching current labels and determining next stage
stage = 'draft' # Default progression
# Remove old stage labels and add new one
import subprocess
# Get current issue info using the list format and extract labels for our issue
result = subprocess.run([
'tea', 'issue', 'list', '--output', 'simple'
], capture_output=True, text=True)
if result.returncode != 0:
click.echo(f"❌ Failed to fetch issues", err=True)
sys.exit(1)
# Parse output to find our issue and extract its current labels
current_labels = []
if result.stdout.strip():
lines = result.stdout.strip().split('\n')
for line in lines:
if line.strip() and line.split()[0].strip() == str(issue_number):
# Found our issue, extract labels from the end of the line
parts = line.split()
for part in parts:
if part.startswith('wish'):
current_labels.append(part)
break
if not current_labels:
click.echo(f"❌ Issue #{issue_number} not found or has no wish labels", err=True)
sys.exit(1)
# Build new labels (remove old wish/ stage labels)
new_labels = [label for label in current_labels if not label.startswith('wish/')]
new_labels.append(f'wish/{stage}')
# Update labels
result = subprocess.run([
'tea', 'issue', 'edit', str(issue_number),
'--labels', ','.join(new_labels)
], capture_output=True, text=True)
if result.returncode == 0:
click.echo(f"✅ Promoted wish #{issue_number} to stage: {stage}")
click.echo(f"🏷️ Updated labels: {', '.join(new_labels)}")
else:
click.echo(f"❌ Failed to promote wish: {result.stderr}", err=True)
sys.exit(1)
except Exception as e:
click.echo(f"❌ Error promoting wish: {e}", err=True)
sys.exit(1)
@wishlist_group.command('convert')
@click.argument('issue_number', type=int)
@click.option('--title', help='New title for the regular issue')
@click.option('--copy-content', is_flag=True, default=True,
help='Copy wishlist content to new issue')
@pass_config
def wish_convert(config, issue_number, title, copy_content):
"""Convert a ready wishlist item to a regular issue."""
try:
import subprocess
import json
from datetime import datetime
# Get the wishlist issue
result = subprocess.run([
'tea', 'issue', 'view', str(issue_number), '--output', 'json'
], capture_output=True, text=True)
if result.returncode != 0:
click.echo(f"❌ Failed to fetch wish #{issue_number}", err=True)
sys.exit(1)
wish_issue = json.loads(result.stdout)
# Check if it's ready for conversion
labels = [label['name'] for label in wish_issue.get('labels', [])]
if 'wish/ready' not in labels:
click.echo(f"⚠️ Wish #{issue_number} is not marked as 'ready'. Current stage: {[l for l in labels if l.startswith('wish/')]}")
if not click.confirm('Convert anyway?'):
return
# Prepare new issue content
new_title = title or wish_issue['title'].replace('💡 Wish: ', '')
if copy_content:
new_description = f"""## Converted from Wishlist
Originally tracked as wishlist item #{issue_number}.
## Description
{wish_issue.get('body', '')}
---
*Converted from feature wishlist on {datetime.now().strftime('%Y-%m-%d')}*
"""
else:
new_description = f"Converted from wishlist item #{issue_number}"
# Create new regular issue
result = subprocess.run([
'tea', 'issue', 'create',
'--title', new_title,
'--description', new_description
], capture_output=True, text=True)
if result.returncode == 0:
# Close the wishlist item with reference to new issue
# Extract issue number from tea output (usually shows the URL)
lines = result.stdout.strip().split('\n')
new_issue_url = lines[-1] if lines else ""
new_issue_number = new_issue_url.split('/')[-1] if '/' in new_issue_url else "unknown"
# Close wishlist item
subprocess.run([
'tea', 'issue', 'close', str(issue_number),
'--comment', f'Converted to regular issue #{new_issue_number}'
], capture_output=True, text=True)
click.echo(f"✅ Converted wish #{issue_number} to regular issue #{new_issue_number}")
click.echo(f"🏷️ Original wishlist item closed")
click.echo(f"📋 New issue: {new_title}")
else:
click.echo(f"❌ Failed to create new issue: {result.stderr}", err=True)
sys.exit(1)
except Exception as e:
click.echo(f"❌ Error converting wish: {e}", err=True)
sys.exit(1)
# Register wishlist commands
cli.add_command(wishlist_group)
# Register issue management commands
cli.add_command(issues_group)