لم تُترجم هذه الصفحة بعد.

Diagnostics and fixes

This page is for developers who check instruction texts, in the editor, with the instruction CLI or over MCP. It lists all 48 diagnostic codes: the 42 that instruction.md reports, with their severity and when they appear, and the ones the specification defines that it doesn't report. It shows each quick fix on a real text, says which diagnostics stop a release, and lists the checks only the editor makes.

How a diagnostic reads

A diagnostic has a code, a severity, a message and, when it is about one place, a line (1-based). It can also have a uri (the base or include it was found in, not the document itself) and a remedy, a hint at the fix. instruction validate --json gives the reader's whole diagnostic instead: a range (start and end lines) in place of line, and for some codes a target, the tool, integration or block it is about.

  • error: the text is not valid as written. A release refuses it.
  • warning: the text is valid, and something in it doesn't do what it seems to. A warning never stops a release.
  • info: a hint. Only the editor gives them.

Codes are the specification's (§18), except those that start with instruction.md/: they are instruction.md's own checks, kept apart from the format's codes. An extension's codes start with its id, extension-id/code.

When diagnostics appear

Check is what reading a text finds: the reader, the inline checks, the workflow checks and instruction.md's own check for Specification 1.1. It runs on the text alone, in:

  • the editor, as you type, in Problems;
  • instruction validate, on files;
  • spec_validate, on any text, and instructions_validate, on a stored draft;
  • every release, on the text being released.

Delivery is what resolving a text finds: its bases and includes read, its parameters given, its allowances narrowed. It runs in spec_deliver, in instruction deliver and whenever an agent reads an instruction. A delivery error means the agent gets no complete text; a delivery warning gives a partial result.

What stops a release

A release refuses any text with a check error. Warnings and infos pass. The refusal is a validation error with the first 50 errors:

instructions_publish, refused
{
  "error": {
    "code": "validation",
    "message": "the text has 1 error(s) a release refuses; fix them first (spec_fixes helps)",
    "details": {
      "diagnostics": [
        {
          "code": "unknown-kind",
          "severity": "error",
          "message": ":::contxt is not a kind of this specification; it is kept as written, uninterpreted",
          "line": 10
        }
      ],
      "validator": "instruction.md"
    }
  }
}

Every release also runs the server's checks, validate and lint, and keeps the result with the version. A failed lint doesn't stop the release; it stops a ref that requires checks from moving to that version. See Run the server's checks.

host-matter-authored is reported by the server and the editor, not by instruction validate: a source to publish must not hold the host's integration lines, which the server adds when it serves the instruction.

Every code

42 codes are reported, and 11 of them have a quick fix. The rest are defined by the specification for other implementations (bundles, adapters, exports) and never reported here.

CodeSeverityWhenMeaningQuick fix
adapter-unavailable—Not reportedA required compiler, runtime, resolver, test or export adapter is unavailable.—
allowance-amount-invaliderrorCheck, DeliveryAn amount not a decimal ≥ 0 (≤ 18 fractional digits), or times not an integer ≥ 1.—
allowance-approve-above-over-maxerrorCheck, Deliveryapprove-above above max.—
allowance-approver-not-personerrorDeliveryAn approver that is not a person or role.—
allowance-currency-invaliderrorCheck, DeliveryMissing or non-ISO-4217 currency.—
allowance-max-over-budgeterrorCheck, Deliverymax above budget.—
allowance-payees-invaliderrorCheck, DeliveryA payee that is no domain, merchant id or & reference.—
allowance-per-unknownerrorCheck, Deliveryper outside its six values.—
allowance-unboundederrorCheck, DeliveryAn allowance without budget.—
allowance-widenederrorDeliveryAn extending document widens an inherited allowance.—
allowance-window-invertederrorCheck, Deliveryuntil before from.—
bundle-invalid—Not reportedAn invalid bundle entry, path, hash or mapping.—
comment-unclosedwarningCheckA comment reaches the end of the file; a warning.—
composition-cycleerrorDeliveryAn include or inheritance cycle.—
duplicate-iderrorCheck, DeliveryAn identity collides within a document instance.Yes
export-conflict—Not reportedAmbiguous targets, duplicate names, competing grants or conflicting native declarations.—
extension-unavailableerrorCheck, DeliveryA required, undeclared or unsupported extension.—
footnote-duplicateerrorCheckA footnote is defined twice in one instance.—
footnote-missingwarningCheckA referenced footnote is absent; a warning.Yes
host-matter-authorederrorCheckHost: a source to publish already holds host-integrations.—
integration-not-allowedwarningCheckA connected object's target is outside the effective policy's allowed.—
invalid-attributeserrorCheck, DeliveryInvalid attribute syntax, key, typed value or a repeated key.Yes (5)
invalid-metadataerrorCheck, DeliveryInvalid or non-mapping metadata, or a known field of the wrong shape.—
invalid-native-config—Not reportedNative configuration or profile validation failed.—
invalid-nestingerrorCheckA fence length or a child-parent rule is violated.Yes (2)
invalid-source—Not reportedThe source bytes are not valid UTF-8.—
invalid-structured-bodyerrorCheckA YAML, JSON or CSV body, or its required shape, is invalid.—
invalid-workflowerrorCheckA workflow's dialect schema, dependency graph or routing is invalid.—
limit-exceedederrorCheck, DeliveryA published processing or resource limit is exceeded.—
math-unclosedwarningCheckA display-math opener without a matching close; a warning.—
orphan-reasonwarningCheckA reason with no rule; a warning.—
parameter-invaliderrorCheck, DeliveryA declaration, default or supplied value is invalid.—
parameter-missingerrorDeliveryA required parameter is missing.—
parameter-optionalwarningCheck, DeliveryAn optional or undeclared placeholder is left as written; a warning.Yes
patch-bodyerrorDeliveryAn incompatible patch operation or body.—
patch-targeterrorDeliveryA patch has no inherited explicit-id target.—
pin-mismatcherrorCheck, DeliveryA required digest or version does not match.—
protocol-syntaxerrorCheckA protocol value does not match name[/versions].—
protocol-version-required—Not reportedA bare protocol name whose binding marks no version stable.—
reason-repeatederrorCheckMore than one reason is attached to one rule.—
reference-kinderrorCheck, DeliveryA typed reference does not match its target's kind.Yes
reference-missingerrorDeliveryA required target is inaccessible or absent.—
reference-optionalwarningCheck, DeliveryAn optional target is unresolved; a warning, and a partial result.Yes
tool-blockedwarningCheckA tool a connected object names is blocked on its server by the effective integrations policy.—
unclosed-directiveerrorCheckA container has no matching close.Yes
unknown-kinderrorCheckThe kind is not registered.Yes (2)
unsupported-formaterrorCheckAn unknown spec or interchange format.Yes
instruction.md/legacy-syntaxerrorCheckinstruction.md's own check: a line written in Specification 1.1, which this edition reads differently. spec_fixes converts the document.Yes

Each code's row has an anchor, #code- and the code with other characters as dashes: #code-unknown-kind.

Quick fixes

A quick fix is an edit that removes a diagnostic without guessing what the author meant: a misspelt kind, attribute or value, a fence too short, a missing id or closing fence, a repeated attribute, an undeclared parameter, a footnote without its definition, a typed reference to the wrong kind or a misspelt id, and a text still in Specification 1.1. A diagnostic with nothing certain to fix gets none.

These are the fixes on real texts, as spec_fixes and the editor make them:

unknown-kind, line 1: :::contxt is not a kind of this specification; it is kept as written, uninterpreted. Fix: Write :::context

Before
:::contxt{title="Where things are"}
The staging database is read-only.
:::
After
:::context{title="Where things are"}
The staging database is read-only.
:::

unknown-kind, line 1: :persn[…] is not an inline kind of this specification; it is kept as written. Fix: Write :person

