Back to Details

dd-file-issue

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

DD File Issue Skill

DD 问题提交技能

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
该技能可帮助你根据问题性质，将GitHub问题提交到正确的仓库——要么是
pup
CLI工具仓库，要么是Claude插件仓库。
调用方式：
/dd-file-issue

Decision Logic: Which Repository?

决策逻辑：选择哪个仓库？

File to 
DataDog/pup
Repository

提交到
DataDog/pup
仓库

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"
与
pup
CLI工具本身相关的问题：
  • API功能：API调用失败、响应错误、缺少API端点
  • 认证：OAuth2问题、令牌刷新故障、API密钥处理问题
  • CLI行为：命令语法、标志无效、输出格式问题
  • pup安装：二进制文件安装、PATH配置问题、版本问题
  • API覆盖范围：缺少Datadog API端点、命令覆盖不完整
  • 性能：API调用缓慢、超时问题（与代理无关时）
  • 错误信息：pup错误信息不清晰、API错误
pup相关问题示例：
  • "pup logs search返回404错误"
  • "OAuth令牌刷新无法正常工作"
  • "需要支持新的Datadog API端点"
  • "pup --output=json返回无效JSON"
  • "pup auth login在Linux上失败"

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

提交到
DataDog/datadog-api-claude-plugin
仓库

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"
与Claude插件及其代理相关的问题：
  • 代理行为：代理选择、代理提示词、代理响应
  • 文档：README、CLAUDE.md、AGENTS.md、代理文件内容不准确
  • 代理提示词：代理给出错误指导、说明不清晰
  • 技能问题：技能无法正常工作
  • 插件安装：插件设置、配置问题
  • 代理选择：Claude为任务选择了错误的代理
  • 示例/指南：代理文件中缺少或错误的示例
  • 用户体验：工作流程混乱、说明不清晰
插件相关问题示例：
  • "logs代理未清晰解释查询语法"
  • "代理告诉我使用错误的pup命令"
  • "文档说要使用TypeScript，但我们现在用pup"
  • "需要更完善的指标查询示例"
  • "代理选择指南令人困惑"

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
如果无法确定问题属于哪个仓库：
  • 向用户询问更多上下文
  • 解释pup和插件问题的区别
  • 让用户自行决定

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
  1. 收集信息
    • 发生了什么问题？
    • 你当时尝试完成什么任务？
    • 看到了什么错误信息（如果有）？
    • 你使用的是哪个代理/命令？
  2. 确定仓库
    • 根据上述决策逻辑分析问题
    • 如果不确定，请用户澄清
  3. 检查现有问题
    • 在目标仓库中搜索类似问题
    • 如果找到，建议用户在现有问题下评论，而非重复提交
  4. 收集问题详情
    • 标题：清晰、简洁的总结（例如："logs agent: 时间格式示例错误"）
    • 正文：详细描述，包含：
      • 发生的情况
      • 预期行为
      • 复现步骤
      • 环境详情（操作系统、pup版本、插件版本）
      • 相关错误信息/日志
  5. 选择问题类型
    • 错误报告
    • 功能请求
    • 文档改进
    • 疑问
  6. 创建问题
    • 使用
      gh issue create
      命令提交问题
    • 添加合适的标签
    • 向用户提供问题链接

Implementation

实现细节

1. Determine Repository

1. 确定仓库

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)
询问澄清问题：
markdown
为了正确提交该问题，我需要了解：

1. 你当时尝试完成什么任务？
2. 发生了什么问题？
3. 这是以下哪类问题：
   - pup命令无法正常工作？（→ pup仓库）
   - 代理给出错误指导？（→ 插件仓库）
   - 文档内容错误/不清晰？（→ 插件仓库）

2. Search for Existing Issues

2. 搜索现有问题

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
对于pup仓库：
bash
gh issue list \
  --repo DataDog/pup \
  --search "your search terms" \
  --limit 10
对于插件仓库：
bash
gh issue list \
  --repo DataDog/datadog-api-claude-plugin \
  --search "your search terms" \
  --limit 10

3. Create Issue

3. 创建问题

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"
对于pup仓库：
bash
gh issue create \
  --repo DataDog/pup \
  --title "Clear, concise title" \
  --body "Detailed description" \
  --label "bug" # 或 "enhancement", "documentation"
对于插件仓库：
bash
gh issue create \
  --repo DataDog/datadog-api-claude-plugin \
  --title "Clear, concise title" \
  --body "Detailed description" \
  --label "bug" # 或 "enhancement", "documentation", "agent"

Issue Body Template

问题正文模板

Use this template for comprehensive issue reports:
markdown
undefined
使用以下模板提交全面的问题报告：
markdown
undefined

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. [...]
  1. [第一步]
  2. [第二步]
  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]
  • 操作系统：[例如：macOS 14.1, Ubuntu 22.04]
  • Pup版本：[运行
    pup --version
    查看]
  • 插件版本：[来自plugin.json]
  • Claude Code版本：[如相关]

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]
undefined
[如果你有修复思路]
undefined

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"
✅ 优秀示例：
  • "logs agent: 时间格式文档错误"
  • "pup metrics query: --from标志忽略相对时间"
  • "Agent选择指南：缺少安全代理的决策树"
❌ 糟糕示例：
  • "它不工作"
  • "Bug"
  • "求助"

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
pup仓库：
  • bug
    - 功能无法正常工作
  • enhancement
    - 新功能或需求
  • documentation
    - 文档改进或补充
  • question
    - 需要更多信息
