Seed performance knowledge corpus (22 articles + AL samples)

Converts an existing performance-review prompt into 22 atomic
knowledge articles under microsoft/knowledge/performance/, each
paired with AL samples under samples/performance/<slug>/ demonstrating
the anti-pattern and/or the best practice. The full set seeds the
corpus the microsoft/skills/al-performance-review leaf skill matches
against and validates the READ knowledge-file format end-to-end.

Every article conforms to the READ contract: six required frontmatter
fields, Description always present, no fenced code blocks, sample
code referenced by repo-relative path. Each article is marked with a
blockquote 'Seed article' note so domain stewards can extend or
restructure them freely.

Articles (ordered by concern area):

Database query efficiency
- use-findset-with-next (AA0181)
- avoid-findfirst-with-next (AA0233)
- only-fetch-records-you-use (AA0175)
- use-findset-readonly-by-default
- use-setloadfields-for-partial-records
- use-addloadfields-in-report-layouts
- use-calcsums-to-aggregate-filtered-sets (file: use-calcsums-for-flowfield-totals.md)
- avoid-calcfields-in-loops
- add-sift-keys-for-flowfields (AA0232)
- use-isempty-for-existence-checks

Filter and key optimization
- filter-before-find
- set-current-key-to-match-filters

Temporary tables and transactions
- use-temporary-tables-for-intermediate-data
- keep-transaction-scope-short
- avoid-user-interaction-in-transactions
- avoid-commit-inside-loops

Record operations
- prefer-get-for-primary-key-lookups
- use-insert-false-when-skipping-triggers
- prefer-direct-record-over-recordref

Strings, codeunits, events
- use-strsubstno-for-message-formatting
- use-single-instance-codeunits-for-caching
- keep-event-subscribers-lightweight

samples/README.md documents the sample-folder convention and makes
clear the samples are demonstration-only, not derived from BC base
application source, with unique object IDs in the 50100-50199 range.

Rubber-duck pass caught: a misleading good.al in avoid-calcfields-in-loops
(fixed by switching to a hoistable CalcFields scenario), an invalid
event subscriber signature in keep-event-subscribers-lightweight
(fixed by adding var xRec), normative guidance leaked into the
Description of use-findset-readonly-by-default (moved to Anti Pattern),
a missing sample pair for keep-transaction-scope-short (added), and
muddy FlowField/CalcSums framing (retitled and clarified).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

samples/README.md

@@ -0,0 +1,29 @@
+# BCQuality Samples
+
+This directory contains AL (and, over time, other-language) code samples referenced by knowledge articles in BCQuality.
+
+## Layout
+
+Samples are organized by domain and by the slug of the knowledge article that references them:
+
+```
+samples/
+  <domain>/
+    <article-slug>/
+      bad.al      # demonstrates the anti-pattern
+      good.al     # demonstrates the best practice
+```
+
+Some articles only have a `good.al` (best practice only) or only a `bad.al` (pure avoidance). That is intentional.
+
+## Status
+
+All samples are **demonstration-only**. They are self-contained AL objects with object IDs in the 50100-50199 range and are not meant to be deployed, nor are they derived from Microsoft's Business Central base application source. They exist to make the accompanying knowledge articles concrete for human readers and for agents that benefit from a worked example.
+
+## Referencing samples from knowledge articles
+
+Knowledge articles MUST NOT contain fenced code blocks (see `skills/read.md`). When a knowledge article wants to show code, it references the relevant sample by path, for example:
+
+> See sample: `samples/performance/filter-before-find/good.al`.
+
+Orchestrators and action skills are free to read these files and include relevant excerpts in their output.

samples/performance/add-sift-keys-for-flowfields/good.al

@@ -0,0 +1,10 @@
+tableextension 50118 "Perf Sample SIFTKey" extends "Cust. Ledger Entry"
+{
+    keys
+    {
+        key(PerfSampleOpenByCustomer; "Customer No.", Open, "Posting Date")
+        {
+            SumIndexFields = "Remaining Amt. (LCY)";
+        }
+    }
+}

