Report Skillpack Issue

Skill: Report a Skillpack Defect

<!--
SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

Issues filed against the skillpack are the maintainers' primary field telemetry. A defect you hit and route around silently gets hit by every other user's agent too. Filing takes two minutes; the report is more valuable than the workaround.

This skill follows the repository's agent-reported issue conventions (.github/ISSUE_TEMPLATE/agent-reported.yml): the [AGENT]: title prefix, the agent-reported label, a declared agent identity, and at most one issue per session.

Step 1: Confirm the defect is in the pack, not the environment

Re-read the suspect rule or skill file in full before reporting. Classify the defect:

• contradiction — two pack statements cannot both be followed.
• dead-reference — a cross-reference targets a file, section, or field that does not exist.
• unexecutable — an instruction cannot be carried out as written (missing input, impossible ordering, undefined term with no declared source).
• factual-error — a claim about a tool, flag, default, or format is wrong; verify against the tool's own source or help output first, and quote that verification in the report.
• environment-mismatch — the rule assumes something (paths, permissions, cluster shape) that the target environment class does not satisfy; report only when the mismatch looks general, not site-specific.
• missing-coverage — the pack gives no guidance for a component or situation it plainly should cover.

If the problem disappears on a careful re-read, or is specific to one site's configuration, do not file.

Step 2: Record your agent identity and the exact pack version

The report must state the driver model and the skills commit it was running (for example claude-opus-5, skills @ abc1234):

git rev-parse --short HEAD

Run that from the repository root. In every command in this skill, replace placeholders BEFORE running and never leave angle brackets in a shell line: <...> parses as redirection and can truncate files.

If the pack was vendored without git history, record the release or image tag it came from. A report that cannot say which version it observed cannot be triaged.

Step 3: Sanitize

The issue lands in a public repository. Nothing you emit, in the title, the body, a comment, a search term, or a version string, may contain: Quote pack text from the public repository freely (not from a locally modified or vendored copy, which may carry private details); describe your environment only in generic terms (GPU class, backend, harness). When in doubt, leave it out — the rule file, version, and defect class are usually enough to reproduce.

Step 4: Check for an existing report

Search titles AND bodies in one bounded, body-inclusive query. A labeled query adds nothing (--label ANDs into the search, so it is a strict subset of the unlabeled one), the default limit of 30 hides real matches for common keys such as README.md, and --json returns bodies inline instead of costing one gh issue view per hit. Use the bare filename as the search term (no backticks):

gh issue list --repo ai-dynamo/dynamo --state all --limit 100 --json number,title,body \
  --search 'benchmark-isolation.md in:title,body'

Review every hit whose title starts with [AGENT]: or whose body mentions the same file and defect class, and read each candidate's comments too, because confirmations of an existing defect are filed as comments (below) and do not appear in title or body search:

ISSUE_NUMBER=123
gh issue view "$ISSUE_NUMBER" --repo ai-dynamo/dynamo --comments

If a matching issue exists, do not file a duplicate: draft the same body (step 5), route it through step 6 with the target recorded as "comment on #123", and on approval run the command with BOTH variables assigned in the same shell invocation (nothing persists between harness shell calls):

ISSUE_NUMBER=123
BODY_FILE=$EXP_ROOT/analysis/skillpack-issue-drafts/001-perf-analyzer-body.md
gh issue comment "$ISSUE_NUMBER" --repo ai-dynamo/dynamo --body-file "$BODY_FILE"

File at most one new issue per session; if the session surfaced several defects, put the most impactful one in the issue and list the rest briefly in its body.

Step 5: Draft the issue

Title: [AGENT]: <file path relative to repo root>: <one-line defect>.

Write the body with a file-writing tool, never by echoing it through a shell, to a run-scoped path that names the invoking role, because several roles can hit defects in the same engagement window: inside an engagement <EXP_ROOT>/analysis/skillpack-issue-drafts/NNN-<role>-body.md (NNN increasing), otherwise ./skillpack-issue-drafts/NNN-<role>-body.md under the current working directory. Never use a shared fixed path such as /tmp, where another role's write can replace an approved body before it is submitted. Delete the draft file once its issue or comment is filed, so a later invocation cannot inherit a stale body. Follow the agent-reported template's structure:

### Agent identity

<driver model>, skills @ <commit or tag>

### What the instructions said vs what you verified

Defect class: <contradiction | dead-reference | unexecutable | factual-error | environment-mismatch | missing-coverage>
Location: <file path and the section heading or quoted sentence>

<exact quote(s) of what the pack says; for a contradiction, quote both sides>

<the generic, sanitized observation that contradicts it, how it was verified, and what the agent could not do,
did wrong, or had to route around>

### Suggested correction

<the wording you would have needed; omit the section if unsure>