github-issues

Files (1)

• SKILL.md

SKILL.md (first lines)

# GitHub Issue Authoring

Turn a verified problem into a useful GitHub issue without inventing product decisions or implementation details

## Core Contract

- The user decides the issue's goal, scope, high-level direction, completion outcomes, and metadata
- Research facts before asking questions:
  - ask the user only for decisions evidence cannot answer
- Before drafting the final issue, confirm the goal, scope, any high-level direction, and observable completion outcomes
- Do not ask again about a decision the request already makes
- If a decision is still missing, interview before drafting:
  - never use a finished draft to obtain it
- Work on one viable issue at a time unless the user explicitly requests a batch
- Prefer an existing canonical issue over creating a duplicate
- Keep the issue detailed enough to act on, but leave detailed design and execution to the assignee
- Preserve uncertainty instead of converting it into a cause, impact, requirement, or owner

When triaging many findings, report all findings that should **not** become issues together first. Then discuss viable new issues one at a time

## Ticketability Gate

Before drafting a new issue, establish:
1. **Actual problem:** A current observable failure, gap, or missing behavior exists
2. **Impact:** Evidence establishes why it matters:
   - volume alone is not impact
3. **Current state:** The problem is not already fixed or only historical
4. **Ownership:** The proposed repository and subsystem own the affected boundary
5. **Evidence strength:** The title, context, and goal do not exceed what the evidence proves
6. **No duplicate:** No existing issue already owns the same outcome
7. **Right artifact:** A new issue is better than an evidence comment, telemetry cleanup, configuration correction, existing issue update, or no action

Do not recommend a new issue when the evidence shows only:
- an already-fixed defect
- an expected or correctly handled validation failure
- duplicate or noisy telemetry without a separate product failure
- stale, local, user-provided, or unsupported configuration
- one generic error group containing unrelated lower causes
- an existing canonical owner that only needs new evidence
- a product or workflow the user explicitly excluded

State the no-ticket disposition plainly and explain the better destination

## Research and Interview

Before asking the user:
- Read the current issue or planning source completely
- Inspect current source, docs, types, tests, logs, runs, and external evidence needed to establish behavior and ownership
- For an operational or reliability issue, inspect each available source that could prove or disprove the claim. This can include Slack, Sentry, service logs, run evidence, current source, and existing issues or PRs
- Do not inspect an irrelevant source just to complete a checklist
- Keep a short scratch record of the sources and time periods checked, unavailable evidence, and what the evidence establishes about scope and ownership. Put only material proof in the issue body
- Search titles and bodies in the proposed repository and in every repository that the evidence identifies as a plausible canonical or implementation owner
- Read every issue, PR, document, or discussion before proposing it as related work
- Distinguish current behavior from historical proposals, partial fixes, and stale evidence
- Establish whether grouped telemetry represents unique incidents, wrappers, polling amplification, or heterogeneous causes

Ask the user, one decision at a time, only when unresolved:
- What outcome the issue should require
- Which high-level implementation direction, if any, the author wants to record
- Which observable completion outcomes are intended
- Which owner, repository, and title prefix are correct when evidence does not settle them
- Whether the action should be a new issue, body update, evidence comment, title-only change, or no ticket
- Whether to assign, label, add to a project, create hierarchy, or synchronize a planning document

## Title

Follow the target repository's established convention. When bracketed ownership titles are used, prefer:

```text
[Product][Subsystem] <concise outcome>
```

- Use the proven owning boundary, not a suspected dependency
- Prefer an action or outcome over a vague topic
- Keep exact GitHub titles synchronized elsewhere only when that separate update is requested and approved

## Body Format

Use this default shape. Omit empty sections and unnecessary subsections

```markdown
## Context

<What is happening, why it matters, the affected boundary, and material unknowns.>

## Verified evidence

- <Direct observation or source link and exactly what it establishes>

## Goal

<High-level observable outcome supplied by the user or established by the agreed scope.>

## Implementation

TODO — the assignee will review the evidence and propose the implementation before coding.

## Done when

- <Agreed, observable completion outcome>

## Related work

- [<Issue or PR>](<url>) — <the exact overlap, dependency, distinction, or ownership boundary>

## Work that may be helpful

- [<Issue, PR, document, or code>](<url>) — <why it may help and its current status>
```

Formatting rules:
- Use short paragraphs, bullets, and small useful subsections instead of prose walls
- Keep the issue understandable without copying the full research record
- Put source links beside the claims they support
- Use `Verified evidence` only for claims actually verified
- Put material unknowns in Context or Evidence:
  - do not invent a separate section to fill space
- Omit `Related work` and `Work that may be helpful` when nothing qualifies
- Keep `Work that may be helpful` to the smallest useful set; do not use it to collect thematic or merely adjacent links

From OrestesK/pi, MIT.

More from OrestesK/pi