Before
Ask :persn[the on-call engineer]{ref=#oncall} first.

::person{id=oncall title="On-call"}
After
Ask :person[the on-call engineer]{ref=#oncall} first.

::person{id=oncall title="On-call"}

unclosed-directive, line 1: :::context is not closed: end it with a line of :::. Fix: Close it with :::

Before
:::context{title="Where things are"}
The staging database is read-only.
After
:::context{title="Where things are"}
The staging database is read-only.
:::

invalid-nesting, line 5: the closing fence on line 5 is shorter than the :::context it closes (4 colons). Fix: Write ::::

Before
::::context{title="Release"}
:::note
Tag the release first.
:::
:::
After
::::context{title="Release"}
:::note
Tag the release first.
:::
::::

invalid-nesting, line 2: :::note opens inside a ::: container with as many colons or more: an inner fence is shorter than its outer one. Fix: Renumber the fences: each inner one shorter

Before
:::context{title="Release"}
:::note
Tag the release first.
:::
:::
After
::::context{title="Release"}
:::note
Tag the release first.
:::
::::

invalid-attributes, line 1: ::person needs id=…. Fix: Give it the id on-call

Before
::person{title="On-call"}
After
::person{id=on-call title="On-call"}

invalid-attributes, line 1: :::context: the attribute "title" is repeated. Fix: Remove the repeated title="Production"

Before
:::context{title="Staging" title="Production"}
The database is read-only.
:::
After
:::context{title="Staging"}
The database is read-only.
:::

invalid-attributes, line 1: :::context: "titel" is not an attribute this kind takes. Fix: Write title

Before
:::context{titel="Where things are"}
The staging database is read-only.
:::
After
:::context{title="Where things are"}
The staging database is read-only.
:::

invalid-attributes, line 1: :::context: "titel" is not an attribute this kind takes. Fix: Remove titel="Where things are"

Before
:::context{titel="Where things are"}
The staging database is read-only.
:::
After
:::context{}
The staging database is read-only.
:::

invalid-attributes, line 1: ::param: "type" is one of string, number, integer, boolean, enum, list, url, duration. Fix: Write type=string

Before
::param{name=region type=strng}
After
::param{name=region type=string}

duplicate-id, line 3: the id "owner" is used twice (first on line 1); ids are unique in a document. Fix: Rename it owner-2

Before
::person{id=owner title="Owner"}

::person{id=owner title="Deputy"}
After
::person{id=owner title="Owner"}

::person{id=owner-2 title="Deputy"}

parameter-optional, line 1: ${team} is not a declared parameter, so it stays as written. Fix: Declare the parameter team

Before
You work for the ${team} team.
After
---
parameters:
  team: { type: string }
---

You work for the ${team} team.

footnote-missing, line 1: the footnote [^1] has no definition, so it stays as text. Fix: Define [^1]

Before
Refunds follow the published policy[^1].
After
Refunds follow the published policy[^1].

[^1]: 

unsupported-format, line 1: spec: "2" is not a format this reader knows; it reads spec: "1". Fix: Write spec: "1"

Before
---
spec: "2"
---

# Refunds
After
---
spec: "1"
---

# Refunds

reference-kind, line 3: :agent[…] names #ana, which is a person, not a agent. Fix: Write :person[…]

Before
::person{id=ana title="Ana"}

Ask :agent[Ana]{ref=#ana} before a refund.
After
::person{id=ana title="Ana"}

Ask :person[Ana]{ref=#ana} before a refund.

reference-optional, line 3: :person[…]: nothing in this document has the id "anna". Fix: Point it at #ana

Before
::person{id=ana title="Ana"}

Ask :person[Ana]{ref=#anna} before a refund.
After
::person{id=ana title="Ana"}

Ask :person[Ana]{ref=#ana} before a refund.

instruction.md/legacy-syntax, line 3: a Specification 1.1 variant: this edition delivers every reader the same text. Fix: Convert the document to this edition

Before
# Support

:::when{reader=agent}
Reply in under 100 words.
:::
After
# Support

:::context{title="When reader is agent"}
Reply in under 100 words.
:::

Fix a text over MCP

spec_fixes takes the text, and optionally a code and a line to narrow it to one diagnostic. Each fix is a list of replace operations, ready for instructions_draft_edit. Offsets are UTF-16 code units into the whole text you sent.

The call
{
  "name": "spec_fixes",
  "arguments": { "content": "<the text>", "code": "unknown-kind", "line": 1 }
}
The text
:::contxt{title="Limits"}
Refunds over €200 need a person.
:::
The answer
{
  "problems": [
    {
      "code": "unknown-kind",
      "severity": "error",
      "message": ":::contxt is not a kind of this specification; it is kept as written, uninterpreted",
      "line": 1,
      "fixes": [
        {
          "title": "Write :::context",
          "ops": [
            {
              "op": "replace",
              "from": 7,
              "to": 7,
              "text": "e"
            }
          ]
        }
      ]
    }
  ],
  "formatted": null
}

To apply a fix to a stored draft, read the draft with instructions_get and include: ["draft"], call spec_fixes with its text, and send the chosen fix's operations to instructions_draft_edit with the draft's revision as expectedRevision. An edit made on an older revision is refused with version_conflict: read again and ask for the fixes again. formatted is not null when spec_format would also change the text.

spec_validate answers with every diagnostic, whether the text is valid (ok), the capability families it needs (requires), its spec and its title:

The call
{
  "name": "spec_validate",
  "arguments": { "content": "<the text>" }
}
The answer
{
  "ok": false,
  "diagnostics": [
    {
      "code": "parameter-optional",
      "severity": "warning",
      "message": "${team} is not a declared parameter, so it stays as written",
      "line": 8
    },
    {
      "code": "unknown-kind",
      "severity": "error",
      "message": ":::contxt is not a kind of this specification; it is kept as written, uninterpreted",
      "line": 10
    }
  ],
  "spec": "1",
  "requires": [],
  "title": "Refunds",
  "validator": "instruction.md"
}

spec_explain explains a code, a kind or a keyword:

The call
{
  "name": "spec_explain",
  "arguments": { "topic": "instruction.md/legacy-syntax" }
}
The answer
{
  "topic": "instruction.md/legacy-syntax",
  "code": "instruction.md/legacy-syntax",
  "meaning": "instruction.md's own check: a line written in Specification 1.1, which this edition reads differently. spec_fixes converts the document."
}

The spec_* tools are on instruction.md's MCP server and on instruction mcp, the stdio server the CLI runs on your machine; they change nothing. MCP tools has their inputs.

Check files with the CLI

instruction validate reports every check diagnostic of each file. It exits 1 when a file has an error, or a warning with --strict. It doesn't apply fixes: use spec_fixes through instruction mcp, or the editor. Its options are on Commands.

Commands
instruction validate refunds.md
instruction validate refunds.md --strict      # warnings fail too
instruction validate refunds.md --json        # every diagnostic, with its range
refunds.md
---
spec: "1"
title: Refunds
---

# Refunds

You work for the ${team} team.

:::contxt{title="Limits"}
Refunds over €200 need a person.
:::
Output
INVALID  refunds.md
         line 10: :::contxt is not a kind of this specification; it is kept as written, uninterpreted  [unknown-kind]
         warning line 8: ${team} is not a declared parameter, so it stays as written  [parameter-optional]

Errors come first, then warnings and infos (left out with --quiet). Each line ends with its code.

In the editor

Problems lists the diagnostics of the instruction you are editing, by line. F8 goes to the next problem and Shift+F8 to the previous one. Ctrl+. (⌘. on a Mac) opens the quick fixes for the caret's line (Quick fix — the problems on the caret's line). When a text has errors, the publish sheet says how many and offers Show, and its publish button is disabled with the tip Fix the problems first.

With Developer mode on, each problem shows its code, its line and the message on this page. With it off, a problem is one plain sentence, and a fix's title is put in plain words too: Make it a rule for a fix that writes a rule keyword, Close it for a closing fence, Set up “team” for declaring the parameter team, and Fix it for any other fix whose title has syntax in it. Check your instruction before you publish shows what a writer sees.

The editor's own checks

The editor adds these to the specification's. They are hints about how a text reads, not about whether it is valid, so they never stop a release, and no other tool reports them.

CodeSeverityDeveloper mode says, for an example lineIn plain wordsQuick fix
keyword-casewarning"must:" is prose — a keyword is written in capitals, MUST:, for the agent to receive it labelledThis sentence reads like a rule but is written as ordinary text. Make it a rule so the agent receives it as one.Write MUST:
prose-ruleinfo"You must" is a sentence — write "MUST:" to make it a rule the agent receives labelledThis sentence could be a rule. Make it one so the agent receives it as a rule.Write MUST:
unclosed-codewarningthis code block is never closed — everything after it is code, delivered as writtenA code block is never closed, so everything after it is treated as code.Close it with ```
title-differswarningThe title in Details differs from the heading — "Refunds" here, "Refund policy" in the heading, which is the name—Use the heading; Remove title:

Write MUST: stands for the keyword in capitals. For keyword-case it is the word as written, upper-cased: MUST, MUST NOT, SHOULD, SHOULD NOT, NEVER, MAY, ALWAYS, GUARDRAIL, AVOID or BECAUSE. For prose-rule it is the rule the sentence asked for: "must" and "always" give MUST, "must not", "must never" and "never" give NEVER, and "should", "should not" and "may" give SHOULD, SHOULD NOT and MAY.

If it doesn't work

What you see Why What to do
the text has 2 error(s) a release refuses; fix them first (spec_fixes helps) The text has check errors Fix the errors in details.diagnostics; spec_fixes has the certain ones
instruction.md/legacy-syntax on several lines The text is written in Specification 1.1 Apply its one fix, which converts the whole text. See Upgrade from Specification 1.1
spec_fixes answers a problem with an empty fixes Nothing certain to fix: the code has no quick fix, or the text could mean more than one thing Fix it by hand, using the message and remedy
version_conflict from instructions_draft_edit The draft changed after you read it Read the draft again, ask spec_fixes again, and send the new operations
The editor shows a problem instruction validate doesn't It is one of the editor's own checks, or host-matter-authored Nothing blocks the release unless it is an error; see The editor's own checks
Still stuck Ask us

Last checked against the product:

Was this page helpful? Report a problem