Issue Writer

Issue Writer

Write issues that let a maintainer understand the problem, reproduce it when

applicable, and decide whether it matters without reading an implementation plan.

Workflow

• Inspect the relevant code, tests, documentation, and repository guidance. Do

not invent behavior, impact, versions, or reproduction results.

• Reduce the request to one problem. Split unrelated problems into separate

issues.

• Remove proposed fixes and implementation details. Preserve constraints and

observable desired behavior only when they clarify the problem.

• For a bug, build the smallest complete reproduction and verify that it still

demonstrates the reported behavior. For a non-bug change, state the concrete

limitation and why resolving it is important.

• Draft only the sections that add information, then edit for brevity.
• Return a draft unless the user explicitly asks to create or submit the issue.

Write for Maintainers

• Lead with the observed problem and its impact.
• Use a specific, problem-focused title. Describe what fails or is difficult,

not a technology or refactoring to adopt.

• Keep paragraphs short and omit background that does not change understanding

or reproduction.

• Use plain language for humans. Do not include agent instructions, exhaustive

task lists, review history, or commentary about how the issue was produced.

• Distinguish verified facts from uncertainty. Do not speculate about a root

cause.

• Do not add labels, priority, milestones, or assignees unless the user provides

them.

Prefer titles such as:

> Port forwarding restarts after it becomes ready

Avoid solution-shaped titles such as:

> Refactor port forwarding to use a new readiness mechanism

Reproduce Bugs

Make reproductions:

• Minimal: Remove every line, step, fixture, dependency, and input that is not

required to trigger the behavior.

• Complete: Include everything a maintainer needs to copy, run, and observe

the problem.

• Verifiable: Run the final reduced example and report the command and result.

Never claim that an untested example reproduces the problem.

Prefer synthetic inline configuration or data over external repositories,

archives, logs, or private application data. Include only relevant environment

details, such as Python, pytest, kind, kubectl, OS, and architecture versions.

Use language-labelled fenced code blocks. Include the complete traceback or

command output when it is relevant; place unusually long output in a

<details> block rather than truncating the useful frames.

Present Python examples in python-labelled code blocks. Do not wrap Python

code in a shell heredoc such as python3 <<'PY' ... PY; readers can infer that

the example should be run with Python. Use a bash block only for shell

commands.

If a minimal reproduction is relevant but unavailable, state that limitation

plainly instead of fabricating one.

Structure the Draft

Adapt the structure to the issue. Do not emit empty headings.

For a bug, usually include:

• A one-paragraph summary
• A minimal reproduction with the exact command
• Actual behavior, including the complete relevant error
• Expected behavior
• Relevant environment details

For an enhancement or maintenance issue, usually include:

• The current limitation or maintenance problem
• A concrete example or affected workflow
• Why it matters to users or maintainers
• Clear boundaries when needed to keep the issue focused

Do not add a “Proposed solution” section, name files to edit, prescribe an

architecture, or provide implementation steps. State the outcome that should be

possible only when it is necessary to explain the problem.

Final Check

Before returning the draft, verify:

• The title describes one problem rather than a solution.
• The opening explains what is wrong and why it matters.
• A bug reproduction is minimal, complete, and actually verified.
• A non-bug issue gives concrete justification.
• Expected behavior is observable without prescribing implementation.
• Every paragraph earns the maintainer's attention.