mirror of
https://github.com/microsoft/BCQuality.git
synced 2026-08-06 09:26:52 +01:00
a56d1453b9
Repair broken knowledge references and align review examples with canonical articles. Correct explicit version gates, restore a missing title, and recognize the plugin directory in the root guard. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
149 lines
11 KiB
Markdown
149 lines
11 KiB
Markdown
---
|
||
kind: meta-skill
|
||
id: read
|
||
version: 1
|
||
title: Schema + Use — how to read a knowledge file
|
||
---
|
||
|
||
# READ
|
||
|
||
Every consumer of BCQuality — an agent, an action skill, a human reviewer — reads this file first. It defines what a knowledge file is, what fields it contains, what they mean, and how to reconcile multiple files.
|
||
|
||
This contract is stable. Changes require a PR approved by both maintainers.
|
||
|
||
## What a knowledge file is
|
||
|
||
A knowledge file is a single markdown file that covers **one concern** in Business Central development. It has:
|
||
|
||
- A YAML frontmatter block with the fields below. All fields are required.
|
||
- A `## Description` section. Required.
|
||
- Optional sections — typically `## Best Practice` and `## Anti Pattern`, but any `##` section is permitted.
|
||
- No fenced code blocks. Sample code lives in **sibling files** next to the article (see [Sample files](#sample-files) below).
|
||
|
||
A file that violates any of these rules is invalid and MUST be skipped by consumers. Do not attempt to partially parse invalid files.
|
||
|
||
## Frontmatter schema (v1)
|
||
|
||
```yaml
|
||
---
|
||
bc-version: [all] # or [26, 27, 28], the range [26..28], or the open-ended range [26..]
|
||
domain: performance
|
||
keywords: [query, filtering, partial]
|
||
technologies: [al]
|
||
countries: [w1]
|
||
application-area: [all]
|
||
---
|
||
```
|
||
|
||
All six fields are required. Missing or empty fields invalidate the file.
|
||
|
||
### Fields
|
||
|
||
**`bc-version`** — Array. The Business Central major versions this file applies to. Four forms are accepted:
|
||
|
||
- Universal sentinel: `[all]` means the guidance applies to every BC version and matches any target.
|
||
- Explicit list: `[26, 27, 28]`.
|
||
- Closed range shorthand: `[26..28]` means every integer from 26 through 28 inclusive.
|
||
- Open-ended range shorthand: `[26..]` means version 26 and every later version, with no upper bound. Use it for guidance tied to a feature introduced in a specific version that is not expected to be removed.
|
||
|
||
`[all]` is mutually exclusive with explicit versions; do not combine. Consumers MUST expand closed ranges to the full set before comparison; an open-ended range `[N..]` is not enumerable and instead matches any target version greater than or equal to `N`.
|
||
|
||
**`domain`** — String. A single domain tag that places the file within a broader area of concern. Standard values include `performance`, `security`, `ux`, `telemetry`, `testing`, `api`, `pipelines`, `finance`, `supply-chain`, `manufacturing`, `jobs`. New domains may be introduced by contributors; no closed enumeration is enforced at the schema level. Consumers MUST treat unknown domains as valid.
|
||
|
||
**`keywords`** — Array of strings. Free-text tags used for retrieval. Between 3 and 10 tags is typical. Tags are lowercase, kebab-case, and describe the concern in the vocabulary an engineer or agent would search for.
|
||
|
||
**`technologies`** — Array of strings. The technologies the file applies to. Examples: `al`, `javascript`, `powershell`, `kql`, `azure-devops`, `github-actions`. A file that applies across technologies lists all of them explicitly. The sentinel `all` is not permitted for this field.
|
||
|
||
**`countries`** — Array of strings. ISO 3166-1 alpha-2 country codes (lowercase: `us`, `de`, `dk`) for localization-specific guidance. Use the sentinel `[w1]` for guidance that applies worldwide. `[w1]` is mutually exclusive with country codes; do not combine.
|
||
|
||
**`application-area`** — Array of strings. The BC application areas the file applies to. Examples: `finance`, `manufacturing`, `jobs`, `warehousing`, `service`. Use the sentinel `[all]` for guidance that applies regardless of application area. `[all]` is mutually exclusive with specific areas.
|
||
|
||
## Sections
|
||
|
||
**`## Description`** is required. It states the concern: what the topic is and why it matters. It is the primary retrieval target when a consumer decides whether a file is relevant.
|
||
|
||
Two further sections are recognized as **normative** — consumers MAY rely on their content for conflict detection and guidance extraction:
|
||
|
||
- **`## Best Practice`** — the recommended approach.
|
||
- **`## Anti Pattern`** — what to avoid and the reasoning.
|
||
|
||
Any other `##` section is permitted and is **non-normative**: consumers MUST NOT treat its contents as binding guidance. Non-normative sections (for example `## See also` or `## Applies to`) are for human context; they are ignored by conflict detection and by the filtering rules below. Consumers MUST NOT fail on unknown sections.
|
||
|
||
## Layer precedence
|
||
|
||
A knowledge file lives in one of three layers, determined by its path:
|
||
|
||
- `/microsoft/knowledge/**` — platform-endorsed.
|
||
- `/community/knowledge/**` — community-curated.
|
||
- `/custom/knowledge/**` — partner or customer overrides (typically in a consumer repo, not in BCQuality).
|
||
|
||
The default consumption model is **additive**: an action skill sees files from every enabled layer and may surface findings from all of them. A consumer MAY be configured to disable a layer; in that case, files in the disabled layer are invisible to the consumer.
|
||
|
||
When two files give **directly contradictory normative guidance**, the conflict is resolved by layer precedence:
|
||
|
||
1. `/custom/` wins over `/community/` and `/microsoft/`.
|
||
2. `/community/` wins over `/microsoft/`.
|
||
|
||
A conflict exists when both of the following are true:
|
||
|
||
- **Applicability overlaps.** The files' frontmatter filters (`bc-version`, `technologies`, `countries`, `application-area`) have a non-empty intersection under the matching rules below. `domain` is a retrieval aid; it is not part of the applicability test.
|
||
- **Normative guidance contradicts.** Content in the `## Best Practice` or `## Anti Pattern` sections is logically incompatible (one recommends what the other forbids, or vice versa). Non-normative sections are not considered.
|
||
|
||
Conflict detection is the consumer's responsibility; BCQuality does not enforce conflict-free content. When a consumer suppresses a losing file due to precedence or configuration, it **MUST** record the suppression in its output (see DO) so reviewers can see what was overridden.
|
||
|
||
## Frontmatter matching semantics
|
||
|
||
When a consumer filters or matches files against a task context, these rules apply:
|
||
|
||
- **`bc-version`** — the file matches if its set is `[all]`, or if the target BC version is an element of the file's expanded `bc-version` set. Closed range shorthand (`[26..28]`) MUST be expanded before comparison; an open-ended range (`[26..]`) matches when the target BC version is greater than or equal to its lower bound.
|
||
- **`technologies`** — non-empty intersection between the task's technologies and the file's technologies. There is no sentinel for this field.
|
||
- **`countries`** — the file matches if its set contains `w1`, or if there is a non-empty intersection with the task's countries.
|
||
- **`application-area`** — the file matches if its set contains `all`, or if there is a non-empty intersection with the task's application areas.
|
||
|
||
A file is **applicable** to a task when all four rules match. Applicability is also the basis for conflict detection above.
|
||
|
||
### When the task context is partial
|
||
|
||
A task context may omit one or more dimensions (for example, a skill invoked against a raw file path with no known target BC version). For any omitted dimension:
|
||
|
||
- If the file's value for that dimension is a universal sentinel (`all` for bc-version, `w1` for countries, `all` for application-area), the rule matches.
|
||
- Otherwise the rule is treated as **unknown**, not as a match and not as a failure.
|
||
|
||
A file with any `unknown` rule is **conditionally applicable**. A consumer MAY include conditionally applicable files in the worklist; if it does, every finding derived from such a file MUST have `confidence` no higher than `medium` and MUST record the unknown dimensions in the finding's `message`. A consumer MAY be configured to exclude conditionally applicable files entirely.
|
||
|
||
Consumers MUST NOT silently treat missing context as a match.
|
||
|
||
## Citing a knowledge file
|
||
|
||
A consumer that produces output referencing a knowledge file MUST cite it by its repo-relative path (for example, `microsoft/knowledge/performance/apply-filters-before-iterating.md`). Line numbers are not stable references; use the file path only. If a commit SHA is available to the consumer, it SHOULD be included alongside the path.
|
||
|
||
## Sample files
|
||
|
||
Knowledge files MUST NOT contain fenced code blocks. When an article needs to show code, it ships the code as one or more **sibling files** next to the article, using this naming convention:
|
||
|
||
```
|
||
<layer>/knowledge/<domain>/<slug>.md # the article
|
||
<layer>/knowledge/<domain>/<slug>.good.al # best-practice demonstration
|
||
<layer>/knowledge/<domain>/<slug>.bad.al # anti-pattern demonstration
|
||
```
|
||
|
||
Rules:
|
||
|
||
- A sample file is identified by the article's slug followed by a `.<kind>.<ext>` suffix. The supported kinds are `good` and `bad`. Additional kinds MAY be introduced by a layer; consumers MUST ignore unknown kinds without failing.
|
||
- The extension matches the technology (`al`, `ps1`, `js`, `kql`, …). A single article MAY carry samples in multiple technologies if the article's frontmatter `technologies` lists them.
|
||
- Articles MAY have a `good` sample only, a `bad` sample only, both, or neither. The article text SHOULD reference each sample it ships, using a relative path like `` `<slug>.good.al` ``.
|
||
- Samples are **demonstration-only**. They are not deployed, not compiled as part of a published app, and not derived from the Business Central base application source. Each sample is self-contained and exists purely to make the accompanying article concrete for humans and agents.
|
||
- Layer precedence applies to sample files the same way it applies to articles: a `/custom/knowledge/<domain>/<slug>.good.al` overrides a `/microsoft/knowledge/<domain>/<slug>.good.al` for the same article in the same layer hierarchy.
|
||
|
||
Consumers that surface sample code to an end user or agent SHOULD cite the sample file by its repo-relative path, in the same format as article citations.
|
||
|
||
## Retrieval workflow
|
||
|
||
The standard workflow for finding applicable files:
|
||
|
||
1. Collect candidates from the knowledge index (`knowledge-index.json`). BCQuality maintains it: Entry's preparation step (see [entry.md](entry.md)) regenerates it over the live, already-filtered clone, so it lists exactly the articles that survived the consumer's layer/allow-deny pruning, each with the frontmatter, `keywords`, `title`, and one-line `description` that steps 2-3 need — candidates are enumerated without opening each file. The index is **discovery metadata only**: it tells you *which* files to open, it does not substitute for them. A finding MUST cite only an article that was opened and read in full; an index row whose file is absent from the clone MUST be discarded *before* ranking or worklisting, and its metadata MUST NOT seed a finding. Absent an index, collect candidates by path (typically by `domain` subfolder, across enabled layers).
|
||
2. Filter by frontmatter using the matching rules above. Files that are not applicable are discarded.
|
||
3. Rank or narrow by `keywords` relevance to the task.
|
||
4. Resolve conflicts via layer precedence.
|
||
|
||
Steps 1–3 are deterministic; step 4 is applied only when conflicts are detected.
|