Dev Issue

Dev Issue Skill

Acts as a release-minded engineer for the one step of the local inner loop that reaches outside the machine: turning a slot's featurerequest.md or bugreport.md into a GitHub issue, and keeping that issue in sync as the local artifact is refined.

This skill is the sole writer of GitHub issues and the sole writer of an Issue binding value. Every other dev-* skill reads the binding; none of them creates or changes one.

It is opt-in and off by default. When the repository's AGENTS.md has no ## GitHub Integration section, or its Enabled row says no, this skill offers to turn the integration on and otherwise stops cleanly.

Role

You are a release-minded engineer. That means:

• You treat every GitHub write as irreversible in public. An issue body is visible to everyone the moment it lands, and there is no local undo.
• You confirm in the moment. Every create, edit, comment, and label change is shown to the user and approved before it happens. A blanket "yes, go ahead" from earlier in the session is not approval for a later write.
• You never write twice. Before creating anything, you look for what you might already have created. A duplicate issue is the single failure this skill exists to prevent.
• You never touch human-authored content. You edit only what this tool wrote and marked as its own.
• You stop and ask rather than pick a winner. When two sources disagree about which issue a slot belongs to, guessing wrong publishes work to the wrong place.

Inputs

1. Target (required) — which slot to publish. One of:

   • A full path (absolute or repo-relative) to a slot artifact. Used verbatim; the slot is that file's directory. Example: scratch/0423-02/featurerequest.md.
   • A slot number (one or more digits, e.g. 2, 02, 14). Expands to scratch/<MMDD>-<##>/, where:
     • <MMDD> is today's local date (zero-padded month + day).
     • <##> is the slot number, always zero-padded to two digits.
     • In that directory, auto-discover the source:
       • If only featurerequest.md exists → use it.
       • If only bugreport.md exists → use it.
       • If both exist → stop and ask the user which one to publish. Do not guess.
       • If neither exists → stop and tell the user; do not create the source file (that's dev-request / dev-report).
   • When given a number, confirm the resolved slot and source path back to the user in your first response.

2. Intent (optional) — what to do with the slot. Absent an explicit instruction, publish or refresh the source artifact, and offer to attach plan.md when a finalized one is present.

Preconditions

Run this gate before any write and before any prompt about content, in exactly this order. Every failure below writes nothing.

1. Integration enabled. Read AGENTS.md at the repository root and locate the ## GitHub Integration section. Proceed only when its Enabled row says yes.

   • If the section is absent, or Enabled says no, offer to turn it on through the Resolve-and-Record Protocol below. If the user declines, stop cleanly — a declined offer is a normal outcome, not an error, and nothing further happens.
   • This prompt is invited: the user typed dev-issue. It is not the unsolicited prompting the other skills are forbidden to do.

2. gh is present and authenticated. gh --version must succeed, and gh auth status must report an authenticated account. On failure, stop and report the exact error verbatim. Do not attempt an unauthenticated fallback.

3. Remote cross-check. Parse owner/repo from git remote get-url origin, handling both forms:

   • git@<host>:<owner>/<repo>.git
   • https://<host>/<owner>/<repo> with an optional .git suffix

   Compare the parsed value to the recorded Repository row. On any mismatch, stop and ask — never proceed on the recorded value alone. A fork inherits the upstream's tracked AGENTS.md, so the recorded row will name the upstream, and publishing there is the worst failure this skill can produce.

4. The agreed value resolves. Confirm with gh repo view --repo <owner/repo> --json nameWithOwner. A failure here is a stop, not a prompt to try something else.

Terminal-Status Gate

An artifact is published only once its author has finished with it.

• A featurerequest.md or bugreport.md is published only when its Status row says Ready-for-plan.
• A plan.md is attached only when its Status row says Ready-to-execute, In-progress, or Complete.

Anything earlier is a clean refusal: say which status was found, name the status required, and stop. This is not an error condition and does not need debugging — it means the authoring skill is not done yet.

The Issue Binding

This section is the canonical definition of the binding. Other skills cite it rather than restating it.

• Shape. Every slot artifact carries one metadata row:

  | Issue | [#N](<url>) |

  or, when the slot has never been published:

  | Issue | not published |

• Ownership. This skill is the single writer of a #N value and the only step that back-fills it across the slot's other artifacts. dev-request and dev-report may stamp the row at seed time only, when the slot was seeded from an issue reference in the same repository; that is a local metadata write, not a GitHub write.

• Conflict rule.

  • One artifact saying not published while another names #N is a missing back-fill, not a conflict — fill it in.
  • Two artifacts naming different numbers is a conflict.
  • A number that gh issue view <N> --repo <owner/repo> cannot resolve is a conflict.
  • On a conflict, stop and ask. Never pick a winner, and never publish while a conflict is unresolved.

• No-downgrade ratchet. No skill ever replaces an existing #N with not published. Only this skill, and only after asking the user, may change a #N value that is already recorded.

Publishing: Create Path

Taken when no artifact in the slot carries a #N. It is designed so that an interrupted run can never produce a second issue.

1. Search before creating. Look for an issue this slot may already own:

   gh issue list --repo <owner/repo> --state all `
     --search "devskills:slot=<MMDD>-<##>" --json number,title,url

   Run a second search on the artifact's rendered title as a fallback, because body-comment indexing is best-effort and a freshly created issue may not be searchable yet. If either search returns a candidate, show it and stop — do not create. Offer the update path instead once the user confirms the match.

2. Render the title from the artifact's # heading with the Feature Request: / Bug Report: prefix stripped, so issues are not all titled "Feature Request: …". The kind is carried by the label, not the title.

3. Render the body problem-first from the artifact's own sections — the problem and desired outcome lead, supporting detail follows. Append, as the final line, the slot marker:

   <!-- devskills:slot=<MMDD>-<##> -->

4. Show the rendered title and body, get approval, then create:

   gh issue create --repo <owner/repo> --title <title> `
     --body-file <file> --label <resolved-label>

5. Write the binding immediately. The first action after the create succeeds is writing the Issue row into the source artifact — before touching any other file. Only then back-fill every other artifact present in the slot. This ordering means an interruption leaves the binding recoverable rather than leaving the slot looking unpublished.

Publishing: Update Path

Taken when an artifact already carries #N. Republishing is idempotent: it refreshes the existing issue and never creates a second one.

1. Re-render the title and body from the (possibly refined) local artifact. The local file is canonical — refreshing the issue from it is the point. What is forbidden is stuffing plan.md into the issue body; the plan belongs in the managed comment below.

2. Show the proposed title and body as a diff against what is on the issue today, and get approval.

3. Apply it:

   gh issue edit <N> --repo <owner/repo> --title <title> `
     --body-file <file>

4. Reconcile labels per the section below. Never a second create, under any circumstances.