dance-lessons-coach/.vibe/skills/product-owner-assistant/README.md

# Product Owner Assistant Skill

A comprehensive skill for managing Gitea issues as Epics and User Stories, designed to help product owners organize and track large bodies of work.

## 🎯 Purpose

The Product Owner Assistant skill enables effective agile product management by:

- **Organizing Issues**: Group related issues into epics and user stories
- **Tracking Progress**: Monitor epic completion and story status
- **Facilitating Refinement**: Prepare structured backlog refinement sessions
- **Enhancing Communication**: Generate progress reports for stakeholders
- **Documenting Work**: Create wiki pages for epics and stories

## 🚀 Quick Start

### Prerequisites

1. **Gitea API Access**: Configured Gitea API token
2. **gitea-client Skill**: Must be installed and configured
3. **jq**: For JSON processing (usually pre-installed)

### Basic Usage

```bash
# Create an epic
skill product-owner-assistant create-epic arcodange dance-lessons-coach \
  "User Authentication System" \
  "Implement comprehensive authentication with OAuth and JWT" \
  "epic,authentication,security"

# Create user stories under the epic
skill product-owner-assistant create-story arcodange dance-lessons-coach 42 \
  "OAuth Integration" \
  "As a user, I want to login with Google/GitHub..." \
  "story,authentication"

# Show epic progress
skill product-owner-assistant epic-progress arcodange dance-lessons-coach 42
```

## 📋 Features

### ✅ Epic Management
- Create epics as parent issues with special labeling
- Track epic state and progress
- List and filter epics by state

### 📝 User Story Organization
- Create user stories linked to epics
- Link existing issues to epics
- Maintain epic-story relationships

### 📊 Progress Tracking
- Visualize epic completion status
- Count stories by state (open, in progress, completed)
- Generate comprehensive progress reports

### 📚 Documentation
- Create wiki pages for epics
- Generate backlog refinement documents
- Prepare sprint planning materials

### 🔄 Integration
- Works with existing Gitea issues
- Compatible with gitea-client skill
- Uses standard Gitea API

## 🎯 Use Cases

### 1. Feature Development
```bash
# Create feature epic
skill product-owner-assistant create-epic team repo \
  "Advanced Search Functionality" \
  "Implement comprehensive search with filters and saved searches"

# Break down into stories
skill product-owner-assistant create-story team repo 42 \
  "Basic Search Implementation" \
  "As a user, I want to search by keyword..."

skill product-owner-assistant create-story team repo 42 \
  "Advanced Filters" \
  "As a user, I want to filter by date, type, author..."
```

### 2. Backlog Refinement
```bash
# Generate refinement document
skill product-owner-assistant refine-backlog team repo \
  backlog-refinement-$(date +%Y-%m-%d).md

# Review and update epics
skill product-owner-assistant list-epics team repo

# Check progress of key epics
skill product-owner-assistant epic-progress team repo 42
skill product-owner-assistant epic-progress team repo 43
```

### 3. Stakeholder Communication
```bash
# Generate weekly progress report
skill product-owner-assistant progress-report team repo \
  weekly-progress-$(date +%Y-%m-%d).md

# Create wiki documentation for key epics
skill product-owner-assistant create-wiki-epic team repo 42
skill product-owner-assistant create-wiki-epic team repo 43
```

## 📁 Structure

```
.vibe/skills/product-owner-assistant/
├── SKILL.md              # Main skill documentation
├── README.md             # This file
├── SUMMARY.md            # Implementation summary
├── scripts/
│   ├── product-owner-assistant.sh  # Main implementation
│   └── test-wiki.sh      # Wiki functionality tester
├── references/
│   ├── agile-epics.md    # Epic management guide
│   ├── user-stories.md    # User story writing guide (placeholder)
│   ├── backlog-refinement.md  # Refinement techniques (placeholder)
│   └── wiki-formatting.md # Wiki documentation guide
├── data/                 # Local data storage (created automatically)
└── assets/               # Templates and resources
```

## 🔧 Configuration

### Environment Variables

```bash
# Gitea API authentication (required)
export GITEA_API_TOKEN="your_token"
# or
export GITEA_API_TOKEN_FILE="/path/to/token"
```

### Default Labels

Customize in the script:

```bash
EPIC_LABELS="epic,backlog"      # Default epic labels
STORY_LABELS="story,backlog"    # Default story labels
```

## 📚 Documentation

### Guides
- [Agile Epic Management](references/agile-epics.md)
- [User Story Writing](references/user-stories.md)
- [Backlog Refinement](references/backlog-refinement.md)
- [Wiki Formatting](references/wiki-formatting.md)

### Examples
See the [SKILL.md](SKILL.md) file for comprehensive usage examples and workflows.

## 🤝 Integration

### With gitea-client Skill
The product-owner-assistant builds on the gitea-client skill:

```bash
# All gitea-client commands are available
gitea-client list-issues team repo
gitea-client show-issue team repo 42

# Product owner assistant adds epic/story management
skill product-owner-assistant create-epic team repo "Title" "Description"
```

### With Gitea Wiki
Automatically creates and updates wiki pages:

```bash
# Creates a wiki page documenting the epic and its stories
skill product-owner-assistant create-wiki-epic team repo 42
```

## 🚀 Best Practices

### Epic Management
1. **Clear Scope**: Each epic should represent significant business value
2. **Measurable Outcomes**: Define success criteria for each epic
3. **Regular Reviews**: Update epic progress weekly
4. **Stakeholder Alignment**: Ensure epics align with business goals

### User Story Creation
1. **INVEST Criteria**: Independent, Negotiable, Valuable, Estimable, Small, Testable
2. **Acceptance Criteria**: Clearly define "done" for each story
3. **Size Appropriately**: Stories should fit in a single sprint
4. **User-Centric**: Focus on user needs and outcomes

### Backlog Refinement
1. **Regular Cadence**: Schedule weekly or bi-weekly sessions
2. **Cross-Functional**: Include developers, testers, designers
3. **Time-Boxed**: Keep sessions focused and efficient
4. **Decision-Oriented**: Make clear decisions on priorities

## 🔮 Future Enhancements

- **Roadmap Visualization**: Generate timeline views of epics
- **Dependency Mapping**: Visualize epic dependencies
- **Resource Planning**: Estimate team capacity needs
- **Risk Management**: Track and mitigate epic risks
- **Project Board Integration**: Sync with Gitea project management
- **Custom Fields**: Support for epic-specific metadata

## 🤖 Usage with AI Agent

The skill is designed to work seamlessly with Mistral Vibe:

```bash
# AI can use the skill directly
task product-owner-assistant create-epic arcodange dance-lessons-coach \
  "AI Feature Implementation" \
  "Implement AI-powered recommendations and automation"

# Or use it in complex workflows
skill product-owner-assistant refine-backlog arcodange dance-lessons-coach \
  ai-refinement-results.md
```

## 📝 License

MIT License - See the [LICENSE](../../../LICENSE) file for details.

## 🙏 Contributing

Contributions are welcome! Please see the main project's CONTRIBUTING.md for guidelines.

## 📞 Support

For issues or questions:
1. Check the [documentation](SKILL.md)
2. Review the [reference guides](references/)
3. Consult the [gitea-client skill](../../gitea-client/SKILL.md)
4. Ask the AI agent for guidance

This skill provides comprehensive epic and user story management capabilities for effective agile product ownership.