codebot help command #4

New Issue

Latte · 2025-12-28T17:20:53Z

Latte commented

2025-12-28 17:20:53 +00:00

Feature Request: @codebot help Command

Summary

Add a @codebot help command that displays all available commands with descriptions and usage examples, making bot capabilities immediately discoverable to users.

What problem does this solve?

Current Problem:
Users have no way to discover what commands are available without reading external documentation. New users don't know what the bot can do, leading to:

Underutilization of bot features
Frequent support questions about capabilities
Slower onboarding for new team members
Users missing powerful features like triage, security scans, and interactive chat

User Pain:

"I don't know what I can ask @codebot to do"
"How do I trigger issue triage?"
"What commands are available?"
Support teams repeatedly explaining the same commands

User story / Use case

As a developer new to the repository,
I want to see all available @codebot commands with examples,
so that I can quickly understand how to interact with the bot without leaving GitHub/Gitea or reading external documentation.

Example scenario:

Developer creates first issue in new repository
Types @codebot help in a comment
Bot immediately responds with complete command list and examples
Developer can now use triage, summarize, explain, suggest, and chat commands

Proposed solution

Implementation

Add a help command handler to IssueAgent that:

Reads command list from config.yml (interaction.commands)
Formats response with:
- Command categories (Issue Triage, Chat, Analysis, Utility)
- Each command with description
- Usage examples
- Link to full documentation (optional)
Posts formatted comment using existing upsert_comment() method

Example Output

@username

**Available @codebot Commands:**

**Issue Triage & Analysis:**
- `@codebot triage` - Full issue triage with auto-labeling and priority assignment
- `@codebot summarize` - Generate 2-3 sentence summary
- `@codebot explain` - Detailed explanation of the issue
- `@codebot suggest` - Solution suggestions or next steps

**Interactive Chat:**
- `@codebot [question]` - Ask questions about the codebase (uses search tools)

**Pull Request Analysis:**
- `@codebot review-again` - Re-run PR review without new commits
- `@codebot changelog` - Generate changelog from PR (coming soon)

**Codebase Analysis:**
- `@codebot codebase` - Trigger full codebase health analysis

**Setup & Utility:**
- `@codebot help` - Show this message
- `@codebot setup-labels` - Auto-create required repository labels (coming soon)

**Examples:**

@codebot triage
@codebot how does authentication work in this project?
@codebot explain


