--- 
name: product-owner-assistant
description: A skill for managing Gitea issues, organizing them into Epics and User Stories, and facilitating product backlog refinement
license: MIT
metadata:
  author: DanceLessonsCoach Team
  version: "1.0.0"
  dependencies:
    - gitea-client
--- 

# Product Owner Assistant

A comprehensive skill for product owners to manage Gitea issues, organize them into Epics and User Stories, and facilitate backlog refinement sessions. This skill integrates with the Gitea API to provide advanced issue management capabilities.

## Key Features

- **Epic Management**: Create and manage epics as parent issues
- **User Story Organization**: Group issues into user stories and features
- **Backlog Refinement**: Facilitate structured refinement sessions
- **Progress Tracking**: Visualize epic and story progress
- **Wiki Integration**: Document epics and stories in project wiki
- **Stakeholder Communication**: Generate progress reports

## Requirements

### Authentication

Same as `gitea-client` skill:

**Option 1: Environment Variable**
```bash
export GITEA_API_TOKEN="your_personal_access_token"
```

**Option 2: Token File** (Recommended)
```bash
export GITEA_API_TOKEN_FILE="/path/to/token_file"
```

### Dependencies

- `gitea-client` skill (for basic Gitea operations)
- `jq` for JSON processing
- `curl` for API requests

## Commands

### Create Epic

```bash
skill product-owner-assistant create-epic <owner> <repo> <title> <description> [labels]
```

Create a new epic as a parent issue with special labeling.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `title`: Epic title (e.g., "User Authentication System")
- `description`: Detailed epic description
- `labels`: Optional comma-separated labels (default: "epic,backlog")

**Example:**
```bash
# Create authentication epic
skill product-owner-assistant create-epic arcodange dance-lessons-coach \
  "User Authentication System" \
  "Implement comprehensive authentication system with OAuth, JWT, and session management" \
  "epic,authentication,high-priority"
```

### Create User Story

```bash
skill product-owner-assistant create-story <owner> <repo> <epic_id> <title> <description> [labels]
```

Create a user story linked to an epic.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `epic_id`: Parent epic issue number
- `title`: Story title
- `description`: Story description with acceptance criteria
- `labels`: Optional comma-separated labels (default: "story,backlog")

**Example:**
```bash
# Create login story under authentication epic
skill product-owner-assistant create-story arcodange dance-lessons-coach 42 \
  "User Login Functionality" \
  "As a user, I want to login with email/password so I can access my account\n\nAcceptance Criteria:\n- Valid credentials grant access\n- Invalid credentials show error\n- Remember me functionality works\n- Password reset option available" \
  "story,authentication,frontend"
```

### Link Issue to Epic

```bash
skill product-owner-assistant link-to-epic <owner> <repo> <issue_number> <epic_id>
```

Link an existing issue to an epic.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `issue_number`: Issue to link
- `epic_id`: Target epic issue number

**Example:**
```bash
# Link issue 45 to epic 42
skill product-owner-assistant link-to-epic arcodange dance-lessons-coach 45 42
```

### Show Epic Progress

```bash
skill product-owner-assistant epic-progress <owner> <repo> <epic_id>
```

Display epic progress with linked stories and their status.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `epic_id`: Epic issue number

**Example:**
```bash
# Show progress for epic 42
skill product-owner-assistant epic-progress arcodange dance-lessons-coach 42
```

### List Epics

```bash
skill product-owner-assistant list-epics <owner> <repo> [state]
```

List all epics in the repository.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `state`: Filter by state (open, closed, all) - default: open

**Example:**
```bash
# List all open epics
skill product-owner-assistant list-epics arcodange dance-lessons-coach

# List closed epics
skill product-owner-assistant list-epics arcodange dance-lessons-coach closed
```

### Backlog Refinement Session

```bash
skill product-owner-assistant refine-backlog <owner> <repo> <output_file>
```

Generate a structured backlog refinement document.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `output_file`: File to save refinement results

**Example:**
```bash
# Generate backlog refinement document
skill product-owner-assistant refine-backlog arcodange dance-lessons-coach backlog-refinement-2024-04-06.md
```

### Generate Progress Report

```bash
skill product-owner-assistant progress-report <owner> <repo> <output_file>
```

Generate a comprehensive progress report for all epics.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `output_file`: File to save the report

**Example:**
```bash
# Generate weekly progress report
skill product-owner-assistant progress-report arcodange dance-lessons-coach weekly-progress-2024-04-06.md
```

### Create Wiki Page for Epic

```bash
skill product-owner-assistant create-wiki-epic <owner> <repo> <epic_id>
```

Create a wiki page documenting an epic and its stories.

