mirror of
https://github.com/microsoft/BCQuality.git
synced 2026-08-06 17:36:53 +01:00
b9c57ba6f9
Reviewing #112 surfaced that the authoring docs never state where a new BC fact (or a false-positive guard) belongs, so an agent iterated do.md -> leaf skills -> knowledge files across two review rounds before landing knowledge in a knowledge article. The information to decide existed but was split across README/do.md/write.md and framed only as positive best practices. - do.md: add "Skills hold mechanics; knowledge files hold BC facts" — a skill is a finder/applier; every BC behavioural claim it acts on must be a cited knowledge file. Names negative knowledge (false-positive guards) as first class, and forbids both adding a BC fact to a skill and restating an article's fact inline (the drift/duplication smell). - write.md: add "Is this a knowledge file?" decision gate at the top, plus a "Negative knowledge is first-class" section with the Description/Best Practice/Anti Pattern mapping and a worked example. - README: note that false-positive-preventing files are first-class knowledge and add a reviewer heuristic to Contributing. Prose-only additions; validator passes. Meta-skill contract semantics are unchanged, so version stays 1 (maintainers may bump if they consider the explicit boundary rule a contract change). Copilot-Session: 76eba53e-18cd-4618-a205-3607f260f9f4 Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com> Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> |
||
|---|---|---|
| .. | ||
| bcquality-al-review | ||
| do.md | ||
| entry.md | ||
| read.md | ||
| README.md | ||
| write.md | ||
BCQuality global skills
This folder contains the skills that are not owned by any single layer. There are two kinds:
- The entry-point skill — the first skill an agent invokes at runtime.
- The three meta-skill contracts — stable references that define what the rest of BCQuality means.
The entry-point skill
| File | Role |
|---|---|
entry.md |
ENTRY — Given a task context, returns a dispatch record naming the action skill(s) to invoke. The agent's first call when pointed at BCQuality. |
Routing logic lives in Entry, not in the orchestrator. An agent that knows only "invoke /skills/entry.md first" has enough to drive the rest of the repo.
The meta-skill contracts
| # | File | Role | Who reads it |
|---|---|---|---|
| 1 | read.md |
READ — Schema + Use. How to read a knowledge file: frontmatter fields, section semantics, matching rules, layer precedence, conflict resolution. | Any agent or action skill that consumes knowledge files. |
| 2 | do.md |
DO — Action Skill contract. The Source → Relevance → Worklist → Action template and the structured output every action skill produces. Includes super-skill composition. | Any agent invoking an action skill; every action-skill author. |
| 3 | write.md |
WRITE — New Knowledge. Authoring rules for knowledge files. Defers to read.md for the schema. |
Contributors (human or agent) adding or editing knowledge files. Not used during consumption. |
READ and DO are read on demand — typically by the first action skill the agent executes after dispatch. They are not prerequisites for invoking Entry. WRITE is only used when scaffolding new content.
These contracts are stable. Changes require a PR approved by both maintainers.
For the end-to-end flow — from orchestrator trigger through to findings integration — see ../agent-consumption.md. For the high-level project framing, see ../README.md.