bcquality/microsoft/skills/review/al-error-handling-review.md

kind	id	version	title	description	inputs	outputs	bc-version	technologies	countries	application-area
action-skill	al-error-handling-review	1	AL error handling review	Reviews AL source changes against error-handling guidance from BCQuality.	pr-diff file-path folder-path	findings-report	all	al	w1	all

AL error handling review

Reviews AL source changes against the error-handling knowledge domain in BCQuality and emits a findings report. This is a leaf action skill: it invokes no sub-skills. It is one of the skills composed by al-code-review.

An orchestrator invokes this skill with a pr-diff, file-path, or folder-path. The skill produces a single JSON document conforming to the DO output contract.

Source

Use READ's Bounded retrieval for review skills workflow with -Domain error-handling. Consume every catalog page across enabled layers before applying this leaf's Relevance and Worklist; preserve each exact catalog path and open complete bodies only for exact paths selected by the Worklist. If the helper or prepared index is unavailable or invalid, use READ's explicit path-discovery and bounded native-read fallback.

When the review scope contains outbound HttpClient.Get or HttpClient.Post calls, including resolved call paths, also retrieve every catalog page with -Domain web-services, using the same known task dimensions and enabled layers. Restrict supplementary candidates to these article slugs across enabled layers; the links identify their canonical owners:

• handle-httpclient-platform-failure-before-response-access
• check-http-status-before-consuming-response-body

Retain each selected catalog row's exact path; do not invent paths for missing, pruned, or disabled entries. Apply this leaf's Relevance, Worklist, and READ layer precedence to the supplementary candidates before retrieving complete bodies with Get-KnowledgeArticles.ps1. Apply each selected article's own scope and exceptions when evaluating code and agent-finding candidates. Use READ's bounded path-discovery fallback over these same sources when needed. This supplements error-handling knowledge, not the scope of the review with unrelated web-services concerns.

Relevance

Apply the frontmatter matching rules defined in READ (Frontmatter matching semantics) against the task context:

• bc-version — the target BC version from the PR branch's app.json or the orchestrator-supplied version. If unavailable, the dimension is unknown.
• technologies — [al].
• countries — the countries declared in the consuming app's app.json. Default to the orchestrator's configured context; if absent, unknown.
• application-area — the union of application areas declared by the changed objects. Pass the actual set; do not substitute [all]. If the area cannot be determined from the changes, the dimension is unknown.

Discard files that are not applicable. Retain conditionally applicable files (any dimension unknown) only when the orchestrator's configuration permits them; findings derived from those files MUST have confidence no higher than medium, AND the finding's message MUST name the dimension or dimensions that were unknown.

Worklist

Narrow the relevant files to the subset that applies to the changes under review. For each relevant file, compute overlap against:

• The changed AL object names and types — especially codeunits that post or validate, tables and table extensions with OnValidate triggers, and any procedure that raises errors or orchestrates a batch over records.
• The changed procedures and triggers, weighted toward OnValidate/OnInsert/OnModify triggers, posting and validation routines, and procedures attributed with [ErrorBehavior(...)] or [TryFunction].
• Tokens extracted from the diff that relate to error surfacing and diagnostics (Error, ErrorInfo, FieldError, TestField, Title, Message, DetailedMessage, AddAction, AddNavigationAction, RecordId, PageNo, ErrorBehavior, Collect, HasCollectedErrors, GetCollectedErrors, ClearCollectedErrors, ErrorType, Internal, Client, TryFunction, GetLastErrorText, Boolean assignment).
• For the outbound HTTP call paths identified in Source, include HttpClient, Get, Post, HttpResponseMessage, response use, and caller failure handling (including [TryFunction] call sites) in keyword and topic matching.
• Resolve changed standalone call targets; when the target declaration has [TryFunction], worklist the ignored-return rule even if the declaration itself is unchanged. Only assignment and conditional use activate try semantics.

