issue-reporting

Files (1)

• SKILL.md

SKILL.md (first lines)

# Issue reporting

Write for another maintainer who was not in the investigation.
Use the established project and problem; ask which repository only when you cannot identify it.

## Check permission and form

Read the project's current contribution instructions, reporting template, and linked policies.
Follow reporting requirements, not unrelated PR checks.
For remote source, shallow-clone into a temporary directory.
Tell jyn if no template is available.

Treat each information item and check requested by upstream reporting instructions and the selected template as required by default.
Before finishing, satisfy each item, explicitly explain why it does not apply to this case, or ask jyn for guidance on the unresolved requirement.
Missing tools, access, authorization, or time do not make an item inapplicable.

Check AI rules for drafting, comments, disclosure, and submission—not just code generation.
If AI-written posts are prohibited, do not draft, rewrite, or supply copy-ready text, even for human submission or with disclosure.
Cite the restriction and continue only with permitted work, such as raw evidence collection.
Restrictions on drafting or submission do not waive investigative work that remains permitted.
Resolve unclear applicability before drafting.
If no policy is found, tell jyn where you checked outside the report; do not claim permission.

Retain the template's headings, order, required text, and fields; omit comments and metadata.
Follow project-specific disclosure rules.
Otherwise, put this exact disclosure before the first template heading:

`🤖 this issue description was generated by an LLM 🤖`

Leave disclosure of later human edits to jyn.

## Decide what needs an upstream response

Choose a bug report, support question, feature request, or design discussion to fit the request.
An unresolved failure needs no diagnosis or fix proposal.

Search open and closed issues and pull requests for the failure, component, and distinctive errors or function names.
Compare plausible matches' reproductions and versions; read resolutions and maintainer comments.
Recommend a follow-up only with new evidence that could change the diagnosis, resolution, or requested action.
Link related but different failures and explain the connection.
State unavailable or unsuccessful search outside the report, not as a claim that nobody reported the problem.

### Does the workaround meet the outcome?

1. **What must work?** Separate required behavior from the preferred mechanism and downstream design choices; identify who chose those constraints.
2. **What already works?** Check supported configurations and public APIs; what does each workaround solve?
   Distinguish unchanged-tool capabilities from consumer patches, downstream forks, and upstream adoption.
3. **What remains?** Tie insufficiencies to requirements and evidence.
   Reconsider revisable downstream choices; resolve missing facts with a small authorized check or bounded question.

For example, suppose a CLI stores its database beside other repository metadata.
Linked worktrees already share it, but allowing a sandboxed CLI to write there also grants access to unrelated files.
A wrapper can move the database into a dedicated directory after setup, at the cost of recurring setup code.
If the request is to use that dedicated directory by default, sharing already works; the remaining request concerns access and setup cost.
A library API for choosing another path is not a solution for the unchanged CLI if using it requires a fork.
Ask for the default change and compare its maintenance cost with the wrapper's, rather than claiming sharing is impossible or replacing the proposal with a documentation suggestion.

Stop when existing guidance satisfies the requested outcome, not merely when a workaround makes the task possible.
If an explicitly unsupported configuration causes the failure, recommend correction at its owner rather than reporting the known incompatibility again.
This does not authorize implementing the correction.
Otherwise, request the minimum upstream change, if needed, and compare its work and maintenance cost with the downstream workaround's.

## Gather evidence

Use jyn's latest corrections and experiments.
Distinguish jyn's reports, agent-run checks, and source inspection.
Give commands and captured results for agent checks; never say jyn ran them or invent checks, logs, or environment details.
Include relevant patches, forks, nonstandard configuration, and prior attempts with their results.

For an unperformed runtime comparison, state the limit and any supported source-based expectation separately.
For example, if the development source still rejects the failing input, a comparison field might say:
“The agent did not run the development build. Its source still rejects empty device names, so I expect the same failure for that input.”
The expectation comes from source inspection, not a runtime result.

Attempt tests and diagnostic collectors required by the reporting instructions or needed to support the report’s conclusions.
Check their effects and run them within existing authorization, even if you suspect another cause.
If a necessary check cannot run, stop the work that depends on it and ask jyn for guidance.
Explain the exact check, what blocks it, why its result matters, and the smallest available way forward.
Continue independent work while waiting.
Merely marking the check “unverified” does not satisfy this requirement.

### Reproduction

Reduce to the smallest verified operation retaining the failure; keep the original application when its behavior matters.
Remove unrelated setup and update prerequisites accordingly.
Include useful working controls: one picker order failing while the reverse works can replace redundant checks.

Give the installation or invocation, relevant inputs and configuration, and point of failure.
Include cursor position and keystrokes when relevant.
Use numbered steps for multiple actions or when required by the template.
For machine-specific identifiers, give a discovery command and explain which result to select.
Distinguish tested steps from proposals and runnable reproducers from illustrations with placeholders or omitted setup.

Name required hardware, unavailable inputs, or inaccessible infrastructure; distinguish the observed failure from any missing portable or minimized reproducer.
Include useful failing artifacts even before minimization, and screenshots for visual failures.

### Installation and source

Record versions, runtime dependencies, and precise installation provenance: a GitHub release asset, distribution package, or local source build, not “official.”
Mark unknowns explicitly.
For required latest-version checks, compare running and installed versions with current release or package metadata before proposing an upgrade; an already-current installation needs none.
Report whether required development-build checks were met.
Task-local installations and builds needed for reporting checks are allowed without separate approval.
Use disposable storage for the installed software, installer state, and caches.
Do not change global state, including shared installations, default toolchains, or persistent user configuration, without explicit authorization.
Use `dependency-review` for builds or updates.
Include full development hashes, the tested invocation, and standalone build/resource paths and environment variables so reproduction does not silently use installed catalogs.

Inspect source for source-based claims.
When attribution matters, compare the patched build's failing path with upstream and identify the relevant patch.
For GitHub, link precise lines at the full inspected commit hash, never a branch or abbreviated hash.
On other hosts, use equivalent stable revision-specific links when available.
Omit source links without source-based claims.

## Write for the maintainer's decision

For a new report or substantial revision, use the [shared editorial pass](../holistic-writing/references/editorial-pass.md) for explanation, request framing, factual fidelity, and main versus supporting detail.
For bounded corrections, check the affected passage, claims, template fields, and links; repeat the whole pass only when the explanation or request changes.

From jyn514/dotfiles, Unlicense.

More from jyn514/dotfiles