samples/performance/avoid-calcfields-in-loops/bad.al

@@ -0,0 +1,18 @@
+codeunit 50117 "Perf Sample CalcFieldsInLoop Bad"
+{
+    procedure ProcessLargeLines(var SalesHeader: Record "Sales Header"; var SalesLine: Record "Sales Line")
+    begin
+        SalesLine.SetRange("Document Type", SalesHeader."Document Type");
+        SalesLine.SetRange("Document No.", SalesHeader."No.");
+        if SalesLine.FindSet() then
+            repeat
+                SalesHeader.CalcFields(Amount);
+                if SalesHeader.Amount > 1000 then
+                    ProcessLine(SalesLine);
+            until SalesLine.Next() = 0;
+    end;
+
+    local procedure ProcessLine(var SalesLine: Record "Sales Line")
+    begin
+    end;
+}

samples/performance/avoid-calcfields-in-loops/good.al

@@ -0,0 +1,18 @@
+codeunit 50116 "Perf Sample CalcFieldsInLoop Good"
+{
+    procedure ProcessLargeLines(var SalesHeader: Record "Sales Header"; var SalesLine: Record "Sales Line")
+    begin
+        SalesHeader.CalcFields(Amount);
+        SalesLine.SetRange("Document Type", SalesHeader."Document Type");
+        SalesLine.SetRange("Document No.", SalesHeader."No.");
+        if SalesLine.FindSet() then
+            repeat
+                if SalesHeader.Amount > 1000 then
+                    ProcessLine(SalesLine);
+            until SalesLine.Next() = 0;
+    end;
+
+    local procedure ProcessLine(var SalesLine: Record "Sales Line")
+    begin
+    end;
+}

samples/performance/avoid-commit-inside-loops/bad.al

@@ -0,0 +1,15 @@
+codeunit 50129 "Perf Sample CommitInLoop Bad"
+{
+    procedure ReleaseAllOrders()
+    var
+        SalesHeader: Record "Sales Header";
+    begin
+        SalesHeader.SetRange(Status, SalesHeader.Status::Open);
+        if SalesHeader.FindSet() then
+            repeat
+                SalesHeader.Status := SalesHeader.Status::Released;
+                SalesHeader.Modify();
+                Commit();
+            until SalesHeader.Next() = 0;
+    end;
+}

samples/performance/avoid-findfirst-with-next/bad.al

@@ -0,0 +1,14 @@
+codeunit 50105 "Perf Sample AvoidFindFirstNext Bad"
+{
+    procedure EmitAllItems(var Item: Record Item)
+    begin
+        if Item.FindFirst() then
+            repeat
+                EmitItem(Item);
+            until Item.Next() = 0;
+    end;
+
+    local procedure EmitItem(var Item: Record Item)
+    begin
+    end;
+}

samples/performance/avoid-user-interaction-in-transactions/bad.al

@@ -0,0 +1,11 @@
+codeunit 50127 "Perf Sample UserInTxn Bad"
+{
+    procedure ArchiveSalesHeader(var SalesHeader: Record "Sales Header")
+    begin
+        SalesHeader.Status := SalesHeader.Status::Released;
+        SalesHeader.Modify();
+        if not Confirm('Archive document %1?', false, SalesHeader."No.") then
+            exit;
+        SalesHeader.Delete(true);
+    end;
+}

samples/performance/avoid-user-interaction-in-transactions/good.al

@@ -0,0 +1,14 @@
+codeunit 50126 "Perf Sample UserInTxn Good"
+{
+    procedure ArchiveSalesHeader(var SalesHeader: Record "Sales Header")
+    begin
+        if not Confirm('Archive document %1?', false, SalesHeader."No.") then
+            exit;
+        DoArchive(SalesHeader);
+    end;
+
+    local procedure DoArchive(var SalesHeader: Record "Sales Header")
+    begin
+        // only Insert/Modify/Delete calls happen here; no prompts
+    end;
+}

