---
name: issue-markdown
description: Build and refactor issue, comment, and review bodies in actions/setup/js using typed report trees and a single publication render.
---
# Issue and comment Markdown
Use this skill when generating or changing Markdown published to issues, comments,
or reviews, especially in `actions/setup/js/`. Build a `Report` tree first; render
only the complete document. Do not assemble Markdown using interpolation,
concatenation, `body +=`, or arrays of Markdown strings joined with newlines.
Parsing an assembled string afterward is not a tree-first refactor.
## Find publication paths
Search production `.cjs` files for `issues.create`, `issues.update`,
`createComment`, `updateComment`, `createReview`, `createReplyForReviewComment`,
and GraphQL body variables. Trace each body back through shared helpers, fallback
comments, retries, staged previews, and append/prepend/replace-island updates.
Exclude test fixtures, HTTP payload assembly, and step-summary-only output.
Jira ADF text is not Markdown: preserve its literal entities, Unicode, and
paragraphs instead of routing it through the Markdown parser or renderer.
## Use the existing tree
`actions/setup/js/report_ast.cjs` defines `Report`, `ReportBlock`, and `ReportInline`.
Use JSDoc annotations so `npm run typecheck` verifies node kinds:
```javascript
/** @type {import("./report_ast.cjs").Report} */
const report = {
type: "report",
title: "Workflow result",
children: [
{
type: "paragraph",
agentTainted: false,
children: [
{ type: "text", value: "Created related issue: ", agentTainted: false },
{ type: "issue_reference", number: String(issue.number), agentTainted: false },
],
},
{ type: "code_block", language: "text", value: diagnostic, agentTainted: true },
],
};
```
Use `heading`, `paragraph`, `list`, `table`, `details`, `quote`, `alert`,
`separator`, `code_block`, and typed inline nodes instead of Markdown punctuation.
GitHub `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, and `[!CAUTION]`
map to `alert` nodes with the matching `kind`; the renderer emits their markers.
Keep alerts separate rather than nesting them inside another alert, which GitHub
does not support. Preserve supported `<sub>` formatting in details summaries.
Use `xml_marker`, `json_marker`, `expiration`, and `closing_reference` for machine
metadata and closing links. Preserve `xml_marker.compact` for identifiers whose
exact spelling is used by cleanup. Use `review_marker` for the durable,
URI-encoded review caller reference; keep the authoritative marker last.
Dynamic labels, paths, errors, and identifiers belong
in text/code nodes; link destinations belong in `link.url`.
Import existing agent/user Markdown with `parseReportMarkdown`, specifying
`agentTainted: true`, the correct `allowedMentions`, and the existing heading and
metadata policy. Parse configured templates before scalar substitution using
`context`; use typed inline/block slots for inserted nodes. Never interpolate
untrusted values into a template before parsing it. A literal code fence in
imported content must not swallow attribution or adjacent generated blocks.
For managed comment memory, set `code_block.language` to
`gh-aw-comment-memory:<id>` and `fenceLength: 6`; rendering lengthens the fence
past embedded backticks. Do not construct or slice fences by hand.
## Compose shared attribution
Use the typed variants instead of rendering a helper and reparsing its output:
| Purpose | Tree-first API |
| --- | --- |
| Generated attribution and guard notices | `buildGeneratedFooterBlocks` / `assembleReportBodyParts` in `markdown_body_helpers.cjs` |
| Deferred footer templates and diagnostic sections | `buildFooterBlocks(getFooterMessageParts(context))` in `messages_footer.cjs` |
| Configured policy footer | `getBodyFooterBlocks` or `appendConfiguredReportFooter` |
| Detection warning | `getDetectionCautionBlocks` |
| Failure-comment attribution | `getFooterAgentFailureCommentBlocks` |
| Authoritative execution metadata | `appendReportExecutionProvenance` |
Keep custom templates and their scalar context separate until composition.
Headers and footers may jointly open/close `<details>`; use
`buildIssueBodyReport` to parse these wrappers together around body slots.
Allocate unique slot names against both source text and previously allocated
slots, and reject wrappers that swallow slots inside code fences.
Internal framework notes carried between handlers use non-JSON-forgeable Symbols
such as `COMMENT_PREAMBLE` and `ISSUE_BODY_SUFFIX`, never agent-settable flags.
## Preserve publication contracts
Framework-authored nodes use `agentTainted: false`; agent-owned descendants retain
their taint even inside framework wrappers. Keep required footer diagnostics,
metadata, and policy text protected during size fitting. Do not mark an entire
agent body trusted to keep it from being shortened.
For attributed safe-output issues and comments, use `buildIssueBodyReport` in
`issue_body.cjs`; it accepts Markdown or typed body blocks and retains configured
wrappers, attribution, expiration, and execution provenance. Comment callers set
the appropriate `itemType` and `workflowIdMarker: false`. Pass the original
workflow `runUrl` when the target repository differs from the execution repository.
Fallback issues must import the original agent body and compose recovery nodes,
not reparse an already assembled or rendered PR/discussion description.
For other issue producers, pass a typed report to
`renderIssueParameters`/`createReportIssue` in `issue_report.cjs`, preserving the
existing authentication and retry boundary. `buildIssueReport` accepts typed
blocks as well as imported Markdown. For comments, render the complete tree with
`renderSizedReport` from `report_size.cjs` and pass its body to the existing API.
Do not render fragments and concatenate or reparse them. Keep one logical render
boundary, including metadata and trusted footers in its size budget.
`renderSizedReport` trims trailing whitespace automatically and measures the
publication body against the exact `maxLength`. Do not trim its result or reserve
an extra character for a terminal newline. Low-level `renderReport` retains its
terminal newline for Markdown serialization. Never truncate rendered Markdown
or trusted policy text to fit.
## Validate the migration
Preserve footer on/off behavior, marker identity and order, mention/link limits,
expiration, cross-repository attribution, structured state recovery, managed
memory extraction, review fallbacks, and append/prepend/island semantics.
Assert tree shape as well as rendered output. Cover hostile backticks and HTML
delimiters, Unicode, escaped table cells, and the exact publication size limit.
Update formatting expectations only for intentional canonical rendering, not to
hide lost content or metadata.
Run the matching Vitest suites from `actions/setup/js`, `npm run typecheck`,
and the repository JavaScript formatting/lint gates. Follow the developer skill
for final repository validation and publication.