**Documentation:** [Read full docs](https://github.com/YourOrg/OpenRabbit/blob/main/README.md)

Files to Modify

tools/ai-review/config.yml

interaction:
  commands:
    - help        # Add to commands list
    - explain
    - suggest
    # ... existing commands

tools/ai-review/agents/issue_agent.py

def _command_help(self, owner: str, repo: str, issue_index: int) -> str:
    """Generate help message with all available commands."""
    commands = self.config.get("interaction", {}).get("commands", [])

    help_text = """**Available @codebot Commands:**

Issue Triage & Analysis:

@codebot triage - Full issue triage with auto-labeling and priority assignment
@codebot summarize - Generate 2-3 sentence summary
@codebot explain - Detailed explanation of the issue
@codebot suggest - Solution suggestions or next steps

Interactive Chat:

@codebot [question] - Ask questions about the codebase

Utility:

@codebot help - Show this message

Examples:

@codebot triage
@codebot how does authentication work?
@codebot explain

"""
return help_text

def _handle_command(self, command: str, owner: str, repo: str,
issue_index: int, full_comment: str) -> str:
"""Route command to appropriate handler."""
if command == "help":
return self._command_help(owner, repo, issue_index)
elif command == "triage":
return self._command_triage(owner, repo, issue_index)
# ... existing command handlers


## Alternatives considered

### Alternative 1: Static README section
- **Rejected:** Users would need to navigate away from their workflow
- Doesn't provide contextual help when they need it

### Alternative 2: Automatic help on first mention
- **Rejected:** Could be annoying if user already knows commands
- Adds unnecessary noise to issues

### Alternative 3: Rich interactive menu (buttons/dropdown)
- **Rejected:** Not supported in GitHub/Gitea comment markdown
- Would require custom UI integration

### Alternative 4: External documentation only
- **Rejected:** Creates friction, users prefer in-context help
- Current approach with external docs + in-app help is best of both worlds

## Acceptance criteria

- [ ] `@codebot help` command responds with formatted list of all commands
- [ ] Response includes command categories (Triage, Chat, Utility)
- [ ] Each command includes clear description
- [ ] Response includes at least 3 usage examples
- [ ] Help text is automatically generated from `config.yml` commands list
- [ ] Works in both issue comments and PR comments
- [ ] Response time < 3 seconds
- [ ] Command is documented in README.md
- [ ] No breaking changes to existing commands
- [ ] Unit tests added for help command handler

**Backwards compatibility:**
- ✅ No breaking changes - purely additive feature
- ✅ No migration needed
- ✅ Works with all existing workflows

## Impact

**Complexity:** **LOW**
- Estimated effort: 1-2 hours
- Single file changes (`issue_agent.py`, `config.yml`)
- No new dependencies
- No database/infrastructure changes

**User Impact:** **HIGH**
- Immediate discoverability improvement
- Reduces support burden significantly
- Foundation for future command additions
- Better onboarding experience

**Technical Impact:**
- Minimal code changes
- No performance concerns
- Easy to test and maintain
- Enables self-service learning

## Mockups / examples

### Example 1: User requests help
```markdown
**Issue #123: Bug in authentication**

User comment:
> @codebot help

Bot response:
> @username
> 
> **Available @codebot Commands:**
> 
> **Issue Triage & Analysis:**
> - `@codebot triage` - Full issue triage with auto-labeling...
> [full help text]

Example 2: Help in PR comment

**Pull Request #45: Add user login**

User comment:
> @codebot help

Bot response:
> [Same help text, works identically in PR comments]

Example 3: Integration with existing commands

User: @codebot help
Bot: [shows all commands]

User: @codebot triage
Bot: [performs triage as normal]

Implementation Plan

Phase 1: Core Implementation (1 hour)

Add help to config.yml commands list
Implement _command_help() method in IssueAgent
Update _handle_command() to route to help handler
Format help text with all command categories

Phase 2: Testing & Documentation (30 minutes)

Test in local Gitea instance
Verify formatting renders correctly
Update README.md with help command
Add unit tests

Phase 3: Deployment (30 minutes)

Create PR with changes
Merge to main
Update workflows if needed
Monitor for issues

Dependencies

None - This is a standalone feature with no external dependencies.

Related to Milestone 2: UX & Discoverability
Part of quick wins strategy (high value, low effort)
Foundation for @codebot setup-labels (Milestone 3)

Success Metrics

Week 1 after deployment:

50%+ of new users discover help command
Reduction in "what can the bot do?" support questions
Zero bugs reported for help command

Month 1 after deployment:

80%+ user awareness of available commands
Increased usage of lesser-known commands (suggest, triage)
Positive user feedback on discoverability

Checklist

I searched existing feature requests and discussions
This request includes user story and acceptance criteria
Impact assessment completed (LOW complexity, HIGH value)
Implementation plan outlined
Acceptance criteria defined
Success metrics identified

Priority: ⭐ HIGHEST - Quick win for immediate UX improvement
Milestone: Milestone 2 - UX & Discoverability
Estimated Effort: 1-2 hours
Value: HIGH

# Feature Request: @codebot help Command ## Summary Add a `@codebot help` command that displays all available commands with descriptions and usage examples, making bot capabilities immediately discoverable to users. ## What problem does this solve? **Current Problem:** Users have no way to discover what commands are available without reading external documentation. New users don't know what the bot can do, leading to: - Underutilization of bot features - Frequent support questions about capabilities - Slower onboarding for new team members - Users missing powerful features like triage, security scans, and interactive chat **User Pain:** - "I don't know what I can ask @codebot to do" - "How do I trigger issue triage?" - "What commands are available?" - Support teams repeatedly explaining the same commands ## User story / Use case **As a** developer new to the repository, **I want** to see all available @codebot commands with examples, **so that** I can quickly understand how to interact with the bot without leaving GitHub/Gitea or reading external documentation. **Example scenario:** 1. Developer creates first issue in new repository 2. Types `@codebot help` in a comment 3. Bot immediately responds with complete command list and examples 4. Developer can now use triage, summarize, explain, suggest, and chat commands ## Proposed solution ### Implementation Add a `help` command handler to `IssueAgent` that: 1. **Reads command list** from `config.yml` (`interaction.commands`) 2. **Formats response** with: - Command categories (Issue Triage, Chat, Analysis, Utility) - Each command with description - Usage examples - Link to full documentation (optional) 3. **Posts formatted comment** using existing `upsert_comment()` method ### Example Output ```markdown @username **Available @codebot Commands:** **Issue Triage & Analysis:** - `@codebot triage` - Full issue triage with auto-labeling and priority assignment - `@codebot summarize` - Generate 2-3 sentence summary - `@codebot explain` - Detailed explanation of the issue - `@codebot suggest` - Solution suggestions or next steps **Interactive Chat:** - `@codebot [question]` - Ask questions about the codebase (uses search tools) **Pull Request Analysis:** - `@codebot review-again` - Re-run PR review without new commits - `@codebot changelog` - Generate changelog from PR (coming soon) **Codebase Analysis:** - `@codebot codebase` - Trigger full codebase health analysis **Setup & Utility:** - `@codebot help` - Show this message - `@codebot setup-labels` - Auto-create required repository labels (coming soon) **Examples:** ``` @codebot triage @codebot how does authentication work in this project? @codebot explain ``` **Documentation:** [Read full docs](https://github.com/YourOrg/OpenRabbit/blob/main/README.md) ``` ### Files to Modify 1. **`tools/ai-review/config.yml`** ```yaml interaction: commands: - help # Add to commands list - explain - suggest # ... existing commands ``` 2. **`tools/ai-review/agents/issue_agent.py`** ```python def _command_help(self, owner: str, repo: str, issue_index: int) -> str: """Generate help message with all available commands.""" commands = self.config.get("interaction", {}).get("commands", []) help_text = """**Available @codebot Commands:** **Issue Triage & Analysis:** - `@codebot triage` - Full issue triage with auto-labeling and priority assignment - `@codebot summarize` - Generate 2-3 sentence summary - `@codebot explain` - Detailed explanation of the issue - `@codebot suggest` - Solution suggestions or next steps **Interactive Chat:** - `@codebot [question]` - Ask questions about the codebase **Utility:** - `@codebot help` - Show this message **Examples:** ``` @codebot triage @codebot how does authentication work? @codebot explain ``` """ return help_text def _handle_command(self, command: str, owner: str, repo: str, issue_index: int, full_comment: str) -> str: """Route command to appropriate handler.""" if command == "help": return self._command_help(owner, repo, issue_index) elif command == "triage": return self._command_triage(owner, repo, issue_index) # ... existing command handlers ``` ## Alternatives considered ### Alternative 1: Static README section - **Rejected:** Users would need to navigate away from their workflow - Doesn't provide contextual help when they need it ### Alternative 2: Automatic help on first mention - **Rejected:** Could be annoying if user already knows commands - Adds unnecessary noise to issues ### Alternative 3: Rich interactive menu (buttons/dropdown) - **Rejected:** Not supported in GitHub/Gitea comment markdown - Would require custom UI integration ### Alternative 4: External documentation only - **Rejected:** Creates friction, users prefer in-context help - Current approach with external docs + in-app help is best of both worlds ## Acceptance criteria - [ ] `@codebot help` command responds with formatted list of all commands - [ ] Response includes command categories (Triage, Chat, Utility) - [ ] Each command includes clear description - [ ] Response includes at least 3 usage examples - [ ] Help text is automatically generated from `config.yml` commands list - [ ] Works in both issue comments and PR comments - [ ] Response time < 3 seconds - [ ] Command is documented in README.md - [ ] No breaking changes to existing commands - [ ] Unit tests added for help command handler **Backwards compatibility:** - ✅ No breaking changes - purely additive feature - ✅ No migration needed - ✅ Works with all existing workflows ## Impact **Complexity:** **LOW** - Estimated effort: 1-2 hours - Single file changes (`issue_agent.py`, `config.yml`) - No new dependencies - No database/infrastructure changes **User Impact:** **HIGH** - Immediate discoverability improvement - Reduces support burden significantly - Foundation for future command additions - Better onboarding experience **Technical Impact:** - Minimal code changes - No performance concerns - Easy to test and maintain - Enables self-service learning ## Mockups / examples ### Example 1: User requests help ```markdown **Issue #123: Bug in authentication** User comment: > @codebot help Bot response: > @username > > **Available @codebot Commands:** > > **Issue Triage & Analysis:** > - `@codebot triage` - Full issue triage with auto-labeling... > [full help text] ``` ### Example 2: Help in PR comment ```markdown **Pull Request #45: Add user login** User comment: > @codebot help Bot response: > [Same help text, works identically in PR comments] ``` ### Example 3: Integration with existing commands ```markdown User: @codebot help Bot: [shows all commands] User: @codebot triage Bot: [performs triage as normal] ``` ## Implementation Plan ### Phase 1: Core Implementation (1 hour) 1. Add `help` to `config.yml` commands list 2. Implement `_command_help()` method in `IssueAgent` 3. Update `_handle_command()` to route to help handler 4. Format help text with all command categories ### Phase 2: Testing & Documentation (30 minutes) 1. Test in local Gitea instance 2. Verify formatting renders correctly 3. Update README.md with help command 4. Add unit tests ### Phase 3: Deployment (30 minutes) 1. Create PR with changes 2. Merge to main 3. Update workflows if needed 4. Monitor for issues ## Dependencies **None** - This is a standalone feature with no external dependencies. ## Related Issues/PRs - Related to Milestone 2: UX & Discoverability - Part of quick wins strategy (high value, low effort) - Foundation for `@codebot setup-labels` (Milestone 3) ## Success Metrics **Week 1 after deployment:** - [ ] 50%+ of new users discover help command - [ ] Reduction in "what can the bot do?" support questions - [ ] Zero bugs reported for help command **Month 1 after deployment:** - [ ] 80%+ user awareness of available commands - [ ] Increased usage of lesser-known commands (suggest, triage) - [ ] Positive user feedback on discoverability ## Checklist - [x] I searched existing feature requests and discussions - [x] This request includes user story and acceptance criteria - [x] Impact assessment completed (LOW complexity, HIGH value) - [x] Implementation plan outlined - [x] Acceptance criteria defined - [x] Success metrics identified --- **Priority:** ⭐ **HIGHEST** - Quick win for immediate UX improvement **Milestone:** Milestone 2 - UX & Discoverability **Estimated Effort:** 1-2 hours **Value:** HIGH

Latte added this to the Milestone 1: Core Features (Quick Wins) milestone 2025-12-28 17:37:01 +00:00

Latte added the Kind/Feature

Priority

High

2

labels 2025-12-28 17:37:23 +00:00

Latte added this to the Development Roadmap project 2025-12-28 17:47:15 +00:00

Latte self-assigned this 2025-12-28 17:47:25 +00:00

Latte moved this to In Progress in Development Roadmap on 2025-12-28 18:54:51 +00:00

Latte commented

2025-12-28 19:01:35 +00:00

@codebot could you look at the pr from this issue and let me know if it looks good?