samples/performance/filter-before-find/bad.al

@@ -0,0 +1,16 @@
+codeunit 50101 "Perf Sample FilterBeforeFind Bad"
+{
+    procedure ProcessUsCustomers(var Customer: Record Customer)
+    begin
+        if Customer.FindSet() then
+            repeat
+                if Customer."Country/Region Code" = 'US' then
+                    ProcessCustomer(Customer);
+            until Customer.Next() = 0;
+    end;
+
+    local procedure ProcessCustomer(var Customer: Record Customer)
+    begin
+        // per-customer work
+    end;
+}

samples/performance/filter-before-find/good.al

@@ -0,0 +1,16 @@
+codeunit 50100 "Perf Sample FilterBeforeFind Good"
+{
+    procedure ProcessUsCustomers(var Customer: Record Customer)
+    begin
+        Customer.SetRange("Country/Region Code", 'US');
+        if Customer.FindSet() then
+            repeat
+                ProcessCustomer(Customer);
+            until Customer.Next() = 0;
+    end;
+
+    local procedure ProcessCustomer(var Customer: Record Customer)
+    begin
+        // per-customer work
+    end;
+}

samples/performance/keep-event-subscribers-lightweight/bad.al

@@ -0,0 +1,12 @@
+codeunit 50140 "Perf Sample Subscriber Bad"
+{
+    [EventSubscriber(ObjectType::Table, Database::"Sales Line", 'OnAfterValidateEvent', 'No.', false, false)]
+    local procedure HeavyWorkOnSalesLineNo(var Rec: Record "Sales Line"; var xRec: Record "Sales Line")
+    var
+        HttpClient: HttpClient;
+        HttpResponse: HttpResponseMessage;
+    begin
+        // synchronous external call on a hot event
+        HttpClient.Get('https://example.com/validate?no=' + Rec."No.", HttpResponse);
+    end;
+}

samples/performance/keep-transaction-scope-short/bad.al

@@ -0,0 +1,18 @@
+codeunit 50128 "Perf Sample TxnScope Bad"
+{
+    procedure ImportCustomers(var Source: List of [Text])
+    var
+        Customer: Record Customer;
+        HttpClient: HttpClient;
+        HttpResponse: HttpResponseMessage;
+        Row: Text;
+    begin
+        foreach Row in Source do begin
+            // external call inside the write transaction
+            HttpClient.Get('https://example.com/validate?row=' + Row, HttpResponse);
+            Customer.Init();
+            // ... populate from Row ...
+            Customer.Insert(true);
+        end;
+    end;
+}

samples/performance/keep-transaction-scope-short/good.al

@@ -0,0 +1,22 @@
+codeunit 50123 "Perf Sample TxnScope Good"
+{
+    procedure ImportCustomers(var Source: List of [Text])
+    var
+        Prepared: Record Customer temporary;
+        Customer: Record Customer;
+    begin
+        // read, validate, and shape outside the transaction
+        PrepareRows(Source, Prepared);
+
+        // transaction starts here: only Insert/Modify calls
+        if Prepared.FindSet() then
+            repeat
+                Customer := Prepared;
+                Customer.Insert(true);
+            until Prepared.Next() = 0;
+    end;
+
+    local procedure PrepareRows(var Source: List of [Text]; var Prepared: Record Customer temporary)
+    begin
+    end;
+}

samples/performance/only-fetch-records-you-use/bad.al

@@ -0,0 +1,10 @@
+codeunit 50107 "Perf Sample OnlyFetchUsed Bad"
+{
+    procedure CustomerHasEntries(CustomerNo: Code[20]): Boolean
+    var
+        CustLedgerEntry: Record "Cust. Ledger Entry";
+    begin
+        CustLedgerEntry.SetRange("Customer No.", CustomerNo);
+        exit(CustLedgerEntry.FindSet());
+    end;
+}