插件仓库：
  • bug
    - 功能无法正常工作
  • enhancement
    - 新功能或需求
  • documentation
    - 文档改进或补充
  • agent
    - 与特定代理行为相关
  • skill
    - 与技能相关
  • question
    - 需要更多信息

Examples

示例

Example 1: Filing a pup Bug

示例1：提交pup错误报告

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.
用户："pup logs search命令30秒后超时"
分析：这是pup CLI的问题（命令行为）
步骤：
  1. 搜索现有问题：
    gh issue list --repo DataDog/pup --search "timeout"
  2. 如果未找到，创建问题：
bash
gh issue create \
  --repo DataDog/pup \
  --title "pup logs search: 命令30秒后超时" \
  --body "## 描述
\`pup logs search\`命令在搜索大时间范围时30秒后超时。

Expected Behavior

预期行为

Should either complete the query or allow configurable timeout.
应完成查询或允许配置超时时间。

Actual Behavior

实际行为

Command fails with timeout error after 30 seconds.
命令30秒后因超时错误失败。

Steps to Reproduce

复现步骤

  1. Run: `pup logs search --query='*' --from='7d' --to='now'`
  2. Wait 30 seconds
  3. See timeout error
  1. 运行：`pup logs search --query='*' --from='7d' --to='now'`
  2. 等待30秒
  3. 看到超时错误

Environment

环境信息

  • OS: macOS 14.1
  • Pup version: 1.2.3
  • DD_SITE: datadoghq.com
  • 操作系统：macOS 14.1
  • Pup版本：1.2.3
  • DD_SITE：datadoghq.com

Error Message

错误信息

``` Error: request timeout after 30000ms ``` "
--label "bug"
undefined
``` Error: request timeout after 30000ms ``` "
--label "bug"
undefined

Example 2: Filing a Plugin Documentation Issue

示例2：提交插件文档问题

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.
用户："logs代理文档显示TypeScript示例而非pup命令"
分析：这是插件的问题（文档）
步骤：
  1. 搜索现有问题：
    gh issue list --repo DataDog/datadog-api-claude-plugin --search "TypeScript"
  2. 创建问题：
bash
gh issue create \
  --repo DataDog/datadog-api-claude-plugin \
  --title "logs agent: 文档中TypeScript示例已过时" \
  --body "## 描述
logs代理文档仍显示TypeScript/Node.js示例，而非pup CLI命令。

Location

位置

`agents/logs.md` lines 150-200
`agents/logs.md`第150-200行

Expected

预期

Should show pup CLI command examples like: ```bash pup logs search --query='*' --from='1h' ```
应显示pup CLI命令示例，例如： ```bash pup logs search --query='*' --from='1h' ```

Actual

实际

Shows TypeScript code with imports and API clients
显示带有导入和API客户端的TypeScript代码

Impact

影响

Confusing for users who expect pup CLI commands
对期望看到pup CLI命令的用户造成困惑

Files Affected

受影响文件

  • agents/logs.md
  • Possibly other agent files (need audit) "
    --label "documentation"
    --label "agent"
undefined
  • agents/logs.md
  • 可能其他代理文件（需要审核） "
    --label "documentation"
    --label "agent"
undefined

Example 3: Feature Request for Plugin

示例3：提交插件功能请求

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
用户："我们可以添加一个Datadog SLO报告的代理吗？"
分析：这是插件的功能增强需求（新代理）
bash
gh issue create \
  --repo DataDog/datadog-api-claude-plugin \
  --title "enhancement: 添加SLO报告代理" \
  --body "## 功能请求

Description

描述

Add a new agent focused on SLO reporting and analysis, separate from the SLO management agent.
添加一个专注于SLO报告和分析的新代理，与现有的SLO管理代理区分开。

Use Cases

使用场景

  • Generate SLO reports for stakeholders
  • Analyze SLO trends over time
  • Compare SLOs across services
  • 为利益相关者生成SLO报告
  • 分析SLO随时间的趋势
  • 跨服务比较SLO

Proposed Agent Capabilities

提议的代理功能

  • Query SLO history
  • Generate formatted reports
  • Calculate SLO burn rates
  • Identify at-risk SLOs
  • 查询SLO历史数据
  • 生成格式化报告
  • 计算SLO燃尽率
  • 识别风险SLO

Related Agents

相关代理

  • Current `slos.md` focuses on SLO CRUD operations
  • New agent would focus on analytics and reporting
  • 当前`slos.md`专注于SLO的增删改查操作
  • 新代理将专注于分析和报告

Priority

优先级

Medium - would improve SLO workflow "
--label "enhancement"
--label "agent"
undefined
中等——将改善SLO工作流程 "
--label "enhancement"
--label "agent"
undefined

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
如果问题创建失败：
  1. 检查网络连接
  2. 验证gh CLI已认证：
    gh auth status
  3. 检查仓库权限
  4. 向用户提供问题详情，让其手动提交

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
成功提交问题后：
markdown
✅ 问题已成功创建！

**仓库**：DataDog/[仓库名称]
**问题编号**：#123
**链接**：https://github.com/DataDog/[仓库名称]/issues/123
**标题**：[问题标题]

团队将审核你的问题并尽快回复。你可以：
- 通过上述链接跟踪问题
- 在问题下评论补充更多细节
- 订阅通知以获取更新

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
  1. 尽可能具体——包含确切的命令、错误信息、代理名称
  2. 提供上下文——你当时尝试完成什么目标？
  3. 包含环境详情——操作系统、版本、配置
  4. 一个报告对应一个问题——不要合并无关问题
  5. 先检查现有问题——避免重复提交
  6. 请耐心等待——维护人员会在有空时回复