# Progressive Help System

## Purpose

Provide context-aware help that reveals features progressively based on user experience level and current needs. Avoid overwhelming new users while empowering advanced users.

## Help Levels

### Level 1: First Time User

**Triggered by**: New installation, first 'help' command, or setup incomplete

```
👋 Welcome to JIRA Integration!

I help you sync BMAD stories with JIRA. Let's start simple:

Essential Commands:
• setup jira    - Connect to your JIRA (start here!)
• sync          - Sync stories to JIRA
• create standup - Generate daily meeting agenda
• help          - See more options

Not set up yet? Just say "setup jira" and I'll guide you!
```

### Level 2: Basic User

**Triggered by**: Successful setup, 1-5 previous operations

```
JIRA Integration - Common Tasks:

✅ You've connected to: acme.atlassian.net

Daily Operations:
• sync [story]     - Sync specific story or all changes
• create standup   - Daily meeting agenda with JIRA data
• sprint health    - Current sprint status report
• show blockers    - List blocking issues

Need More?
• help advanced    - See advanced features
• help examples    - See usage examples
```

### Level 3: Regular User

**Triggered by**: 5+ operations, multiple sync types used

```
JIRA Integration - Full Feature Set:

Sync Operations:
• sync             - Smart sync based on context
• bulk sync        - Sync multiple stories efficiently
• sync status      - Update only status fields

Team Coordination:
• standup          - Daily scrum agenda
• weekly sync      - Comprehensive team update
• global sync      - Multi-timezone coordination

Reports & Analytics:
• sprint health    - Velocity, burndown, risks
• team performance - Productivity metrics
• backlog health   - Grooming readiness

Advanced:
• visual dashboard - Interactive sync status
• help workflows   - Complex workflow examples
```

### Level 4: Power User

**Triggered by**: 20+ operations, used advanced features

```
JIRA Integration - Power Features:

Advanced Sync:
• three-way sync analysis    - Git↔BMAD↔JIRA correlation
• sync with preview         - Dry run before changes
• selective field sync      - Update specific fields only

Automation:
• auto-sync rules          - Configure triggers
• scheduled sync           - Cron-based automation
• webhook integration      - Real-time updates

Maintenance:
• cleanup orphaned        - Remove stale issues
• bulk status fix        - Correct misaligned statuses
• field remapping        - Update custom fields

Developer Tools:
• sync health api       - JSON metrics endpoint
• debug sync           - Verbose logging mode
• help internals      - Technical documentation
```

## Contextual Help

### By Current Activity

**During Story Editing**:

```
💡 JIRA Tip: This story isn't synced yet. Say "sync this" to create a JIRA ticket.
```

**After Failed Sync**:

```
Need help? Common solutions:
• "check jira connection" - Verify setup
• "sync with preview" - See what would change
• "help sync errors" - Troubleshooting guide
```

**During Sprint Boundary**:

```
🏃 Sprint ending soon! You might want to:
• "sprint health" - Final sprint report
• "sync all done stories" - Close completed work
• "prepare retrospective" - Retro meeting prep
```

### By Error Type

**No JIRA Connection**:

```
JIRA not connected. Let's fix that:
1. Say "setup jira" for guided setup
2. Or "help setup" for manual instructions
```

**Permission Error**:

```
Permission issue detected. Try:
• "test jira permissions" - See what's missing
• "help permissions" - Setup guide
• Contact JIRA admin with this: [specific permission list]
```

## Smart Suggestions

### Based on Usage Patterns

**Frequent Manual Syncs**:

```
💡 I notice you sync manually often. Want to set up auto-sync?
Say "configure auto-sync" to save time.
```

**Always Using Same Project**:

```
💡 Always working with AUTH project? I can make that your default.
Say "set default project AUTH"
```

**Complex Queries**:

```
💡 Power user tip: You can use JQL directly!
Example: "find issues where assignee=me AND sprint=current"
```

## Help Command Variations

### Structured Help

- `help` - Appropriate level based on experience
- `help basic` - Essential commands only
- `help advanced` - All features
- `help examples` - Real usage examples
- `help workflows` - Common workflow patterns

### Topic Help

- `help sync` - Everything about syncing
- `help standup` - Meeting generation help
- `help reports` - Reporting features
- `help setup` - Configuration help
- `help errors` - Troubleshooting

### Contextual Help

- `help with this` - Context-aware suggestions
- `what can I do here?` - Current options
- `show tips` - Random useful tips
- `help me` - Conversational assistance

## Implementation Guidelines

[[LLM: When providing help:

1. Check user's experience level:
   - New: Show only essentials
   - Basic: Add common tasks
   - Regular: Show full features
   - Power: Include advanced options

2. Consider context:
   - Current file/task
   - Recent errors
   - Time of day (standup time?)
   - Sprint phase

3. Format for clarity:
   - Use categories
   - Show examples
   - Highlight next steps
   - Keep it concise

4. Promote discovery:
   - Suggest one new feature
   - Show related commands
   - Offer deeper dives
     ]]

## Progressive Feature Introduction

### Week 1: Basics

- Setup
- Simple sync
- Daily standup

### Week 2: Team Features

- Sprint reports
- Team sync
- Blockers

### Week 3: Analytics

- Performance metrics
- Trend analysis
- Roadmaps

### Week 4: Advanced

- Automation
- Customization
- Integration

## Benefits

1. **Reduces Overwhelm**: New users see only what they need
2. **Encourages Exploration**: Natural feature discovery
3. **Improves Adoption**: Gradual complexity increase
4. **Provides Value Fast**: Quick wins with basic features
5. **Scales with User**: Grows as expertise develops

This progressive help system ensures users get exactly the right amount of information at the right time, making the JIRA integration feel intuitive and powerful without being overwhelming.