Eliminate input failures when updating Jira issues via MCP

[williamthorsen]

Eliminate INVALID_INPUT failures when updating Jira issues via MCP

Problem

Updates to Jira issues via the update_jira_issue MCP tool fail repeatedly with opaque INVALID_INPUT errors when the description_html or comment_html payload contains HTML that the agent has every reason to believe is valid (semantic HTML, well-formed, no obvious problems). Each failure provides zero diagnostic signal ({"errorMessages":["INVALID_INPUT"],"errors":{}}), so the agent burns iterations on blind retries.

The operation is high-frequency and the failure mode is recurring in well-defined ways. The agent is the unreliable step in the middle, regenerating HTML stochastically each time. The goal is to eliminate (or at least sharply reduce) these failures without over-engineering the first intervention.

Context

Observed failure triggers

Three concrete triggers have been seen repeatedly:

1. Named HTML entities other than &/</> (e.g., —,  , …).
2. Confluence-only macros (<ac:task-list>, <ac:structured-macro>, etc.) inadvertently included by an agent that has been working with Confluence content in the same session.
3. File-path mode of the MCP tool — passing a path string in lieu of inline HTML.

Why these fail (inferred class)

The MCP tool advertises a permissive HTML surface, but the payload is converted into Atlassian Document Format (ADF) before persistence. The opaque error originates in that conversion. The general class of failure is:

HTML inputs that look valid to a generic HTML validator but cannot be losslessly mapped to Jira's ADF document model.

All three observed triggers fit this shape. There may be additional unknown instances of the class.

Why the agent is the right place to fix this (and why a sanitiser script is not the first move)

All three triggers are agent decisions about what to emit, not artefacts of an unavoidable transformation. The agent authors the HTML; it isn't sanitising third-party input. The first intervention should therefore be an explicit, prescriptive skill that names the rules — not a subprocess that polices the agent's output.

A deterministic sanitiser may be warranted later if explicit rules prove insufficient in practice. That decision should be gated on observed post-deploy failure rate, not on a hypothesis about reliability. To make that decision possible, the skill's recovery protocol must produce evidence (structured failure records) that can be reviewed periodically.

Existing constraints

• The MCP tool's interface is fixed; we cannot extend it to accept Markdown directly.
• The jira skill is a built-in platform skill (not part of this repo), so we cannot edit it.
• Skills installed via codeassembly-agents install ship into ~/.rovodev/skills/<name>/ (or platform equivalents). The path-rewriter expands {platform_home_dir} literally inside SKILL.md.
• codeassembly-agents is not installed onto user PATH; only the skill bundle ships globally.

Solution

Create a new user-invocable skill, update-jira-ticket, consisting of SKILL.md only — no helper script, no new dependencies, no install pipeline changes.

Mechanism

The skill body is short (~25–40 lines) and prescriptive. It covers:

1. When the skill applies — any call to update_jira_issue with description_html or comment_html.
2. Authoring rules — source content from a local Markdown artefact when one exists; otherwise compose in Markdown first. Convert to HTML using only the allowlisted elements; never hand-author HTML containing constructs outside the allowlist.
3. Allowed elements — h1–h6, p, ul, ol, li, strong, em, code, pre, a, blockquote, hr, br, table, thead, tbody, tr, th, td. Nothing else.
4. Forbidden constructs — <ac:*> macros (Confluence-only); named HTML entities other than &/</> (use literal Unicode: — not —, … not …, regular space or U+00A0 not  ).
5. Invocation rules — always pass HTML inline; never use file-path mode of the MCP tool.
6. Recovery protocol — if INVALID_INPUT still fires after following the rules: send <p>ok</p> to confirm call shape; bisect the payload to isolate the smallest failing fragment; cap at 4 retries; append a structured failure record to a known JSONL location (see below); surface the failing fragment to the user.
7. Escalation criterion — explicitly named in the skill body: if recorded failures concentrate in known trigger classes, file a follow-up to add a deterministic sanitiser; if they distribute across unknown classes, the recovery protocol remains the right tool.

Failure record format (interim, until generic logging exists)

The skill instructs the agent, at the end of the recovery protocol, to append a single JSON object per line to ~/ai-artifacts/skill-failures/update-jira-ticket.jsonl. Each record contains at minimum: timestamp, skill (update-jira-ticket), project_slug, failing_fragment, and notes. A separate follow-up ticket will replace this ad-hoc location with a generic skill-failure logging mechanism.

Auto-load

The skill's description: frontmatter is phrased to trigger the agent's skill-loading heuristics whenever the agent is about to call update_jira_issue with description_html or comment_html. The skill is also user-invocable as !update-jira-ticket.

Acceptance criteria

• A new skill update-jira-ticket exists at packages/agents/content/skills/update-jira-ticket/SKILL.md, with frontmatter that includes user-invocable: true and a description: phrased to auto-load on calls to update_jira_issue involving description_html or comment_html.
• The skill body is body-only — no peer files, no helper script, no new package dependencies, no install-pipeline changes.
• The skill body prescribes a single correct path: Markdown source → HTML constrained to the allowlist → inline payload, with explicit forbidden constructs (<ac:*>, named entities outside &/</>, file-path mode).
• The skill body includes the recovery protocol (<p>ok</p> probe → bisection → 4-retry cap → surface failing fragment), and instructs the agent to append a structured JSONL failure record to ~/ai-artifacts/skill-failures/update-jira-ticket.jsonl after a failed recovery attempt.
• The failure record format is documented inline in the skill body with at minimum these fields: timestamp (ISO 8601 UTC), skill (update-jira-ticket), project_slug, failing_fragment, notes.
• The skill body names an explicit escalation criterion: under what observed failure pattern a follow-up to add a deterministic sanitiser would be warranted.
• The skill installs successfully via codeassembly-agents install and the {platform_home_dir} mechanism (if used in the body) substitutes correctly.
• Any documentation that enumerates skills (if such an index exists in the repo) includes update-jira-ticket. If no such index exists, this is a no-op.
• A follow-up ticket is filed proposing a generic skill-failure logging mechanism (JSONL, with at least project_slug, skill, timestamp) that this skill (and others) can adopt in place of the interim ad-hoc location.

[williamthorsen]

Counter-proposal: skill body alone, no sanitiser script

The diagnosis is right but I think the prescription overcorrects. All three observed failure triggers are agent decisions about what to emit, not artefacts of an unavoidable transformation step. The agent is the author of the HTML — it isn't sanitising third-party input. Cleaning your own output by running it through a sibling script is a sign the rules belong in the skill body, not in a peer file.

Why the script is doing less work than it appears

• Named entities — the agent voluntarily emits — etc. The fix is "write — literally." That's a rule, not a transformation.
• <ac:*> macros — pure compliance ("never emit these"). A rule, not a transformation.
• File-path mode — pure compliance ("never use this argument shape"). A rule, not a transformation.

For each trigger, the sanitiser exists only to catch the case where the agent ignores a rule it could just follow. That's a real risk, but the recovery protocol (<p>ok</p> probe → bisection → surface fragment) already catches it — and it also catches unknown failure classes that the sanitiser cannot. The sanitiser is a redundant net for the same fish the recovery protocol already lands.

Costs the ticket understates

• Two sources of truth for the allowlist — SKILL.md describes it for the agent; sanitise.py enforces it. They will drift.
• Install-path fragility — {platform_home_dir} rewriting, python3 availability assumption, peer-file shipping in the bundle, tests for the script. All real maintenance surface for a problem that may not need it.
• A shell-out per Jira update on a high-frequency operation, just to verify the agent followed instructions.

Proposed alternative

Ship update-jira-ticket as SKILL.md only, ~25 lines, prescriptive:

When updating a Jira issue's description or comment via update_jira_issue:

Authoring. Source from a local Markdown artefact when one exists, or compose in Markdown first. Convert to HTML using only the allowlist below.

Allowed elements: `h1`–`h6`, `p`, `ul`, `ol`, `li`, `strong`, `em`, `code`, `pre`, `a`, `blockquote`, `hr`, `br`, `table`, `thead`, `tbody`, `tr`, `th`, `td`. Nothing else. Strip `ac:*` constructs unconditionally — Confluence-only, will reject.

Characters: literal Unicode in HTML, never named entities. `—` not `—`. `…` not `…`. Regular space (or U+00A0) not ` `. Only `&`, `<`, `>` are valid in payload.

Invocation: always pass HTML inline via `description_html` / `comment_html`. Never use file-path mode of the MCP tool.

Recovery (if `INVALID_INPUT` still fires): `

ok

` probe → bisect to smallest failing fragment → 4-retry cap → surface fragment to user.

The auto-load mechanism (frontmatter description: phrased to trigger on update_jira_issue calls involving description_html/comment_html) carries over unchanged.

When to revisit

If, after deploying the skill-body-only version, the agent measurably continues to emit banned constructs at frequency that costs real iterations, that is the moment to add the sanitiser — motivated by observed failure rate rather than hypothesised reliability gap. The recovery protocol gives us the bisection trace to confirm whether failures are concentrated in the known-trigger classes (sanitiser would help) or distributed across unknown classes (sanitiser would not).

Ask

Either:

1. Defend why explicit skill rules will not suffice for these three triggers, given the recovery protocol exists. Or
2. Reframe the ticket to ship the skill body alone first, and reserve sanitise.py for a follow-up gated on observed post-deploy failure rate.

[williamthorsen]

Accepted. Ticket and plan have been reshaped to ship the body-only skill — no sanitise.py, no peer files, no install-pipeline changes.

The counter-proposal's strongest point was epistemic: "deploy the cheaper thing, measure, escalate on evidence" beats "build the maximal solution on a hypothesised reliability gap." The two-sources-of-truth and shell-out-per-call critiques were also fair.

One modification carried into the revision: the recovery protocol now instructs the agent to append a structured JSONL failure record (timestamp, skill, project_slug, failing_fragment, notes) to a known location after a failed recovery attempt. Without that, "revisit if failures recur" tends to mean "never." This makes the escalation criterion data-driven.

A separate follow-up has been filed for a generic skill-failure logging mechanism that this skill (and others) can adopt in place of the interim ad-hoc JSONL location.

[williamthorsen]

Follow-up filed: #468 — generic skill-failure logging that this skill will migrate to once it lands.