Improve PR-review parity: suggestion blocks, missing KB articles, privacy cross-ref

Adds the contract field, skill instructions, and two knowledge articles
that BCAppsBCQuality's PR-review agent needs to match (and exceed) the
coverage of the embedded review agent in BCAppsCampAIRHack:

skills/do.md
- New optional findings[].suggested-code field. Documents what it MUST
  contain (a literal line-replacement payload) and when to emit it.

microsoft/skills/review/al-code-review.md
- Instructs both the agent self-review pass and rolled-up sub-skill
  findings to populate suggested-code when the fix is mechanical.
- Lists examples (dead code removal, Count > 0 -> IsEmpty, object-scope
  Label) that map to issues observed in the parity comparison.

microsoft/knowledge/style/telemetry-event-id-stable-unique.{md,bad.al,good.al}
- New knowledge article: telemetry event IDs must be stable, unique,
  and non-placeholder. Closes a gap surfaced by the parity comparison.

microsoft/knowledge/style/labels-declared-at-object-scope.{md,bad.al,good.al}
- New knowledge article: Labels must live in the object-level var
  block, not in procedure-local var blocks. Closes the second gap.

microsoft/knowledge/privacy/no-pii-in-telemetry-message-string.md
- Adds an explicit note that changing DataClassification alone does not
  make embedding PII into the message string acceptable, plus links to
  the two adjacent privacy articles. Resolves the privacy advice the
  parity comparison flagged as ambiguous.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Jesper Schulz-Wedde 2026-05-27 15:45:49 +02:00
parent 4d59fb73bc
commit b11f3ec506
9 changed files with 130 additions and 1 deletions

View file

@ -94,7 +94,8 @@ Every action skill emits a single JSON document that conforms to this schema:
{ "path": "string", "sha": "string" }
],
"confidence": "high | medium | low",
"from-sub-skill": "string"
"from-sub-skill": "string",
"suggested-code": "string"
}
],
"suppressed": [
@ -168,6 +169,8 @@ The first reference is the **primary** reference: the knowledge file the finding
**`findings[].from-sub-skill`** — optional. Set only by super-skills. The `skill.id` of the sub-skill that produced the finding, or the literal string `"agent"` for an agent finding the super-skill produced from its own reasoning. Absent on findings produced directly by a leaf skill.
**`findings[].suggested-code`** — optional. A concrete code-replacement payload for the lines indicated by `location`. When present, the string MUST be a literal replacement for the source lines covered by `location.line` (or `location.range` if set) — i.e., what the file would contain after the fix, with no surrounding diff markers, fences, or commentary. Consumers MAY render it as a one-click suggestion in the delivery surface (for example, a GitHub ```` ```suggestion ```` block). Emit `suggested-code` only when the fix is small, mechanical, and unambiguous; omit it when the appropriate fix depends on context the skill cannot determine. The `suggested-code` payload supplements `message`; it does not replace the explanation in `message`.
**`suppressed`** — MUST list every knowledge file that was discarded due to layer precedence or consumer configuration, whenever that file would otherwise have contributed to the worklist. Each entry contains:
- `reference` — the suppressed file (same object shape as `findings[].references`).