issue-reporting

Files (1)

• SKILL.md

SKILL.md (first lines)

# Issue reporting

Draft only when a report or follow-up is warranted and the target project's AI policy permits it.
Use the project and problem from the conversation; ask for the target repository only when it cannot be identified.
Assume jyn is writing to another maintainer.
Transfer the evidence they need without relying on shared context.
Use the project's applicable channel and template for a bug report, support question, feature request, or design discussion.
Describe the user workflow, limitation, and existing workaround rather than forcing every request into a bug report.

## Gather the authoritative inputs

Before drafting any upstream text, check the target project's current contribution instructions and linked policies for AI, LLM, or agent rules.
Check which rules apply to issue bodies, comments, drafting, disclosure, and agent submission.
Permission to generate code does not imply permission to write posts.
If the project prohibits AI-written reports or comments, do not draft, rewrite, or provide copy-ready text for them, even with disclosure or human submission.
Explain the restriction and cite the policy; continue only permitted work, such as investigation and raw evidence collection for the user to write up.
If the policy's applicability is unclear, resolve it before drafting.
If no policy is found, state where you checked outside the report rather than claiming permission.
Apply project-specific disclosure requirements instead of this skill's default wording when they differ.

Before drafting, search the target project's open and closed issues and pull requests for existing reports or fixes.
Search by the visible failure, relevant component, and distinctive error messages or function names.
Read plausible matches, including relevant comments, and compare their reproductions and affected versions with the current evidence.
When a matching report exists, read its resolution and relevant maintainer comments before proposing further communication.
Recommend a follow-up there rather than a duplicate only when new evidence could change the diagnosis, resolution, or requested action.
Reproducing a known unsupported configuration on newer versions does not, by itself, justify another comment.
Link related reports and explain the connection when they describe a different failure.
If search is unavailable or finds no match, state that limit outside the report; do not claim the bug has never been reported.

Before attributing the problem upstream or proposing a change, trace the following chain:

1. State the observed problem and required behavior separately from any preferred mechanism.
   Identify which constraints are governing requirements and which follow from a downstream design choice, including who chose it.
   A directory layout chosen for a draft design is not an intrinsic upstream requirement.
   A heading or the surrounding explanation can establish whose choice it is; do not add a disclaimer when that is already clear.
2. Check plausible existing solutions in the supported configuration and public APIs, and state what each workaround actually solves.
   Distinguish unchanged-tool capabilities from approaches requiring consumer patches, downstream forks, or upstream adoption.
   An existing library API does not by itself establish that an unmodified CLI exposes the same capability.
   State those adoption and maintenance costs in the main explanation, not only in collapsed test details.
3. Tie any remaining insufficiency to a concrete requirement and evidence, not an assumed side effect.
   If it follows from a revisable downstream design choice, consider changing that choice rather than treating it as a constraint on upstream.
   If that evidence is missing, use a small authorized check or ask a bounded question; do not turn uncertainty into a defect claim.
4. If a change is still needed, identify the minimum upstream change that addresses the remaining problem, not the original problem already solved.
   A working but costly workaround supports a simplification request, not a claim that upstream changes are required for correctness.
   Compare its downstream cost with the proposed upstream work and maintenance.

Do not require a fix proposal to report an unresolved failure; preserve uncertainty about its cause.

If the reproduction depends on an explicitly unsupported configuration, identify who selects that configuration.
Recommend correcting it at its owner rather than reporting the known incompatibility again.
This does not authorize implementing the correction.

If existing guidance resolves the problem, explain the applicable resolution and stop.
Do not draft a report or comment merely to satisfy this skill.
The writing, tightening, and delivery requirements apply only when a report or follow-up is warranted.

