mirror of
https://github.com/microsoft/BCQuality.git
synced 2026-08-06 09:26:52 +01:00
Emit human-readable domain label on review findings (#54)
* Emit human-readable domain label on review findings Add an optional findings[].domain field to the DO review output contract so each finding carries its own human-readable review-domain display label. Leaf review skills set it on every finding they emit; the al-code-review super-skill copies it verbatim during rollup and sets it to "Agent" for its own cross-cutting agent findings. This decouples consumers from BCQuality's domain taxonomy: they render finding.domain verbatim instead of maintaining a sub-skill-id -> label map. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Define domain display-label constraints Clarify that review domains may contain internal whitespace, punctuation, case-sensitive text, and non-ASCII characters. Require consumers to preserve and safely encode the complete label instead of relying on lossy slugs, matching the replacement BC-ALAgents consumer. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 77d0a40e-8bf5-40ac-a450-40eb0255db03 --------- Co-authored-by: Jesper Schulz-Wedde <jesper.schulzwedde@microsoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Jesper Schulz-Wedde
GitHub
parent
809af9708e
commit
ae04938c03
19 changed files with 91 additions and 56 deletions
|
|
@ -21,7 +21,7 @@ flowchart LR
|
|||
E -->|3 dispatch record| A
|
||||
A -->|4 invoke dispatched skill| S[Action skill<br/>e.g. al-code-review]
|
||||
S -->|5 execute| P[Source → Relevance<br/>→ Worklist → Action<br/>reading READ · DO on demand]
|
||||
P -->|6 emit| R[Findings · References<br/>· Confidence]
|
||||
P -->|6 emit| R[Findings · Domain labels<br/>· References · Confidence]
|
||||
R -->|7 integrate| O
|
||||
```
|
||||
|
||||
|
|
@ -65,6 +65,7 @@ The output contract is defined in the DO meta-skill so that every action skill
|
|||
|
||||
- **Outcome** — `completed`, `not-applicable`, `no-knowledge`, `partial`, or `failed`. An orchestrator can distinguish a clean run from a no-op from a failure without guessing.
|
||||
- **Findings** — what the skill observed (severity, message, optional location).
|
||||
- **Domain** — the producer-owned, human-readable display label on each review finding.
|
||||
- **References** — structured objects (`path` plus optional commit `sha`) pointing to the knowledge files that informed each finding.
|
||||
- **Confidence** — per-finding evidence strength.
|
||||
- **Suppressed** — knowledge files that were discarded by layer precedence or configuration, so reviewers can see what was overridden.
|
||||
|
|
@ -78,12 +79,12 @@ The orchestrator turns findings into PR comments, build gates, or IDE diagnostic
|
|||
|
||||
BCQuality is an **additive** knowledge layer. The agent surfaces two kinds of findings, both shaped to the same DO output contract:
|
||||
|
||||
- **Knowledge-backed findings** carry one or more entries in `references[]` pointing at BCQuality knowledge files. Their `id` is the primary file's repo-relative path. These are produced by leaf sub-skills and rolled up by super-skills.
|
||||
- **Agent findings** are surfaced by a super-skill from its own self-review pass when no BCQuality knowledge file backs the concern. They are tagged with `from-sub-skill: "agent"`, carry an empty `references: []`, use a slug `id` prefixed `agent:`, and have `confidence` capped at `medium`. Their `message` is self-contained because there is no knowledge-file footer to fall back on.
|
||||
- **Knowledge-backed findings** carry one or more entries in `references[]` pointing at BCQuality knowledge files. Their `id` is the primary file's repo-relative path. Leaf sub-skills set `domain` to their human-readable display label, and super-skills preserve it verbatim during rollup.
|
||||
- **Agent findings** carry an empty `references: []`, use a slug `id` prefixed `agent:`, and have `confidence` capped at `medium`. A leaf can emit one strictly within its own domain and uses that leaf's display label. A super-skill can emit a cross-cutting agent finding with `from-sub-skill: "agent"` and `domain: "Agent"`. Their `message` is self-contained because there is no knowledge-file footer to fall back on.
|
||||
|
||||
Before a super-skill emits an agent finding, it validates the candidate against the BCQuality knowledge already loaded for the task: a matching file upgrades the candidate to a knowledge-backed finding (and merges or deduplicates against the relevant sub-skill output); a contradicting file suppresses the candidate. Only candidates with no BCQuality coverage become agent findings.
|
||||
Before a skill emits an agent finding, it validates the candidate against the BCQuality knowledge already loaded for the task: a matching file upgrades the candidate to a knowledge-backed finding (and merges or deduplicates against relevant existing output); a contradicting file suppresses the candidate. Only candidates with no BCQuality coverage become agent findings.
|
||||
|
||||
Orchestrators MAY render the two kinds differently — for example, by labelling agent findings or routing them to a separate review domain — and MAY apply independent severity floors. The `from-sub-skill: "agent"` marker is the contract.
|
||||
Orchestrators MUST tolerate an absent `domain` in reports from older producers. When it is present, treat it as display text rather than an identifier: preserve the full string and its case, whitespace, punctuation, and non-ASCII characters, escaping only for the target rendering format. Do not tokenize it on spaces or use a lowercased or slugified form as the sole metadata or deduplication key, because distinct labels can collapse to the same slug. Retain the exact string, use a lossless encoding, or use a collision-resistant digest instead. Orchestrators MAY render knowledge-backed and agent findings differently and MAY apply independent severity floors; `references: []` and the `agent:` id prefix distinguish agent findings, while `from-sub-skill: "agent"` identifies those emitted by the super-skill itself.
|
||||
|
||||
## Why this architecture
|
||||
|
||||
|
|
|
|||
|
|
@ -82,7 +82,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. A populated example:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"AppSource"`. A populated example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -105,6 +105,7 @@ Output conforms to the DO output contract. A populated example:
|
|||
{ "path": "microsoft/knowledge/appsource/object-affixes-prevent-collisions.md" }
|
||||
],
|
||||
"confidence": "high",
|
||||
"domain": "AppSource",
|
||||
"suggested-code": "field(50100; \"Loyalty Points ABC\"; Integer)"
|
||||
}
|
||||
],
|
||||
|
|
|
|||
|
|
@ -77,7 +77,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. A populated example:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Breaking Changes"`. A populated example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -100,7 +100,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/breaking-changes/do-not-change-published-procedure-signatures.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Breaking Changes"
|
||||
},
|
||||
{
|
||||
"id": "microsoft/knowledge/breaking-changes/choose-access-modifiers-deliberately.md",
|
||||
|
|
@ -113,7 +114,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/breaking-changes/choose-access-modifiers-deliberately.md" }
|
||||
],
|
||||
"confidence": "medium"
|
||||
"confidence": "medium",
|
||||
"domain": "Breaking Changes"
|
||||
}
|
||||
],
|
||||
"suppressed": []
|
||||
|
|
|
|||
|
|
@ -76,7 +76,7 @@ For each sub-skill in the worklist, executed one at a time per the discipline ab
|
|||
1. Invoke the sub-skill with the orchestrator's inputs, passing only the subset each sub-skill declares in its `inputs`.
|
||||
2. Capture the sub-skill's complete findings-report verbatim and append it to `sub-results`.
|
||||
3. If the sub-skill's `outcome` is `failed`, stop here for this sub-skill: its findings are not reliable per the DO contract and MUST NOT be copied into the super-skill's top-level `findings[]` or counted in `summary.counts`.
|
||||
4. Otherwise, append each entry from the sub-skill's `findings[]` to the super-skill's top-level `findings[]`, setting `from-sub-skill` to the sub-skill's `skill.id`. For non-citation findings (those whose `id` is a skill-defined slug rather than a reference path), prefix `id` with `<from-sub-skill>:` to prevent collisions across sub-skills. Other finding fields are preserved.
|
||||
4. Otherwise, append each entry from the sub-skill's `findings[]` to the super-skill's top-level `findings[]`, setting `from-sub-skill` to the sub-skill's `skill.id` and preserving each finding's optional `domain` field verbatim, including its absence. For non-citation findings (those whose `id` is a skill-defined slug rather than a reference path), prefix `id` with `<from-sub-skill>:` to prevent collisions across sub-skills. Other finding fields are preserved.
|
||||
|
||||
### Agent self-review pass
|
||||
|
||||
|
|
@ -89,11 +89,12 @@ Frame the pass by cross-cutting concerns — architecture, error handling, resou
|
|||
For every candidate the agent identifies in this pass:
|
||||
|
||||
1. **Validate against BCQuality knowledge.** Check the candidate against the knowledge files the sub-skills have already loaded for this task (visible via their `references` and `suppressed` lists in `sub-results`).
|
||||
- If a BCQuality knowledge file matches the candidate, upgrade it to a knowledge-backed finding: cite the file in `references`, set `id` to the file's path, set `from-sub-skill` to the sub-skill that owns that knowledge domain, and merge with or deduplicate against any sub-skill finding that already covers the same concern at the same location.
|
||||
- If a BCQuality knowledge file matches the candidate, upgrade it to a knowledge-backed finding: cite the file in `references`, set `id` to the file's path, set `from-sub-skill` to the sub-skill that owns that knowledge domain, set `domain` to the human-readable label required by that sub-skill's Output contract, and merge with or deduplicate against any sub-skill finding that already covers the same concern at the same location.
|
||||
- If a BCQuality knowledge file **explicitly contradicts** the candidate (its `## Best Practice` or `## Anti Pattern` says the opposite of what the agent flagged), suppress the candidate and do not surface it.
|
||||
- Otherwise the candidate has no BCQuality coverage; emit it as a super-skill agent finding.
|
||||
2. **Emit agent finding.** Per DO's *Agent findings* rules:
|
||||
- `from-sub-skill: "agent"` (the super-skill itself produced it)
|
||||
- `domain: "Agent"` (the display label for super-skill cross-cutting findings)
|
||||
- `references: []`
|
||||
- `id` is a skill-defined slug prefixed with `agent:` (for example, `agent:missing-error-handling-on-http-call`).
|
||||
- `confidence` capped at `medium`.
|
||||
|
|
@ -143,7 +144,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip
|
|||
{ "path": "microsoft/knowledge/performance/apply-filters-before-iterating.md" }
|
||||
],
|
||||
"confidence": "high",
|
||||
"from-sub-skill": "al-performance-review"
|
||||
"from-sub-skill": "al-performance-review",
|
||||
"domain": "Performance"
|
||||
},
|
||||
{
|
||||
"id": "microsoft/knowledge/performance/use-setloadfields-for-partial-records.md",
|
||||
|
|
@ -157,7 +159,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip
|
|||
{ "path": "microsoft/knowledge/performance/use-setloadfields-for-partial-records.md" }
|
||||
],
|
||||
"confidence": "high",
|
||||
"from-sub-skill": "al-performance-review"
|
||||
"from-sub-skill": "al-performance-review",
|
||||
"domain": "Performance"
|
||||
},
|
||||
{
|
||||
"id": "microsoft/knowledge/security/secrettext-for-credentials.md",
|
||||
|
|
@ -172,7 +175,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip
|
|||
{ "path": "microsoft/knowledge/security/secrettext-for-credentials.md" }
|
||||
],
|
||||
"confidence": "high",
|
||||
"from-sub-skill": "al-security-review"
|
||||
"from-sub-skill": "al-security-review",
|
||||
"domain": "Security"
|
||||
},
|
||||
{
|
||||
"id": "microsoft/knowledge/security/secrets-isolated-storage.md",
|
||||
|
|
@ -186,7 +190,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip
|
|||
{ "path": "microsoft/knowledge/security/secrets-isolated-storage.md" }
|
||||
],
|
||||
"confidence": "medium",
|
||||
"from-sub-skill": "al-security-review"
|
||||
"from-sub-skill": "al-security-review",
|
||||
"domain": "Security"
|
||||
},
|
||||
{
|
||||
"id": "agent:missing-error-handling-on-http-client",
|
||||
|
|
@ -199,7 +204,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip
|
|||
},
|
||||
"references": [],
|
||||
"confidence": "medium",
|
||||
"from-sub-skill": "agent"
|
||||
"from-sub-skill": "agent",
|
||||
"domain": "Agent"
|
||||
}
|
||||
],
|
||||
"suppressed": [],
|
||||
|
|
@ -224,7 +230,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/performance/apply-filters-before-iterating.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Performance"
|
||||
},
|
||||
{
|
||||
"id": "microsoft/knowledge/performance/use-setloadfields-for-partial-records.md",
|
||||
|
|
@ -237,7 +244,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/performance/use-setloadfields-for-partial-records.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Performance"
|
||||
}
|
||||
],
|
||||
"suppressed": []
|
||||
|
|
@ -262,7 +270,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/security/secrettext-for-credentials.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Security"
|
||||
},
|
||||
{
|
||||
"id": "microsoft/knowledge/security/secrets-isolated-storage.md",
|
||||
|
|
@ -275,7 +284,8 @@ Output conforms to the DO output contract, extended with `sub-results` and `skip
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/security/secrets-isolated-storage.md" }
|
||||
],
|
||||
"confidence": "medium"
|
||||
"confidence": "medium",
|
||||
"domain": "Security"
|
||||
}
|
||||
],
|
||||
"suppressed": []
|
||||
|
|
|
|||
|
|
@ -85,7 +85,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. A populated example:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Data Modeling"`. A populated example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -108,6 +108,7 @@ Output conforms to the DO output contract. A populated example:
|
|||
{ "path": "microsoft/knowledge/data-modeling/set-last-date-modified-in-onmodify-and-onrename.md" }
|
||||
],
|
||||
"confidence": "high",
|
||||
"domain": "Data Modeling",
|
||||
"suggested-code": "trigger OnRename()\nbegin\n \"Last Date Modified\" := Today();\nend;"
|
||||
}
|
||||
],
|
||||
|
|
|
|||
|
|
@ -78,7 +78,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. A populated example:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Error Handling"`. A populated example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -101,7 +101,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/error-handling/prefer-errorinfo-for-actionable-errors.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Error Handling"
|
||||
},
|
||||
{
|
||||
"id": "microsoft/knowledge/error-handling/errortype-internal-vs-client-for-diagnostics.md",
|
||||
|
|
@ -114,7 +115,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/error-handling/errortype-internal-vs-client-for-diagnostics.md" }
|
||||
],
|
||||
"confidence": "medium"
|
||||
"confidence": "medium",
|
||||
"domain": "Error Handling"
|
||||
}
|
||||
],
|
||||
"suppressed": []
|
||||
|
|
|
|||
|
|
@ -96,7 +96,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. A populated example:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Events"`. A populated example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -119,7 +119,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/events/publish-thin-onbefore-onafter-integration-events.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Events"
|
||||
},
|
||||
{
|
||||
"id": "microsoft/knowledge/events/use-ishandled-to-make-base-behaviour-overridable.md",
|
||||
|
|
@ -132,7 +133,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/events/use-ishandled-to-make-base-behaviour-overridable.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Events"
|
||||
}
|
||||
],
|
||||
"suppressed": []
|
||||
|
|
|
|||
|
|
@ -85,7 +85,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. A populated example:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Interfaces"`. A populated example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -108,7 +108,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/interfaces/prefer-interface-over-case-branching.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Interfaces"
|
||||
},
|
||||
{
|
||||
"id": "microsoft/knowledge/interfaces/set-defaultimplementation-on-enum.md",
|
||||
|
|
@ -121,7 +122,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/interfaces/set-defaultimplementation-on-enum.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Interfaces"
|
||||
}
|
||||
],
|
||||
"suppressed": []
|
||||
|
|
|
|||
|
|
@ -85,7 +85,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. A populated example:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Performance"`. A populated example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -108,7 +108,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/performance/apply-filters-before-iterating.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Performance"
|
||||
},
|
||||
{
|
||||
"id": "microsoft/knowledge/performance/use-setloadfields-for-partial-records.md",
|
||||
|
|
@ -121,7 +122,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/performance/use-setloadfields-for-partial-records.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Performance"
|
||||
}
|
||||
],
|
||||
"suppressed": []
|
||||
|
|
|
|||
|
|
@ -79,7 +79,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. A populated example:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Privacy"`. A populated example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -102,7 +102,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/privacy/data-classification-required-on-pii-fields.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Privacy"
|
||||
}
|
||||
],
|
||||
"suppressed": []
|
||||
|
|
|
|||
|
|
@ -77,7 +77,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. A populated example:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Security"`. A populated example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -100,7 +100,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/security/secrettext-for-credentials.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Security"
|
||||
},
|
||||
{
|
||||
"id": "microsoft/knowledge/security/secrets-isolated-storage.md",
|
||||
|
|
@ -113,7 +114,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/security/secrets-isolated-storage.md" }
|
||||
],
|
||||
"confidence": "medium"
|
||||
"confidence": "medium",
|
||||
"domain": "Security"
|
||||
}
|
||||
],
|
||||
"suppressed": []
|
||||
|
|
|
|||
|
|
@ -77,7 +77,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. A populated example:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Style"`. A populated example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -99,7 +99,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/style/label-suffix-approved-list.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Style"
|
||||
}
|
||||
],
|
||||
"suppressed": []
|
||||
|
|
|
|||
|
|
@ -77,7 +77,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. The empty-corpus case produces:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Telemetry"`. The empty-corpus case produces:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
|
|||
|
|
@ -84,7 +84,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. A populated example:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Testing"`. A populated example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -107,6 +107,7 @@ Output conforms to the DO output contract. A populated example:
|
|||
{ "path": "microsoft/knowledge/testing/asserterror-needs-expectederror-and-code.md" }
|
||||
],
|
||||
"confidence": "high",
|
||||
"domain": "Testing",
|
||||
"suggested-code": "asserterror PostInvalidOrder();\nAssert.ExpectedError(ExpectedPostingErr);"
|
||||
}
|
||||
],
|
||||
|
|
|
|||
|
|
@ -77,7 +77,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. A populated example:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Accessibility"`. A populated example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -99,7 +99,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/ui/show-caption-on-editable-fields.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Accessibility"
|
||||
}
|
||||
],
|
||||
"suppressed": []
|
||||
|
|
|
|||
|
|
@ -80,7 +80,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. A populated example:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Upgrade"`. A populated example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -102,7 +102,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/upgrade/enum-values-additive-at-end.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Upgrade"
|
||||
}
|
||||
],
|
||||
"suppressed": []
|
||||
|
|
|
|||
|
|
@ -80,7 +80,7 @@ Outcome selection:
|
|||
|
||||
## Output
|
||||
|
||||
Output conforms to the DO output contract. A populated example:
|
||||
Output conforms to the DO output contract. Every finding this skill emits MUST set `findings[].domain` to `"Web Services"`. A populated example:
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -103,7 +103,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/web-services/set-required-api-page-properties.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Web Services"
|
||||
},
|
||||
{
|
||||
"id": "microsoft/knowledge/web-services/expose-systemid-as-the-api-key.md",
|
||||
|
|
@ -116,7 +117,8 @@ Output conforms to the DO output contract. A populated example:
|
|||
"references": [
|
||||
{ "path": "microsoft/knowledge/web-services/expose-systemid-as-the-api-key.md" }
|
||||
],
|
||||
"confidence": "high"
|
||||
"confidence": "high",
|
||||
"domain": "Web Services"
|
||||
}
|
||||
],
|
||||
"suppressed": []
|
||||
|
|
|
|||
|
|
@ -64,10 +64,10 @@ plugin-root environment variable, prefer it.
|
|||
file and execute its Source → Relevance → Worklist → Action steps, reading
|
||||
`PLUGIN_ROOT/skills/read.md` and `PLUGIN_ROOT/skills/do.md` on demand.
|
||||
|
||||
4. **Emit findings.** Produce the rolled-up findings report in the DO output contract
|
||||
(`outcome`, `findings`, `references`, `confidence`, `suppressed`). Do not invent a
|
||||
different shape; downstream consumers parse the DO contract without skill-specific
|
||||
logic.
|
||||
4. **Emit findings.** Produce the rolled-up findings report in the DO output contract,
|
||||
including each review finding's producer-supplied `domain` label (`outcome`,
|
||||
`findings`, `references`, `confidence`, `suppressed`). Do not invent a different
|
||||
shape; downstream consumers parse the DO contract without skill-specific logic.
|
||||
|
||||
If Entry returns `no-match` or `failed`, return the dispatch record unchanged so the
|
||||
caller can log the reason.
|
||||
|
|
|
|||
|
|
@ -95,6 +95,7 @@ Every action skill emits a single JSON document that conforms to this schema:
|
|||
],
|
||||
"confidence": "high | medium | low",
|
||||
"from-sub-skill": "string",
|
||||
"domain": "string",
|
||||
"suggested-code": "string",
|
||||
"suggested-code-omission-reason": "string"
|
||||
}
|
||||
|
|
@ -189,6 +190,10 @@ 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 cross-cutting reasoning. Absent on findings emitted directly by a leaf skill — including agent findings the leaf emits within its own domain, which appear in the leaf's own report without this field.
|
||||
|
||||
**`findings[].domain`** — optional in the shared schema for backward compatibility and for non-review findings. It is a short, human-readable display label for the review domain that produced the finding (for example, `Security`, `Breaking Changes`, `API & Web Services`). A review leaf skill MUST set it on every finding it emits. The value MUST be a non-empty, single-line string with no leading or trailing whitespace or control characters. Internal whitespace, punctuation, case, and non-ASCII characters are valid and significant.
|
||||
|
||||
A review super-skill MUST preserve `domain` verbatim when rolling a leaf finding into its top-level `findings[]`, including preserving its absence from older producers, and MUST set it to `"Agent"` for agent findings it emits about cross-cutting concerns. Consumers MUST tolerate its absence. When rendering a present value, consumers MUST preserve the complete display text, escaping only as required by the output format; they MUST NOT split it on whitespace or restrict it to identifier characters. `domain` is display text, not a stable machine identifier. If a consumer embeds it in metadata or uses it in a deduplication key, it MUST retain the exact string, use a lossless encoding, or use a collision-resistant digest; it MUST NOT rely on lowercasing or lossy slugification as the sole identity.
|
||||
|
||||
**`findings[].suggested-code`** — optional in the schema but **expected for mechanical findings**. It is 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` whenever the fix is small, local, and mechanical: deleting unreachable code; replacing one expression (`Count() > 0` → `not IsEmpty()`); moving a local `Label` to object scope; adding a missing property such as `ToolTip`, `OptionCaption`, or `DataClassification`; replacing a string-concatenated `Error` with a Label-backed call; changing a permission token; or adding a missing `else`/guard branch whose replacement is unambiguous from the surrounding diff. When a `.good.al` companion exists and the diff context matches the `.bad.al` shape, prefer adapting the `.good.al` replacement into `suggested-code`.
|
||||
|
|
@ -226,7 +231,7 @@ The five required sections still apply. Their meaning shifts from knowledge file
|
|||
- `## Source` — names the sub-skills invoked (mirrors `sub-skills` in frontmatter).
|
||||
- `## Relevance` — rules for deciding which sub-skills apply to the current task. A sub-skill is relevant when its declared `inputs` are satisfied by the orchestrator's provided inputs and the orchestrator has not disabled it via configuration. The super-skill MUST NOT filter sub-skills by task content (for example, by inspecting the diff or the file). Task-level applicability is the sub-skill's own responsibility; sub-skills signal non-applicability by returning `outcome: "not-applicable"` or `outcome: "no-knowledge"`.
|
||||
- `## Worklist` — the final list of sub-skills to invoke; the rest go to `skipped-sub-skills`.
|
||||
- `## Action` — invoke each worklisted sub-skill with the appropriate subset of inputs, collect its findings-report verbatim into `sub-results`, and copy its `findings[]` into the super-skill's top-level `findings[]` with `from-sub-skill` set. Findings from a sub-skill with `outcome: "failed"` MUST NOT be copied into the super-skill's top-level `findings[]` and MUST NOT contribute to the super-skill's `summary.counts` (their report is still preserved in `sub-results` for traceability, consistent with DO's rule that consumers ignore a failed skill's findings).
|
||||
- `## Action` — invoke each worklisted sub-skill with the appropriate subset of inputs, collect its findings-report verbatim into `sub-results`, and copy its `findings[]` into the super-skill's top-level `findings[]` with `from-sub-skill` set. All finding fields, including the optional `domain`, are preserved verbatim unless this contract explicitly requires a transformation. Findings from a sub-skill with `outcome: "failed"` MUST NOT be copied into the super-skill's top-level `findings[]` and MUST NOT contribute to the super-skill's `summary.counts` (their report is still preserved in `sub-results` for traceability, consistent with DO's rule that consumers ignore a failed skill's findings).
|
||||
- `## Output` — the super-skill's output contract, including `sub-results` and, if any, `skipped-sub-skills`.
|
||||
|
||||
### Outcome rollup
|
||||
|
|
@ -288,5 +293,3 @@ Conforms to the DO output contract.
|
|||
## How orchestrators consume output
|
||||
|
||||
An orchestrator invokes an action skill with an input appropriate to the skill's declared `inputs`, receives the JSON output, and maps findings to its delivery surface (PR comments, build gates, IDE diagnostics). The orchestrator MUST NOT interpret skill-specific fields beyond the schema above. Skills that need richer semantics MUST encode them within the schema (for example, by adding structured `message` text) rather than extending the output shape.
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue