/dd-file-issue

name: dd-file-issue
description: File GitHub issues to the right repository (pup CLI or plugin)
trigger: |
  Use this skill when the user wants to:
  - Report a bug
  - Request a feature
  - File an issue
  - Submit a problem report
  - Report something not working
  - Suggest an improvement
examples:
  - "This isn't working, file an issue"
  - "Can you create a bug report for this?"
  - "I want to request a new feature"
  - "Report this error to the team"

DD File Issue Skill

This skill helps you file GitHub issues to the correct repository. All issues — whether related to the `pup` CLI, skills, agents, or documentation — are tracked in `DataDog/pup`.

**Invocation**: `/dd-file-issue`

Decision Logic: Which Repository?

File to `DataDog/pup` Repository

All issues are filed here, including:

• **API Functionality**: API calls failing, incorrect responses, missing API endpoints
• **Authentication**: OAuth2 issues, token refresh problems, API key handling
• **CLI Behavior**: Command syntax, flags not working, output format issues
• **pup Installation**: Binary installation, PATH issues, version problems
• **API Coverage**: Missing Datadog API endpoints, incomplete command coverage
• **Performance**: Slow API calls, timeout issues
• **Error Messages**: Confusing pup error messages, API errors
• **Agent Behavior**: Agent selection, agent prompts, agent responses
• **Documentation**: README, CLAUDE.md, AGENTS.md, agent files inaccurate
• **Agent Prompts**: Agent giving wrong guidance, unclear instructions
• **Skill Issues**: Skills not working correctly
• **Agent Selection**: Claude picking wrong agent for task
• **Examples/Guides**: Missing or incorrect examples in agent files
• **User Experience**: Confusing workflows, unclear instructions

**Example Issues**:

• "pup logs search returns 404 error"
• "OAuth token refresh not working"
• "Need support for new Datadog API endpoint"
• "pup --output=json returns invalid JSON"
• "pup auth login fails on Linux"
• "logs agent doesn't explain query syntax clearly"
• "Agent tells me to use wrong pup command"
• "Documentation says to use TypeScript but we use pup now"
• "Need better examples for metrics queries"
• "Agent selection guide is confusing"

Workflow

1. **Gather Information**

• What went wrong?
• What were you trying to do?
• What error message did you see (if any)?
• What agent/command were you using?

2. **Determine Repository**

• All issues go to `DataDog/pup`

3. **Check for Existing Issues**

• Search the target repository for similar issues
• If found, suggest commenting on existing issue instead

4. **Collect Issue Details**

• Title: Clear, concise summary (e.g., "logs agent: incorrect time format example")
• Body: Detailed description with:
• What happened
• Expected behavior
• Steps to reproduce
• Environment details (OS, pup version, plugin version)
• Relevant logs/errors

5. **Select Issue Type**

• Bug report
• Feature request
• Documentation improvement
• Question

6. **Create Issue**

• Use `gh issue create` to file the issue
• Add appropriate labels
• Provide issue URL to user

Implementation

1. Determine Repository

All issues are filed against `DataDog/pup`. Ask clarifying questions to gather detail:

To file this issue correctly, I need to understand:

1. What were you trying to do?
2. What went wrong?
3. Was this a problem with:
   - A pup command not working?
   - An agent giving bad guidance?
   - Documentation being wrong/unclear?

2. Search for Existing Issues

gh issue list \
  --repo DataDog/pup \
  --search "your search terms" \
  --limit 10

3. Create Issue

gh issue create \
  --repo DataDog/pup \
  --title "Clear, concise title" \
  --body "Detailed description" \
  --label "bug" # or "enhancement", "documentation"

Issue Body Template

Use this template for comprehensive issue reports:

## Description
[Clear description of the issue]

## Expected Behavior
[What should happen]

## Actual Behavior
[What actually happened]

## Steps to Reproduce
1. [First step]
2. [Second step]
3. [...]

## Environment
- OS: [e.g., macOS 14.1, Ubuntu 22.04]
- Pup version: [run `pup --version`]
- Plugin version: [from plugin.json]
- Claude Code version: [if relevant]

## Error Messages / Logs

[Paste any error messages or relevant logs]

## Additional Context
[Any other relevant information]

## Suggested Fix (Optional)
[If you have ideas for how to fix this]

Best Practices

Good Issue Titles

✅ Good:

• "logs agent: incorrect time format documentation"
• "pup metrics query: --from flag ignores relative time"
• "Agent selection guide: missing decision tree for security agents"

❌ Bad:

• "It doesn't work"
• "Bug"
• "Help"

When to Bundle Issues

• **Don't bundle** unrelated issues - file separately
• **Do bundle** if multiple issues stem from same root cause
• **Do bundle** if documenting several examples of same problem

Labels to Use

**For pup repository**:

• `bug` - Something isn't working
• `enhancement` - New feature or request
• `documentation` - Improvements or additions to documentation
• `agent` - Related to specific agent behavior
• `skill` - Related to skills
• `question` - Further information is requested

Examples

Example 1: Filing a pup Bug

**User**: "The pup logs search command times out after 30 seconds"

**Analysis**: This is a pup CLI issue (command behavior)

**Steps**: 1. Search existing issues: `gh issue list --repo DataDog/pup --search "timeout"` 2. If not found, create issue:

gh issue create \
  --repo DataDog/pup \
  --title "pup logs search: command times out after 30 seconds" \
  --body "## Description
The \`pup logs search\` command times out after 30 seconds when searching large time ranges.

## Expected Behavior
Should either complete the query or allow configurable timeout.

## Actual Behavior
Command f