dd-file-issue

# 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

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**
   - Analyze the issue against decision logic above
   - If unclear, ask user to clarify

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

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]

```

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

1. Search existing issues: `gh issue list --repo DataDog/pup --search "timeout"`
2. 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**:

1. Search existing issues: `gh issue list --repo DataDog/datadog-api-claude-plugin --search "TypeScript"`
2. 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:

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:

```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

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