dd-file-issue

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

3. Create Issue

Issue Body Template

Use this template for comprehensive issue reports:

[Paste any error messages or relevant logs]

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:

Example 2: Filing a Documentation Issue

User: "The logs agent documentation shows TypeScript examples instead of pup commands"

Analysis: This is a documentation issue

Steps:

1. Search existing issues: gh issue list --repo DataDog/pup --search "TypeScript"
2. Create issue:

Example 3: Feature Request

User: "Can we add an agent for Datadog SLO reporting?"

Analysis: This is a pup enhancement (new agent)

Error Handling

If issue creation fails:

1. Check network connectivity
2. Verify gh CLI is authenticated: gh auth status
3. Check repository permissions
4. Provide user with issue details to file manually

Success Response

After successfully filing an issue:

Tips for Users

1. Be specific - Include exact commands, error messages, agent names
2. Provide context - What were you trying to accomplish?
3. Include environment details - OS, versions, configuration
4. One issue per report - Don't bundle unrelated problems
5. Check existing issues first - Avoid duplicates
6. Be patient - Maintainers will respond when available