**Arguments:**
- `owner`: Repository owner
- `repo`: Repository name
- `epic_id`: Epic issue number

**Example:**
```bash
# Create wiki page for epic 42
skill product-owner-assistant create-wiki-epic arcodange dance-lessons-coach 42
```

## Workflows

### Epic Creation and Management

```bash
# 1. Create new epic
skill product-owner-assistant create-epic arcodange dance-lessons-coach \
  "Payment Processing System" \
  "Implement Stripe and PayPal integration for subscription payments" \
  "epic,payment,backend"

# 2. Create user stories under the epic
epic_id=43
skill product-owner-assistant create-story arcodange dance-lessons-coach $epic_id \
  "Stripe Integration" \
  "As a user, I want to pay with credit card via Stripe..." \
  "story,payment,stripe"

skill product-owner-assistant create-story arcodange dance-lessons-coach $epic_id \
  "PayPal Integration" \
  "As a user, I want to pay with PayPal..." \
  "story,payment,paypal"

# 3. Show epic progress
skill product-owner-assistant epic-progress arcodange dance-lessons-coach $epic_id

# 4. Create wiki documentation
skill product-owner-assistant create-wiki-epic arcodange dance-lessons-coach $epic_id
```

### Backlog Refinement Session

```bash
# 1. Generate refinement document
skill product-owner-assistant refine-backlog arcodange dance-lessons-coach refinement-session.md

# 2. Review and update issues based on refinement
# (Manual process - discuss with team, update priorities, etc.)

# 3. Generate updated progress report
skill product-owner-assistant progress-report arcodange dance-lessons-coach post-refinement-report.md

# 4. Update wiki with refinement results
# (Manual process - incorporate decisions into wiki)
```

### Sprint Planning Preparation

```bash
# 1. List all open epics
skill product-owner-assistant list-epics arcodange dance-lessons-coach

# 2. For each high-priority epic, show progress
for epic_id in 42 43 45; do
  echo "=== Epic $epic_id ==="
  skill product-owner-assistant epic-progress arcodange dance-lessons-coach $epic_id
  echo ""
done

# 3. Generate comprehensive progress report
skill product-owner-assistant progress-report arcodange dance-lessons-coach sprint-planning-report.md

# 4. Create/update wiki pages for key epics
skill product-owner-assistant create-wiki-epic arcodange dance-lessons-coach 42
skill product-owner-assistant create-wiki-epic arcodange dance-lessons-coach 43
```

## Usage Examples

### Creating a Complete Feature Epic

```bash
# Create the main epic
skill product-owner-assistant create-epic arcodange dance-lessons-coach \
  "Advanced Search Functionality" \
  "Implement comprehensive search with filters, saved searches, and search history" \
  "epic,search,frontend,backend"

# Add user stories
epic_id=$(skill product-owner-assistant list-epics arcodange dance-lessons-coach | grep "Advanced Search" | cut -d' ' -f1)

skill product-owner-assistant create-story arcodange dance-lessons-coach $epic_id \
  "Basic Search Implementation" \
  "As a user, I want to search for content by keyword..." \
  "story,search,mvp"

skill product-owner-assistant create-story arcodange dance-lessons-coach $epic_id \
  "Advanced Filters" \
  "As a user, I want to filter search results by date, type, author..." \
  "story,search,filters"

skill product-owner-assistant create-story arcodange dance-lessons-coach $epic_id \
  "Saved Searches" \
  "As a user, I want to save my search queries for quick access..." \
  "story,search,ux"

# Link existing related issues
skill product-owner-assistant link-to-epic arcodange dance-lessons-coach 55 $epic_id
skill product-owner-assistant link-to-epic arcodange dance-lessons-coach 58 $epic_id

# Show complete epic structure
skill product-owner-assistant epic-progress arcodange dance-lessons-coach $epic_id
```

### Weekly Progress Reporting

```bash
# Generate weekly progress report
report_date=$(date +%Y-%m-%d)
skill product-owner-assistant progress-report arcodange dance-lessons-coach \
  "weekly-progress-report-$report_date.md"

# Share with team (example - adapt to your communication tools)
echo "Weekly Progress Report Generated: weekly-progress-report-$report_date.md"
# Could integrate with email, Slack, or other notification systems
```

### Backlog Refinement with Stakeholders

```bash
# Prepare for refinement session
session_date=$(date +%Y-%m-%d)
skill product-owner-assistant refine-backlog arcodange dance-lessons-coach \
  "backlog-refinement-$session_date.md"

# During the session, use the generated document to:
# 1. Review each epic and its stories
# 2. Update priorities and estimates
# 3. Identify dependencies and risks
# 4. Make decisions on what to include in next sprint

# After the session, update issues and generate final report
skill product-owner-assistant progress-report arcodange dance-lessons-coach \
  "post-refinement-report-$session_date.md"
```

