DD File Issue Skill

Name: dd-file-issue
Rating: 92
Author: DataDog

This skill helps you file GitHub issues to the correct repository - either the pup CLI tool or the Claude plugin, depending on the nature of the issue.

Invocation: /dd-file-issue

Decision Logic: Which Repository?

File to `DataDog/pup` Repository

Issues related to the pup CLI tool itself:

•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 (when not related to agents)
•Error Messages: Confusing pup error messages, API errors

Example Issues for pup:

•"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"

File to `DataDog/datadog-api-claude-plugin` Repository

Issues related to the Claude plugin and its agents:

•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
•Plugin Installation: Plugin setup, configuration issues
•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 for plugin:

•"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"

Unclear Cases (Ask User)

If unclear which repository the issue belongs to:

•Ask the user for more context
•Explain the difference between pup and plugin issues
•Let user decide

Workflow

•
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?
•
Determine Repository
- •Analyze the issue against decision logic above
- •If unclear, ask user to clarify
•
Check for Existing Issues
- •Search the target repository for similar issues
- •If found, suggest commenting on existing issue instead
•
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
•
Select Issue Type
- •Bug report
- •Feature request
- •Documentation improvement
- •Question
•
Create Issue
- •Use gh issue create to file the issue
- •Add appropriate labels
- •Provide issue URL to user

Implementation

1. Determine Repository

Ask clarifying questions:

markdown

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? (→ pup repo)
   - An agent giving bad guidance? (→ plugin repo)
   - Documentation being wrong/unclear? (→ plugin repo)

2. Search for Existing Issues

For pup repository:

bash

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

For plugin repository:

bash

gh issue list \
  --repo DataDog/datadog-api-claude-plugin \
  --search "your search terms" \
  --limit 10

3. Create Issue

For pup repository:

bash

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

For plugin repository:

bash

gh issue create \
  --repo DataDog/datadog-api-claude-plugin \
  --title "Clear, concise title" \
  --body "Detailed description" \
  --label "bug" # or "enhancement", "documentation", "agent"

Issue Body Template

Use this template for comprehensive issue reports:

markdown

## 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]

code


## 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
•question - Further information is requested

For plugin 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:

•Search existing issues: gh issue list --repo DataDog/pup --search "timeout"
•If not found, create issue:

bash

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 fails with timeout error after 30 seconds.

## Steps to Reproduce
1. Run: \`pup logs search --query='*' --from='7d' --to='now'\`
2. Wait 30 seconds
3. See timeout error

## Environment
- OS: macOS 14.1
- Pup version: 1.2.3
- DD_SITE: datadoghq.com

## Error Message
\`\`\`
Error: request timeout after 30000ms
\`\`\`
" \
  --label "bug"

Example 2: Filing a Plugin Documentation Issue

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

Analysis: This is a plugin issue (documentation)

Steps:

•Search existing issues: gh issue list --repo DataDog/datadog-api-claude-plugin --search "TypeScript"
•Create issue:

bash

gh issue create \
  --repo DataDog/datadog-api-claude-plugin \
  --title "logs agent: outdated TypeScript examples in documentation" \
  --body "## Description
The logs agent documentation still shows TypeScript/Node.js examples instead of pup CLI commands.

## Location
\`agents/logs.md\` lines 150-200

## Expected
Should show pup CLI command examples like:
\`\`\`bash
pup logs search --query='*' --from='1h'
\`\`\`

## Actual
Shows TypeScript code with imports and API clients

## Impact
Confusing for users who expect pup CLI commands

## Files Affected
- agents/logs.md
- Possibly other agent files (need audit)
" \
  --label "documentation" \
  --label "agent"

Example 3: Feature Request for Plugin

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

Analysis: This is a plugin enhancement (new agent)

bash

gh issue create \
  --repo DataDog/datadog-api-claude-plugin \
  --title "enhancement: add SLO reporting agent" \
  --body "## Feature Request

### Description
Add a new agent focused on SLO reporting and analysis, separate from the SLO management agent.

### Use Cases
- Generate SLO reports for stakeholders
- Analyze SLO trends over time
- Compare SLOs across services

### Proposed Agent Capabilities
- Query SLO history
- Generate formatted reports
- Calculate SLO burn rates
- Identify at-risk SLOs

### Related Agents
- Current \`slos.md\` focuses on SLO CRUD operations
- New agent would focus on analytics and reporting

### Priority
Medium - would improve SLO workflow
" \
  --label "enhancement" \
  --label "agent"

Error Handling

If issue creation fails:

•Check network connectivity
•Verify gh CLI is authenticated: gh auth status
•Check repository permissions
•Provide user with issue details to file manually

Success Response

After successfully filing an issue:

markdown

✅ Issue created successfully!

**Repository**: DataDog/[repo-name]
**Issue**: #123
**URL**: https://github.com/DataDog/[repo-name]/issues/123
**Title**: [issue title]

The team will review your issue and respond soon. You can:
- Track the issue at the URL above
- Add more details by commenting on the issue
- Subscribe to notifications for updates

Tips for Users

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

DD File Issue Skill

Decision Logic: Which Repository?

File to DataDog/pup Repository

File to DataDog/datadog-api-claude-plugin Repository

Unclear Cases (Ask User)

Workflow

Implementation

1. Determine Repository

2. Search for Existing Issues

3. Create Issue

Issue Body Template

Best Practices

Good Issue Titles

When to Bundle Issues

Labels to Use

Examples

Example 1: Filing a pup Bug

Example 2: Filing a Plugin Documentation Issue

Example 3: Feature Request for Plugin

Error Handling

Success Response

Tips for Users

File to `DataDog/pup` Repository

File to `DataDog/datadog-api-claude-plugin` Repository