DD File Issue Skill

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:

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:

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

For plugin repository:

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

3. Create Issue

For pup repository:

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

For plugin repository:

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:

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

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:

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)

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:

✅ 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