samples/performance/only-fetch-records-you-use/good.al

@@ -0,0 +1,10 @@
+codeunit 50106 "Perf Sample OnlyFetchUsed Good"
+{
+    procedure CustomerHasEntries(CustomerNo: Code[20]): Boolean
+    var
+        CustLedgerEntry: Record "Cust. Ledger Entry";
+    begin
+        CustLedgerEntry.SetRange("Customer No.", CustomerNo);
+        exit(not CustLedgerEntry.IsEmpty());
+    end;
+}

samples/performance/prefer-direct-record-over-recordref/bad.al

@@ -0,0 +1,20 @@
+codeunit 50135 "Perf Sample RecordRef Bad"
+{
+    procedure BlockCustomer(CustomerNo: Code[20])
+    var
+        RecRef: RecordRef;
+        PkRef: KeyRef;
+        NoRef: FieldRef;
+        BlockedRef: FieldRef;
+    begin
+        RecRef.Open(Database::Customer);
+        PkRef := RecRef.KeyIndex(1);
+        NoRef := PkRef.FieldIndex(1);
+        NoRef.SetRange(CustomerNo);
+        if not RecRef.FindFirst() then
+            exit;
+        BlockedRef := RecRef.Field(54);
+        BlockedRef.Value(2);
+        RecRef.Modify(true);
+    end;
+}

samples/performance/prefer-direct-record-over-recordref/good.al

@@ -0,0 +1,12 @@
+codeunit 50134 "Perf Sample RecordRef Good"
+{
+    procedure BlockCustomer(CustomerNo: Code[20])
+    var
+        Customer: Record Customer;
+    begin
+        if not Customer.Get(CustomerNo) then
+            exit;
+        Customer.Blocked := Customer.Blocked::All;
+        Customer.Modify(true);
+    end;
+}

samples/performance/prefer-get-for-primary-key-lookups/bad.al

@@ -0,0 +1,11 @@
+codeunit 50131 "Perf Sample GetVsFind Bad"
+{
+    procedure CustomerName(CustomerNo: Code[20]): Text[100]
+    var
+        Customer: Record Customer;
+    begin
+        Customer.SetRange("No.", CustomerNo);
+        if Customer.FindFirst() then
+            exit(Customer.Name);
+    end;
+}

samples/performance/prefer-get-for-primary-key-lookups/good.al

@@ -0,0 +1,10 @@
+codeunit 50130 "Perf Sample GetVsFind Good"
+{
+    procedure CustomerName(CustomerNo: Code[20]): Text[100]
+    var
+        Customer: Record Customer;
+    begin
+        if Customer.Get(CustomerNo) then
+            exit(Customer.Name);
+    end;
+}

samples/performance/set-current-key-to-match-filters/good.al

@@ -0,0 +1,9 @@
+codeunit 50122 "Perf Sample SetCurrentKey Good"
+{
+    procedure LinesForDocument(DocumentType: Enum "Sales Document Type"; DocumentNo: Code[20]; var SalesLine: Record "Sales Line")
+    begin
+        SalesLine.SetCurrentKey("Document Type", "Document No.", "Line No.");
+        SalesLine.SetRange("Document Type", DocumentType);
+        SalesLine.SetRange("Document No.", DocumentNo);
+    end;
+}

samples/performance/use-addloadfields-in-report-layouts/good.al

@@ -0,0 +1,17 @@
+report 50112 "Perf Sample AddLoadFields Good"
+{
+    dataset
+    {
+        dataitem(Cust; "Cust. Ledger Entry")
+        {
+            column(CustomerNo; "Customer No.") { }
+            column(PostingDate; "Posting Date") { }
+            column(Amount; Amount) { }
+
+            trigger OnPreDataItem()
+            begin
+                AddLoadFields("Customer No.", "Posting Date", Amount);
+            end;
+        }
+    }
+}

samples/performance/use-calcsums-for-flowfield-totals/bad.al

@@ -0,0 +1,14 @@
+codeunit 50115 "Perf Sample CalcSums Bad"
+{
+    procedure OutstandingForCustomer(CustomerNo: Code[20]) Total: Decimal
+    var
+        CustLedgerEntry: Record "Cust. Ledger Entry";
+    begin
+        CustLedgerEntry.SetRange("Customer No.", CustomerNo);
+        CustLedgerEntry.SetRange(Open, true);
+        if CustLedgerEntry.FindSet() then
+            repeat
+                Total += CustLedgerEntry."Remaining Amt. (LCY)";
+            until CustLedgerEntry.Next() = 0;
+    end;
+}

samples/performance/use-calcsums-for-flowfield-totals/good.al

@@ -0,0 +1,12 @@
+codeunit 50114 "Perf Sample CalcSums Good"
+{
+    procedure OutstandingForCustomer(CustomerNo: Code[20]): Decimal
+    var
+        CustLedgerEntry: Record "Cust. Ledger Entry";
+    begin
+        CustLedgerEntry.SetRange("Customer No.", CustomerNo);
+        CustLedgerEntry.SetRange(Open, true);
+        CustLedgerEntry.CalcSums("Remaining Amt. (LCY)");
+        exit(CustLedgerEntry."Remaining Amt. (LCY)");
+    end;
+}

samples/performance/use-findset-readonly-by-default/bad.al

@@ -0,0 +1,10 @@
+codeunit 50109 "Perf Sample FindSetReadonly Bad"
+{
+    procedure SumInvoiceLines(var SalesLine: Record "Sales Line") Total: Decimal
+    begin
+        if SalesLine.FindSet(true) then
+            repeat
+                Total += SalesLine."Line Amount";
+            until SalesLine.Next() = 0;
+    end;
+}

samples/performance/use-findset-readonly-by-default/good.al

@@ -0,0 +1,10 @@
+codeunit 50108 "Perf Sample FindSetReadonly Good"
+{
+    procedure SumInvoiceLines(var SalesLine: Record "Sales Line") Total: Decimal
+    begin
+        if SalesLine.FindSet() then
+            repeat
+                Total += SalesLine."Line Amount";
+            until SalesLine.Next() = 0;
+    end;
+}

samples/performance/use-findset-with-next/bad.al

@@ -0,0 +1,10 @@
+codeunit 50103 "Perf Sample FindSetWithNext Bad"
+{
+    procedure SumLineAmounts(var SalesLine: Record "Sales Line") Total: Decimal
+    begin
+        if SalesLine.FindFirst() then
+            repeat
+                Total += SalesLine."Line Amount";
+            until SalesLine.Next() = 0;
+    end;
+}

samples/performance/use-findset-with-next/good.al

@@ -0,0 +1,10 @@
+codeunit 50102 "Perf Sample FindSetWithNext Good"
+{
+    procedure SumLineAmounts(var SalesLine: Record "Sales Line") Total: Decimal
+    begin
+        if SalesLine.FindSet() then
+            repeat
+                Total += SalesLine."Line Amount";
+            until SalesLine.Next() = 0;
+    end;
+}

samples/performance/use-insert-false-when-skipping-triggers/good.al

@@ -0,0 +1,12 @@
+codeunit 50132 "Perf Sample InsertParam Good"
+{
+    procedure BulkLoadTempItems(var TempItem: Record Item temporary; Source: List of [Code[20]])
+    var
+        ItemNo: Code[20];
+    begin
+        foreach ItemNo in Source do begin
+            TempItem."No." := ItemNo;
+            TempItem.Insert(false);
+        end;
+    end;
+}

samples/performance/use-isempty-for-existence-checks/bad.al

@@ -0,0 +1,11 @@
+codeunit 50121 "Perf Sample IsEmpty Bad"
+{
+    procedure HasOpenDocuments(CustomerNo: Code[20]): Boolean
+    var
+        SalesHeader: Record "Sales Header";
+    begin
+        SalesHeader.SetRange("Sell-to Customer No.", CustomerNo);
+        SalesHeader.SetRange(Status, SalesHeader.Status::Open);
+        exit(SalesHeader.Count() > 0);
+    end;
+}

samples/performance/use-isempty-for-existence-checks/good.al

@@ -0,0 +1,11 @@
+codeunit 50120 "Perf Sample IsEmpty Good"
+{
+    procedure HasOpenDocuments(CustomerNo: Code[20]): Boolean
+    var
+        SalesHeader: Record "Sales Header";
+    begin
+        SalesHeader.SetRange("Sell-to Customer No.", CustomerNo);
+        SalesHeader.SetRange(Status, SalesHeader.Status::Open);
+        exit(not SalesHeader.IsEmpty());
+    end;
+}

samples/performance/use-setloadfields-for-partial-records/bad.al

@@ -0,0 +1,14 @@
+codeunit 50111 "Perf Sample SetLoadFields Bad"
+{
+    procedure ExportItemNumbers(var Item: Record Item)
+    begin
+        if Item.FindSet() then
+            repeat
+                Export(Item."No.", Item.Description);
+            until Item.Next() = 0;
+    end;
+
+    local procedure Export(ItemNo: Code[20]; Description: Text[100])
+    begin
+    end;
+}

samples/performance/use-setloadfields-for-partial-records/good.al

@@ -0,0 +1,15 @@
+codeunit 50110 "Perf Sample SetLoadFields Good"
+{
+    procedure ExportItemNumbers(var Item: Record Item)
+    begin
+        Item.SetLoadFields("No.", Description);
+        if Item.FindSet() then
+            repeat
+                Export(Item."No.", Item.Description);
+            until Item.Next() = 0;
+    end;
+
+    local procedure Export(ItemNo: Code[20]; Description: Text[100])
+    begin
+    end;
+}

samples/performance/use-single-instance-codeunits-for-caching/good.al

@@ -0,0 +1,17 @@
+codeunit 50138 "Perf Sample SingleInstance Good"
+{
+    SingleInstance = true;
+
+    var
+        Cached: Record "Sales & Receivables Setup";
+        Loaded: Boolean;
+
+    procedure GetSetup(): Record "Sales & Receivables Setup"
+    begin
+        if not Loaded then begin
+            Cached.Get();
+            Loaded := true;
+        end;
+        exit(Cached);
+    end;
+}

samples/performance/use-strsubstno-for-message-formatting/bad.al

@@ -0,0 +1,7 @@
+codeunit 50137 "Perf Sample StrSubstNo Bad"
+{
+    procedure CustomerGreeting(var Customer: Record Customer): Text
+    begin
+        exit('Hello, ' + Customer.Name + ' (' + Customer."No." + ')');
+    end;
+}

samples/performance/use-strsubstno-for-message-formatting/good.al

@@ -0,0 +1,9 @@
+codeunit 50136 "Perf Sample StrSubstNo Good"
+{
+    procedure CustomerGreeting(var Customer: Record Customer): Text
+    var
+        GreetingLbl: Label 'Hello, %1 (%2)';
+    begin
+        exit(StrSubstNo(GreetingLbl, Customer.Name, Customer."No."));
+    end;
+}

samples/performance/use-temporary-tables-for-intermediate-data/good.al

@@ -0,0 +1,16 @@
+codeunit 50124 "Perf Sample TempTable Good"
+{
+    procedure BuildAffectedItems(var TempItem: Record Item temporary)
+    var
+        SalesLine: Record "Sales Line";
+    begin
+        TempItem.Reset();
+        TempItem.DeleteAll();
+        SalesLine.SetRange(Type, SalesLine.Type::Item);
+        if SalesLine.FindSet() then
+            repeat
+                TempItem."No." := SalesLine."No.";
+                if TempItem.Insert(false) then;
+            until SalesLine.Next() = 0;
+    end;
+}