To issues clearly

Turn a plan, bug report, audit finding, or PRD into live GitHub issues that explain the outcome clearly enough for another person to implement and verify.

The tracker is the publication surface. Draft in the conversation, then create or edit the issue directly with GitHub. The skill supplies judgment and a repeatable shape; GitHub supplies the issue number, labels, and relationships.

Choose the issue shape before writing

The title and body depend on what the source is asking for. Do not force every issue into a defect-shaped template.

• Decision: a product, policy, workflow, or boundary choice is unresolved. Use an imperative title such as Decide where customers book online and the decision template below.
• Change, fix, or capability: the issue exists to make the product do something. Use an imperative desired-outcome title such as Show seller-linked colour photos in the storefront before vision processing completes or Keep a failed upload available for retry.
• Reported defect or contract failure: the issue exists to record and investigate what is wrong now. Use the observed-action-and-consequence title shape below.
• Wide refactor: one mechanical change has a cross-codebase blast radius. Use the expand/migrate/contract sequence below.

Classify first. A decision issue asks people to choose; an implementation issue tells someone what behavior to build; a defect issue says what behavior is wrong now.

Titles that survive a cold read