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; for an interactive choice, the question blocks publishing, so it is asked (see Human-dependency isolation). 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 for an interactive choice ask first under Human-dependency isolation — 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
   • for every hard edge, name the producer output, the blocked operation or criterion, and its evidence; check the counterfactual with other valid prerequisites retained, then verify the set keeps independent siblings and natural cohesion. See the contract for the unchanged packet fields and worked examples.
6. Before the completed-draft adversarial review, verify material factual claims that justify the draft's scope or design against current sources: repository behavior against current code and docs; issue or pull-request status and prior decisions against live GitHub records; and runtime observations under the existing artifact-citation rule. Correct, qualify, or remove any such unsupported claim, and put support in the review packet's existing evidence array. Route a materially unresolved claim through the existing uncertainty and human-dependency rules: needs-decision for unresolved product, policy, or design choices, and blocked-by-human when verification waits on a person, credential, asset, or outside system. The packet schema stays unchanged. This check responds to the factual-history error reported in issue #4566, which concerns issue #3838 and issue #1019. Then run the completed-draft adversarial review on each completed roadmap, child, or orphan draft. This is not the Intake critique above. The packet, checklist, mode table, failure stop, wait ceiling, and no-mutation boundary are normative in Completed-draft adversarial review. Send only the exact title and body plus that bounded packet. Resolve idd-issue-authoring-delegate when a helper runtime can run it; the helper does not invoke the command. If the resolver cannot be run, or usable is false, use the agent-native reviewer or a structured self-critique. That is not a failed review. When usable is true, the mode is fallback (default), combined, on-success, or never; union findings when both mechanisms run. A missing command, non-zero exit, timeout, cancellation, or unreadable findings is a failure only after usable: true. A readable empty list is clean. If no mechanism that ran returns a readable list, do not publish the target: do not create it, update its body, change its label, or append a marker for it. An existing held issue keeps its label and previous body. The drafts go into a carrier marked Review: not reviewed (step 8), unless they already sit in one or one of step 8's two exceptions applies. The reviewer returns findings only. Prefer a non-context-inheriting reviewer; issue #3448 records why a context-inheriting no-mutation dispatch can still publish. Bound the wait with issueAuthoring.adversarialReview.waitCeiling (default PT20M) using the caller's own wait and cleanup, and do not wrap the command in a timeout utility. Dispose of every finding. Keep a findings ledger in the session scratchpad, never in the repository, and send each rejected finding that has evidence as a previously rejected: string in the packet's evidence array (carry-forward rule). Review the revised draft again before the linter whenever that revision changes more than wording, including acceptance criteria, candidate files, dependency edges, roadmap task-list or relationship wiring, scope or the proposed change, or the readiness bucket (Disposition). Wording-only edits do not start another review. Audit every revised body before publication. A roadmap shell may be reviewed and published with an empty ## Tracks list. Review each child before publishing it. Review the parent again when real child numbers are written into ## Tracks, then audit that edit before saving it.
7. Before publishing a ready orphan, roadmap, or child body, or a draft carrier (--shape carrier), 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; a carrier is never published without that check, and it has no manual fallback (step 8's second exception applies). 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. For every needs-decision lint — initial publication, held-body re-lint, and Stage 2 — pass --expect-bucket needs-decision and both configured labels.
8. Publish each ready, needs-decision, or blocked-by-human body directly under the authoring hold once the completed-draft review (step 6) and then the mechanical gate (step 7) have passed. The Intake critique stays the pre-draft pass above and does not replace step 6. No separate publish approval is needed. A reviewed draft does not end in local files only. When its final shape cannot be published under the hold now (the command cannot create it yet, such as a child whose set anchor is not published and held, or the final form waits on something else), publish a draft carrier with publish-authoring-hold --shape carrier (run it with --apply; the default is a dry run), as Draft carrier defines. A preview request also publishes a carrier, and the drafts are shown in the reply too. When authoring stops before the review completes on a planned stop (context pressure, or the user's instruction to stop), or when the review fails or cannot finish, the target is not published; its drafts go into a carrier marked Review: not reviewed (drafts already in a carrier stay there). Two exceptions keep the drafts local: the user explicitly says not to publish (an instruction not to create any issue, not a request to see the drafts first; the final message says that the drafts are not durable and gives their local paths), or the carrier cannot be published either (no helper runtime, issueAuthoring.journalIssue unset, or a failure before the create; the final message says the same and asks the user where to keep the drafts). A choice that the interactive rule in Human-dependency isolation holds unpublished is a pending question, not a reviewed draft. 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
   • for a review-needs-decision follow-up, see the narrow auto-release exception in the contract for its extra label and release rules
   • 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 (or reuse one — see the heartbeat-coalescing rule below), 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
   • Heartbeat coalescing (issueAuthoring.heartbeatCoalesceWindow, default PT2M): before appending a heartbeat, replay the target's paginated log; reuse the latest trusted marker instead of appending when it is the same owner/set/session, its mode is acquire/bootstrap/resume/heartbeat, it is younger than the window, and its body-sha256 matches the just-fetched body — re-fetch and verify the reused marker exactly as a fresh one. This window never applies to acquire, bootstrap, resume, release, release-guard, or release-complete appends themselves — only a heartbeat append may be skipped
   • 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; reuse applies here too), 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 (a carrier cannot be created either, so the second exception above applies) — never intentionally create an unlabeled issue. That command is idd-publish-authoring-hold (node scripts/publish-authoring-hold.mjs in this source repository). It publishes one issue per call: an orphan (the default), a draft carrier (--shape carrier), a roadmap shell (--shape roadmap), or a child (--shape child with --anchor naming the set anchor's <owner>/<repo>#<number>); see its --help and the contract's "New-issue ownership" section
   • the hidden publication token is this exact HTML-first body line. anchor reuses the opaque target value only when this new issue is itself the set anchor (self-reference); for a non-anchor child, anchor is instead the set anchor's already-resolved real <owner>/<repo>#<number> reference, not an opaque id (full rule: references/contract.md's "New-issue ownership" section):