A file enters the candidate worklist when its keywords intersect the extracted tokens or its topic (derived from the index entry's path, title, and description) matches a changed object type. Read an article's full file — its ## Best Practice / ## Anti Pattern bodies — only after it makes the worklist; candidate selection uses the index alone.

The following targeted checks cover every current error-handling article:

• [ErrorBehavior(ErrorBehavior::Collect)], ErrorInfo.Collectible, HasCollectedErrors, GetCollectedErrors, or ClearCollectedErrors is added or changed, especially when errors are collected without later surfacing/clearing them — collect-validation-errors-with-errorbehavior.
• New or changed code inserts an error/duration log record around a failed TryFunction/GetLastErrorText/GetLastErrorCode path and then raises, propagates, or rethrows the error — log-writes-must-survive-rollback. Do not worklist it when the log insert already happens inside a Session.StartSession-targeted codeunit's OnRun; that is the compliant shape, not the signal to flag.
• A guarded lookup (if Record.Get(...) then ... else or similar) sets a value used later, and the same guard shape (with the same blank/zero fallback style) is applied to a field that feeds a posted amount, a tax/VAT calculation, a quantity or price actually used in a transaction, or a legally/compliance-facing output — defensive-vs-offensive-code-must-match-blast-radius. The signal is a posting-critical or compliance-facing field guarded defensively with a silent fallback, not the mere presence of a guarded lookup.
• Developer-only invariant text is raised with default client visibility, or a user-actionable validation is hidden as ErrorType::Internal — errortype-internal-vs-client-for-diagnostics.
• FieldError receives a complete capitalized sentence, repeats the field caption/value, or ends the predicate with punctuation — fielderror-default-message-logic.
• An unguarded FieldError is used as though it performed a comparison, or TestField is forced onto a complex rule needing a tailored predicate — fielderror-vs-testfield.
• A resolved call target is marked [TryFunction] but the call is a standalone statement whose Boolean result is ignored — ignored-tryfunction-return-disables-try-semantics. This call-site rule supersedes the performance TryFunction article unless writes and rollback expectations are also visible.
• A plain Error represents a known actionable correction that can be expressed through ErrorInfo actions/navigation, or an ErrorInfo omits the context needed for that action — prefer-errorinfo-for-actionable-errors.

Once the candidate worklist is known, resolve layer-precedence conflicts per READ. Drop lower-precedence files whose normative guidance (## Best Practice or ## Anti Pattern) directly contradicts a higher-precedence candidate, and record each dropped file in suppressed with reason: "layer-precedence". Files that would have been candidates but are hidden because their layer is disabled in consumer configuration are recorded with reason: "configuration". Files that never became candidates are NOT recorded in suppressed.

When the post-conflict worklist is empty because no applicable error-handling knowledge exists, or because configuration suppressed every candidate, emit outcome: "no-knowledge". When the worklist is empty because no applicable error-handling knowledge matched the changes, emit outcome: "completed" with an empty findings array.

Action

For each worklist entry, evaluate the diff against the file's ## Best Practice and ## Anti Pattern sections. Emit findings as follows:

• When the diff contains a clear match for an Anti Pattern, emit a finding with severity major or blocker, a message summarizing the anti-pattern, location pointing to the offending line or range, and a references entry pointing to the knowledge file. Use blocker only when the knowledge file states the anti-pattern violates a platform-level guarantee. When the file does not make such a claim, the ceiling is major.
• When the diff contains code that contradicts a Best Practice without being a full anti-pattern, emit minor with the same reference shape.
• Applicability alone is not a finding. Emit info only for a concrete, non-actionable observation the article explicitly defines; otherwise emit nothing when no violation is present.

Set confidence to:

• high when the detection is based on an unambiguous pattern match (identifier, syntax, object type).
• medium when detection relies on heuristics or when any frontmatter dimension was unknown.
• low when the finding is an advisory derived only from applicability.

After evaluating each worklist entry, also consider whether the diff exhibits an error-handling defect the agent recognises from its general AL knowledge that no knowledge file in the worklist covers. Such candidates are agent findings within this skill's domain — emit them with references: [], an id slug prefixed with agent:, confidence capped at medium, severity capped at minor (agent findings are advisory and non-gating), and a message that is self-contained (describing both the issue and a concrete recommendation, since there is no knowledge-file footer for the consumer to fall back on). Hold every candidate to the precision bar in skills/do.md (Agent findings): emit only a concrete, material error-handling defect a knowledgeable BC reviewer would agree is wrong — steelman it first and drop anything stylistic, speculative, dependent on code outside the diff, or merely a valid alternative; when in doubt, omit. The scope is strictly error handling; defects outside this domain belong to other leaves and MUST NOT be emitted here. Before emitting, check the worklist for a knowledge file that matches the candidate — if one exists, upgrade the candidate to a knowledge-backed finding instead. See skills/do.md for the full contract.

For every emitted finding, decide whether the fix is mechanical. A fix is mechanical when it is small, local, and unambiguous from the diff context (for example: replace a string-concatenated Error with a Label-backed call; mark an internal-only failure ErrorType::Internal; add a missing DetailedMessage). For mechanical findings, emit findings[].suggested-code with the literal replacement for the source lines indicated by location. The payload must be a verbatim replacement — no diff markers, no fences, no commentary — that the consumer can render as a one-click suggestion. When a .good.al companion exists and the diff context matches the .bad.al shape, adapt the .good.al replacement into suggested-code.

Omit suggested-code only when the appropriate fix depends on context the skill cannot determine, when multiple defensible replacements exist, or when the fix spans non-contiguous code. If a finding is mechanical-looking but you omit suggested-code, set findings[].suggested-code-omission-reason to a short explanation. See skills/do.md for the full contract.

Outcome selection:

• completed — the skill evaluated every worklist item; default when the skill finishes normally, including when the resulting findings array is empty.
• no-knowledge — no applicable error-handling knowledge survived Source, Relevance, configuration filtering, and conflict resolution. findings is empty.
• not-applicable — the task context lacks an AL dimension (no AL changes in the diff, or technologies filter rejected the task).
• partial — a time or token budget was hit before the worklist was exhausted. summary.coverage reflects the evaluated subset; outcome-reason explains the cause.
• failed — an unrecoverable error occurred. outcome-reason is required.

Output

Output conforms to the DO output contract. Every finding this skill emits MUST set findings[].domain to "Error Handling". A populated example:

{
  "skill": { "id": "al-error-handling-review", "version": 1 },
  "outcome": "completed",
  "summary": {
    "counts": { "blocker": 0, "major": 1, "minor": 1, "info": 0 },
    "coverage": { "worklist-size": 2, "items-evaluated": 2 }
  },
  "findings": [
    {
      "id": "microsoft/knowledge/error-handling/prefer-errorinfo-for-actionable-errors.md",
      "severity": "major",
      "message": "A validation error names the maximum allowed quantity but raises a plain Error with no recommended action. Use an ErrorInfo with a Fix-it AddAction so the user can apply the known value.",
      "location": {
        "file": "src/Sales/SalesLine.TableExt.al",
        "line": 88,
        "range": { "start-line": 86, "end-line": 89 }
      },
      "references": [
        { "path": "microsoft/knowledge/error-handling/prefer-errorinfo-for-actionable-errors.md" }
      ],
      "confidence": "high",
      "domain": "Error Handling"
    },
    {
      "id": "microsoft/knowledge/error-handling/errortype-internal-vs-client-for-diagnostics.md",
      "severity": "minor",
      "message": "This 'unexpected state' failure is developer-facing but is raised with default Client visibility. Mark it ErrorType::Internal so the detail goes to telemetry and the user sees a generic message.",
      "location": {
        "file": "src/Ledger/PostingEngine.Codeunit.al",
        "line": 211
      },
      "references": [
        { "path": "microsoft/knowledge/error-handling/errortype-internal-vs-client-for-diagnostics.md" }
      ],
      "confidence": "medium",
      "domain": "Error Handling"
    }
  ],
  "suppressed": []
}

When no applicable error-handling knowledge is available, the report is:

{
  "skill": { "id": "al-error-handling-review", "version": 1 },
  "outcome": "no-knowledge",
  "summary": {
    "counts": { "blocker": 0, "major": 0, "minor": 0, "info": 0 },
    "coverage": { "worklist-size": 0, "items-evaluated": 0 }
  },
  "findings": [],
  "suppressed": []
}