1. Read the target project's `CONTRIBUTING.md` and current issue template before
   drafting. Follow its issue-reporting requirements, including instructions it
   links to; reading them alone is not sufficient. If `CONTRIBUTING.md` is absent,
   check the project's documented contribution instructions. Distinguish reporting
   requirements from PR-only requirements; drafting a report does not authorize
   fixes or running unrelated PR checks. For remote source, shallow-clone the
   repository into a temporary directory. Use the applicable issue or discussion template,
   retaining its headings, order, and required fields; omit template comments and
   metadata. If no template is available, tell the user.
   Follow the project's disclosure placement; otherwise put this skill's default disclosure before the first template heading.
   Preserve the template's heading order and required fields.
   For a bug report, lead with the installation or invocation and visible failure; include reproduction, expected behavior, and output.
2. Incorporate the user's latest corrections and reported experiments.
   Track whether each result came from the user, an agent-run check, or source inspection.
   Distinguish jyn's goals and reported experience from verification evidence.
   Describe agent-run checks through their commands, reproducers, and captured results; do not turn them into claims that jyn personally ran them.
   Do not present proposed or unverified steps as completed checks.
   A matching source defect does not prove a runtime reproduction.
   Do not invent commands, full logs, environment details, or a successful test.
   Capture relevant local patches, forks, nonstandard configuration, and previous attempts with their results.
   Include a working control when it narrows the failure: for example, one picker order fails while the reverse order works.
3. Record the installed version, installation source, and relevant runtime dependencies.
   Name the source precisely, such as a project's GitHub release asset, a distribution package, or a local source build.
   Do not use "official" as a substitute for provenance; state when the source is unknown.
   If the project requests testing the development version, check that requirement and report
   whether it was met. If testing needs a different build, prefer an isolated
   standalone directory over replacing the installed program. Follow
   `dependency-review` for a requested build or update; do not silently expand
   drafting into installation.
4. Inspect relevant source when the report makes a source-based claim. For GitHub,
   resolve the inspected revision's full commit hash and use a permalink with
   precise line anchors; never use branch names or abbreviated hashes in code
   links. For other hosts, use an equivalent stable, revision-specific link when
   available. Omit source links when the report makes no source-based claim.

## Write the report

Organize the report around the maintainer's decision, not the investigation's chronology.
Read the title and body together; preserve the specific request rather than replacing it with a broader problem description.
For a change proposal, name the proposed change before the workaround, unless the required template specifies otherwise.
Before opening any collapsed details, the maintainer should understand the failure, why it matters, the requested outcome,
and why obvious workarounds fall short.
Use supporting details to verify those points, not to introduce them.
When an existing supported approach might meet the need, ask about it without replacing a specific proposal with a general request for advice.
Do not imply that such an approach exists or ask the maintainer to design one unless that is the intended request.
A maintainer can recommend keeping the solution downstream without also supplying an alternative.
Follow required template fields rather than adding duplicate requests.
The [discussion contrast](../holistic-writing/references/reading-examples.md#state-the-request-before-the-workaround) shows how these choices affect reading.

- Use complete sentences and ordinary issue prose, even when conversation uses IRC style.
  State jyn's goals and known experience accurately, without imitating her conversational voice or inventing familiarity, use, or personal verification.
  Distinguish intended use from current use: "I want to use ..." does not establish "I use ...".
  For a bug report, choose a title that names the general failure rather than one tool that exposes it:
  "user-local Python" rather than "mise Python"; name mise in the body.
  Include facts that help the maintainer reproduce, diagnose, or fix the failure;
  omit investigation narration and redundant checks when a working control
  already establishes the relevant difference.
- Explain the practical need with a concrete user workflow, not just a desired mechanism.
  When the motivation or upstream responsibility is not obvious, add a motivation section or use the corresponding template field.
  Introduce downstream tools and their roles before relying on them for context.
  Explain the property that makes a technical term relevant to the argument, not just the term itself.
  For example, say that all linked worktrees share Git's common directory, rather than only naming `common_dir()`.
  When execution boundaries matter, identify where processes and data live; "guest" alone does not distinguish a VM from a container.

From jyn514/dotfiles, Unlicense.

More from jyn514/dotfiles