Allow leaf sub-skills to emit agent findings within their domain

The original DO contract pinned all agent reasoning to the super-skill:
'Agent findings are emitted only by super-skills... Leaf sub-skills MUST
NOT emit agent findings'. This funnels all agent reasoning across all 6
domains through a single super-skill pass, which is the root structural
cause of the attention dilution we have been chasing in BCAppsBCQuality
PRs #28 and #30:

- T1 standalone run showed al-security-review finds rimd-on-read-only
  cleanly when run alone, but emits zero agent findings because the
  contract forbids it. So obvious things like case-without-else (no
  matching KB article yet) get dropped on the floor.
- The al-code-review self-review pass keeps producing 0-1 agent findings
  per PR because it is asked to reason across 6 domains in one pass.

The fix is to move agent reasoning into the leaves, bounded by each
leaf's domain. Each leaf now has both knowledge-backed and agent-finding
permissions within its own scope; the super-skill self-review pass
becomes a smaller, cross-cutting role.

skills/do.md
  - Replace the 'only by super-skills' / 'MUST NOT' clause with a
    two-tier model: leaf sub-skills MAY emit agent findings strictly
    within their declared domain; super-skills MAY emit agent findings
    for cross-cutting concerns that span domains.
  - Update the encoding rules: leaf agent findings have references:[]
    and an agent:-prefixed id, no from-sub-skill (the leaf's own report
    carries the finding under its own skill.id). Super-skills set
    from-sub-skill='agent' for their own self-review findings; when
    rolling up leaf agent findings, they set from-sub-skill=<leaf-id>.
  - Clarify that 'MUST validate against knowledge' applies to super-
    skill self-review candidates only - leaves already validated within
    their domain when they decided to emit.

microsoft/skills/review/al-{security,performance,privacy,style,upgrade,
                                                            ui}-review.md
  - New paragraph after the confidence rules instructing each leaf to
    surface domain-specific agent findings when no knowledge file
    covers a defect the agent recognises from general AL knowledge.
  - Bound the scope: 'The scope is strictly <domain>; defects outside
    this domain belong to other leaves and MUST NOT be emitted here.'
  - Same validation requirement: check the worklist for a matching
    knowledge file first; if one exists, upgrade to a knowledge-backed
    finding instead.

microsoft/skills/review/al-code-review.md
  - Rewrite the 'Agent self-review pass' subsection. The pass is now
    explicitly for cross-cutting concerns that no single leaf could
    have surfaced because they span multiple domains. Domain-specific
    reasoning belongs in the leaves, not duplicated here.
  - Update the rollup behavior to acknowledge leaf-emitted agent
    findings: they are rolled up like any other sub-skill finding, with
    from-sub-skill set to the leaf id, and are not re-validated by the
    super-skill (the leaf already validated within its own domain).
  - Drop the 'Leaf sub-skills MUST NOT emit agent findings' line.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Jesper Schulz-Wedde 2026-05-28 11:42:38 +02:00
parent 832504d428
commit 3a07ee82d2
8 changed files with 29 additions and 12 deletions

View file

@ -59,6 +59,8 @@ Set `confidence` to:
- `medium` when detection relies on heuristics or when any frontmatter dimension was `unknown`.
- `low` when the finding is an advisory derived only from applicability.
After evaluating each worklist entry, also consider whether the diff exhibits a style defect the agent recognises from its general AL knowledge that no knowledge file in the worklist covers. Such candidates are agent findings within this skill's domain — emit them with `references: []`, an `id` slug prefixed with `agent:`, `confidence` capped at `medium`, and a `message` that is self-contained (describing both the issue and a concrete recommendation, since there is no knowledge-file footer for the consumer to fall back on). The scope is strictly style; defects outside this domain belong to other leaves and MUST NOT be emitted here. Before emitting, check the worklist for a knowledge file that matches the candidate — if one exists, upgrade the candidate to a knowledge-backed finding instead. See `skills/do.md` for the full contract.
When the knowledge file ships an unambiguous `.good.al` companion that names exactly the correction the finding requires (and the diff context makes the substitution mechanical), set `findings[].suggested-code` to the literal replacement for the source lines indicated by `location`. The payload must be a verbatim replacement — no diff markers, no fences, no commentary — that the consumer can render as a one-click suggestion. Skip the field when the appropriate fix depends on context the skill cannot determine, or when more than one defensible replacement exists. See `skills/do.md` for the full contract.
Outcome selection: