issue-authoring

Issue Authoring

Use this skill to prepare issue-ready work before execution starts. Keep the skill concise and treat the repository docs as the canonical source for the full contract and schema. The canonical source bundle lives in this repository; install copies in the agent-specific skill directory your runtime reads.

Stable Phases

Use two stable phases:

1. Intake and Clarification — inspect relevant context, identify ambiguity, run a secondary critique or explicit self-critique, and ask only the questions that block safe issue drafting. Keep clarification bounded; use the repository-local issueAuthoring.maxClarificationRounds value when available, otherwise default to 3 rounds. Under-clarification stop rule: if, after bounded clarification, you still cannot name the concrete surface to edit or an objective verification for a candidate task, route it to needs-decision or ask — do not publish a confidently-vague ready issue. Reliability over speed.
2. Decompose and Draft — restate the request in implementation terms, split it into atomic tasks, classify readiness, reuse existing issues when safe, and draft the smallest issue shape that preserves dependencies and reviewability.

Preserve low-readiness work in stable buckets: ready, deferred, needs-decision, blocked-by-human, and out-of-scope.

Workflow

1. Read the bundled contract in references/contract.md.
2. Reuse or extend an existing issue before creating a new one — but never edit the body of an actively-claimed or open-PR issue (its claimed agent will not pick the change up); cover it with a follow-up issue instead. See the contract's claim-state precondition.
3. Choose the smallest safe output shape:
   • orphan issue for one ready autonomous task only when the target repository discovers orphans (issue-scope: roadmap-first, the default, via the orphan fallback, or orphan-first) and any configured orphan-first-policy approval step can be completed after drafting
   • roadmap plus sub-issues for multi-task or multi-session work
   • stable non-ready buckets for deferred, needs-decision, blocked-by-human, or out-of-scope work
4. Prefix-first: resolve the target repository's marker prefix before emitting any authoring marker — roadmap-id, blocked-by, autopilot-suitability, or effort. Use the prefix documented by the target repository's onboarding or IDD docs, and ask the user instead of guessing when the prefix is not discoverable. Never default to this source repository's idd-skill prefix in an installed bundle.
5. Keep dependencies machine-readable and minimal:
   • roadmap identity via <!-- <marker-prefix>-roadmap-id: ... -->
   • active child issues via roadmap task-list links
   • issue-to-issue dependencies via Blocked by #NNN
   • sequential roadmap dependencies via <!-- <marker-prefix>-blocked-by: ... --> only when a separate roadmap must close first
   • keep independent sibling work in roadmap task lists unless a true correctness, availability, or ordering constraint requires a dependency edge
6. Before publishing a ready orphan, roadmap, or child body, run the audit-authored-issue linter against it as the mechanical pre-publish gate — see Mechanical pre-publish gate in the bundled contract, including the manual fallback for instructions-only installs with no helper runtime. Resolve every reported failure before treating the issue as ready. Before newly publishing a body into the needs-decision or blocked-by-human bucket instead, also run the linter, passing --expect-bucket <needs-decision|blocked-by-human> (choose the one matching value) — the same gate section's --expect-bucket flag requires the matching authoring-bucket marker for that publish, closing the gap where a non-ready body would otherwise never be audited at all.
7. Publish each ready drafted body directly under the authoring hold once it passes the mechanical gate (step 6) and the critique pass (the Intake and Clarification phase above) — no separate publish approval is needed. Only skip publishing when the current request explicitly asked for a preview instead. Manage the authoring label for each created or updated issue:
   • resolve issueAuthoring.authoringLabelName, defaulting to status:authoring
   • create the label with gh label create before first use when the target repository does not already have it
   • treat label creation or application failure as a publishing blocker
   • apply the label before updating an existing issue
   • acquire per-target ownership before editing an existing issue or roadmap; the shared label is a claim-suppression lock, not an owner token. Follow the append-only owner-marker and re-read protocol in references/workflow-boundary.md and stop without editing when ownership or the target snapshot conflicts
   • for a new Stage 1 set, generate one opaque set ID and reuse it in every owner marker for that set; when resuming an interrupted set, recover and verify its persisted set ID from the exact trusted owner markers and reuse it instead of generating a replacement; never infer set membership from the label alone
   • when a set includes a parent roadmap, publish a valid roadmap shell under the authoring hold before any child; acquire and verify that roadmap as the set anchor, leaving its ## Tracks list empty only until child issue numbers exist. Without a parent roadmap, use the designated lead target as the anchor
   • acquire and verify the set anchor before publishing or acquiring any child; do not acquire children independently, and stop all edits if any target cannot join that anchor's verified set
   • before each child acquisition or resume, append and verify a same-owner anchor heartbeat, re-fetch the anchor's paginated log, then append the child marker and immediately re-fetch both anchor and child. Stop with the label in place if anchor ownership changed between those reads
   • persist the anchor's canonical repository/issue identity in every owner marker for the set; the anchor marker points to itself, and a resume must stop if the interrupted set's anchor cannot be proven
   • immediately before every Stage 1 body or relationship edit, re-fetch both the edited target and the set anchor; require each target's expected owner token independently, plus the same set, anchor, and owning session, and require an unchanged expected target snapshot before editing
   • immediately before that edit, renew both generations with a trusted same-owner-per-target heartbeat marker (one marker when target and anchor coincide), re-fetch and verify both, and stop if renewal or ownership verification fails
   • create new issues only through a capability-checked publication command that applies the authoring label atomically and carries an exact hidden publication token for target, anchor, set, and session; if that operation is unavailable, stop before creating the issue — never intentionally create an unlabeled issue
   • the hidden publication token is this exact HTML-first body line: