mirror of
https://github.com/microsoft/BCQuality.git
synced 2026-08-06 17:36:53 +01:00
62dabf9a11
The /samples/ top-level tree is replaced with sibling files in each
knowledge-layer folder. An article and its demonstrations now live
side-by-side:
microsoft/knowledge/<domain>/<slug>.md
microsoft/knowledge/<domain>/<slug>.good.al
microsoft/knowledge/<domain>/<slug>.bad.al
Rationale:
- Proximity. An article and its paired samples are one unit; the
filesystem now reflects that.
- Layer ownership. Samples inherit layer precedence for free -- a
/custom/ fork can override an article and its samples atomically,
which the shared /samples/ tree previously made awkward.
- Trivial migration path. Action-skill source globs
(*/knowledge/<domain>/**/*.md) are unchanged; sample discovery is a
sibling-filename lookup.
Changes:
- git mv of all 65 sample files from samples/<domain>/<slug>/{bad,good}.al
to microsoft/knowledge/<domain>/<slug>.{bad,good}.al (history preserved).
- Update See-sample references in all 37 articles that ship samples.
- skills/read.md: replace the no-code-blocks bullet with a pointer to a
new Sample files section that fully specifies the sibling convention,
the kinds (good/bad + forward-compatible), multi-technology rules,
demonstration-only status, and layer-precedence behaviour.
- skills/write.md: update the samples pointer to match.
- README.md: annotate the knowledge tree with the sample sibling shape.
- samples/README.md deleted; content lifted into skills/read.md.
- Both generators (C:\temp\gen_performance_knowledge.py,
C:\temp\gen_security_knowledge.py) updated to emit at the new paths
and to stop writing samples/README.md. Re-running them is idempotent
against the committed layout.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
80 lines
5.2 KiB
Markdown
80 lines
5.2 KiB
Markdown
---
|
||
kind: meta-skill
|
||
id: write
|
||
version: 1
|
||
title: New Knowledge — how to author a knowledge file
|
||
---
|
||
|
||
# WRITE
|
||
|
||
Anyone — human or agent — adding a knowledge file to BCQuality follows this guide. READ is the format specification; WRITE is the authoring guide. This file does not restate the schema; consult READ for field-by-field semantics.
|
||
|
||
## Before you start
|
||
|
||
Read `skills/read.md` first. A file that does not conform to READ will be rejected. WRITE assumes READ is already understood.
|
||
|
||
## The atomicity rule
|
||
|
||
One knowledge file covers **one concern**. If two ideas would share a file, split them into two files and cross-reference from the Description. A good test: could an action skill reasonably want to cite one without the other? If yes, they are two concerns.
|
||
|
||
Symptoms that a file is trying to be two:
|
||
|
||
- Two Best Practice sections.
|
||
- A Description that uses "and" to join two topics.
|
||
- `keywords` that span two unrelated vocabularies.
|
||
|
||
## Size
|
||
|
||
Target under 100 lines. Ideal under 50. Long files almost always mean two concerns; the fix is to split, not to compress.
|
||
|
||
## Sections
|
||
|
||
**Description** is the only required section and the one that matters most. It states the concern and why it matters in two to five sentences. It is the primary retrieval target — write it as if a skill is deciding whether to load this file based on this text alone.
|
||
|
||
**Best Practice** is optional but recommended when the concern has a clear preferred approach. State the approach and the reasoning. Keep it to the *what* and *why*; the *how* (code) belongs in a sample file.
|
||
|
||
**Anti Pattern** is optional but recommended when the concern has a common wrong approach. State the pattern, the consequence, and the signal a reviewer or agent can use to detect it. Anti Pattern sections are highly actionable for review skills; write them with detection in mind.
|
||
|
||
Custom `##` sections are permitted when they serve the concern (for example, `## Applies to` for scope caveats or `## See also` for related files). Consumers are not required to understand them, so do not put load-bearing content there.
|
||
|
||
## No fenced code blocks
|
||
|
||
Knowledge files do not contain code. Samples live as **sibling files** next to the article — `<slug>.good.al`, `<slug>.bad.al`, etc. — in the same knowledge-layer folder. See `skills/read.md` for the full convention. This keeps knowledge files retrieval-friendly and prevents code from drifting out of sync with BC platform changes buried inside prose.
|
||
|
||
## Choosing frontmatter values
|
||
|
||
**`bc-version`.** Claim only the versions you have evidence for. If the guidance is known to apply from BC 24 onward and you have tested against 26–28, write `[26..28]`, not `[24..28]`. Under-claim; a future contributor can widen the range.
|
||
|
||
**`domain`.** Pick one. If two fit, the file is probably two concerns. If no existing domain fits, introduce a new one — domains are open. Prefer existing domains when they are a reasonable fit, to keep retrieval predictable.
|
||
|
||
**`keywords`.** Three to ten, lowercase, kebab-case. Write them as the search terms an engineer or agent would use to find this concern. Include synonyms when a concept has multiple common names (for example, `find-set` and `findset`). Do not duplicate the domain or title as a keyword.
|
||
|
||
**`technologies`.** List every technology the guidance touches, explicitly. Do not use a sentinel; there is no `[all]` for technologies. If the guidance is truly technology-agnostic, the file probably belongs in a different repository.
|
||
|
||
**`countries`.** Default to `[w1]` (worldwide). Use ISO country codes only when the guidance is specific to a localization — tax regulations, electronic invoicing formats, country-specific VAT rules. `[w1]` is mutually exclusive with country codes.
|
||
|
||
**`application-area`.** Default to `[all]`. Restrict only when the guidance is specific to a BC application area — posting routines in Finance, lot tracking in Warehouse Management. `[all]` is mutually exclusive with specific areas.
|
||
|
||
## File naming
|
||
|
||
`kebab-case.md`. The name should echo the concern: `filter-before-find.md`, `avoid-implicit-commit.md`, `telemetry-for-failed-posts.md`. Avoid generic names (`performance.md`) and version numbers in the name.
|
||
|
||
## Choosing a layer
|
||
|
||
- **`/microsoft/knowledge/<domain>/`** — platform-endorsed guidance. Authored or approved by the BC platform team. Use this layer only when the guidance reflects a platform guarantee or official recommendation.
|
||
- **`/community/knowledge/<domain>/`** — shared community patterns. The default layer for contributions from outside the platform team. Content here can be promoted to `/microsoft/` once it proves itself.
|
||
- **`/custom/knowledge/<domain>/`** — partner or customer overrides. Generally does not appear in the BCQuality repository itself; `/custom/` lives in consumer repositories.
|
||
|
||
## Pre-PR checklist
|
||
|
||
Before opening a pull request:
|
||
|
||
- Frontmatter has all six required fields with valid values (see READ).
|
||
- The file has a `## Description` section.
|
||
- No fenced code blocks.
|
||
- File is under 100 lines.
|
||
- File covers one concern.
|
||
- File is in the correct layer and domain folder.
|
||
- Name is kebab-case and descriptive.
|
||
|
||
Agents scaffolding new files SHOULD run this checklist programmatically before emitting the file.
|