## Integration with Gitea Wiki

The skill can create and update wiki pages to document epics and their progress:

```bash
# Create wiki page for an epic
skill product-owner-assistant create-wiki-epic arcodange dance-lessons-coach 42

# This creates a wiki page with:
# - Epic title and description
# - List of all linked user stories
# - Current status of each story
# - Progress visualization
# - Links to all related issues
```

## Best Practices

### Epic Management

1. **Clear Scope**: Each epic should represent a significant feature or capability
2. **Measurable Outcomes**: Define success criteria for each epic
3. **Time-Bound**: Estimate epic duration (e.g., "2-3 sprints")
4. **Regular Reviews**: Update epic progress weekly
5. **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. **Vertical Slices**: Deliver end-to-end functionality
5. **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 and scope
5. **Documented**: Record decisions and action items

### Progress Tracking

1. **Visualize Progress**: Use the epic-progress command regularly
2. **Update Frequently**: Keep epic status current
3. **Communicate Changes**: Share progress with stakeholders
4. **Celebrate Milestones**: Acknowledge completed epics
5. **Learn from Completion**: Conduct retrospectives on finished epics

## Advanced Features

### Custom Labels

Create custom labels for better organization:

```bash
# Create epic and story labels
gitea-client create-label arcodange dance-lessons-coach "epic" "#ff69b4"
gitea-client create-label arcodange dance-lessons-coach "story" "#ffa500"
gitea-client create-label arcodange dance-lessons-coach "feature" "#00ced1"
```

### Milestone Tracking

Associate epics with milestones:

```bash
# Create milestone
gitea-client create-milestone arcodange dance-lessons-coach "Q2 2024" "2024-06-30"

# Assign epic to milestone
skill product-owner-assistant create-epic arcodange dance-lessons-coach \
  "User Profile Enhancements" \
  "Improve user profile with social features" \
  "epic,profile,milestone-Q2-2024"
```

### Cross-Project Epics

For large initiatives spanning multiple repositories:

```bash
# Create epic in main repo
skill product-owner-assistant create-epic arcodange dance-lessons-coach \
  "Cross-Platform Mobile App" \
  "Develop iOS and Android apps with shared backend" \
  "epic,mobile,cross-project"

# Create related issues in other repos
# (Use gitea-client directly for other repositories)
```

## Implementation Notes

### Issue Linking Strategy

The skill uses Gitea's issue referencing system:

- **Parent-Child Relationships**: Epics reference stories using `#issue_number` in comments
- **Tracking**: Maintains a mapping of epic-story relationships
- **Progress Calculation**: Aggregates story status to determine epic completion

### Wiki Integration

Wiki pages are created with Markdown formatting:

```markdown
# [Epic Title]

**Status**: [Open/In Progress/Completed]
**Created**: [Date]
**Last Updated**: [Date]

## Description
[Epic description]

## User Stories

| Story | Status | Assignee |
|-------|--------|----------|
| [Story Title](#123) | Open | @developer |
| [Story Title](#124) | In Progress | @developer |

## Progress

![Progress](progress-bar)
- **Total Stories**: X
- **Completed**: Y
- **In Progress**: Z
- **Open**: W

## Related Issues

- [Issue #123](link): [Title]
- [Issue #124](link): [Title]
```

### Data Storage

The skill stores minimal local data:

- **Cache**: Temporary issue data for performance
- **State**: Epic-story relationships in `.vibe/skills/product-owner-assistant/data/`
- **Configuration**: User preferences and defaults

## Error Handling

Common issues and solutions:

- **Authentication Errors**: Verify `GITEA_API_TOKEN` or `GITEA_API_TOKEN_FILE`
- **Rate Limiting**: Wait and retry with exponential backoff
- **Missing Epics**: Verify epic ID exists and is accessible
- **Permission Issues**: Ensure token has required scopes
- **Network Problems**: Check connectivity to Gitea instance

## 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
- **Stakeholder Notifications**: Automated progress updates
- **Integration with Project Boards**: Sync with Gitea project management
- **Custom Fields**: Support for epic-specific metadata
- **Export/Import**: Bulk epic management

## References

- [Gitea API Documentation](https://gitea.com/api/swagger)
- [Agile Epic Management Guide](references/agile-epics.md)
- [User Story Writing Guide](references/user-stories.md)
- [Backlog Refinement Techniques](references/backlog-refinement.md)
- [Wiki Formatting Reference](references/wiki-formatting.md)

See the [references/](references/) directory for detailed guides and templates.
