Clarify SR vs preview channel mapping in dependency-flow skill

[PureWeen]

Note

Are you waiting for the changes in this PR to be merged?
It would be very helpful if you could test the resulting artifacts from this PR and let us know in a comment if this change resolves your issue. Thank you!

Description

Clarifies the SR vs preview channel mapping rules in the dependency-flow skill so future agent runs don't invent non-existent channel names.

Background

While answering a question about the darc command to add release/10.0.1xx-sr7 to the maestro feed, the agent initially looked for a SR-specific channel. There isn't one — every release/X.0.Yxx-srN MAUI branch maps to the single general .NET X.0.Yxx SDK channel. Only -previewN branches get dedicated per-preview channels (e.g., release/11.0.1xx-preview3 → .NET 11.0.1xx SDK Preview 3).

Verified via darc get-default-channels --source-repo https://github.com/dotnet/maui:

• All of release/9.0.1xx-sr1 … release/9.0.1xx-sr12 → .NET 9.0.1xx SDK
• All of release/10.0.1xx-sr1 … release/10.0.1xx-sr6 → .NET 10.0.1xx SDK
• release/11.0.1xx-preview3 → .NET 11.0.1xx SDK Preview 3
• release/11.0.1xx-preview4 → .NET 11.0.1xx SDK Preview 4

Changes

Updates .github/skills/dependency-flow/SKILL.md:

1. Branch → channel mapping rules — explicit rules for SR, preview, and main/dev branches, with a "do not invent" guard against fabricating SR-specific channels.
2. Verification step — tells the agent to always run darc get-default-channels --source-repo … and copy a sibling branch's channel exactly before constructing a command.
3. Worked example — adds the canonical darc add-default-channel invocation for a new SR branch.

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.sh | bash -s -- 35529

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/dotnet/maui/main/eng/scripts/get-maui-pr.ps1) } 35529"

[github-actions]

🔍 Skill Validation Results

✅ Static Checks Passed

Skills checked: 17 | Agents checked: 4

Full validator output

Found 1 skill(s)
[dependency-flow] 📊 dependency-flow: 2,620 BPE tokens [chars/4: 2,528] (standard ~), 33 sections, 5 code blocks
[dependency-flow]    ⚠  Skill is 2,620 BPE tokens (chars/4 estimate: 2,528) — approaching "comprehensive" range where gains diminish.
✅ All checks passed (1 skill(s))
Found 4 agent(s)
Validated 4 agent(s)

✅ All checks passed (4 agent(s))

⏭️ LLM Evaluation: Skipped

No changed skills with eval tests found.

🔍 Full results and investigation steps

[PureWeen]

Adversarial PR Review

Methodology: 3 independent reviewers with adversarial consensus follow-up.

The core change is correct: factual claims about release/X.0.Yxx-srN → general SDK channel mapping and release/X.0.Yxx-previewN → per-preview channel mapping match the live darc output. The darc add-default-channel --channel --branch --repo flag set is right; the --source-repo vs --repo asymmetry between get-default-channels and add-default-channel is real darc CLI convention, not a typo. No security, regression, or correctness issues found.

Two small documentation refinements suggested inline.

CI Status

• ✅ Skill validation passed (static checks)
• ✅ All required gh-aw / safe-output / detection jobs green
• ⏭️ maui-pr Azure pipeline skipped — expected for a docs-only change under .github/skills/
• ⏳ Build Analysis is a tracking placeholder, not a required gate

Test Coverage

Not applicable — this is an agent-skill documentation change. The skill-validation workflow (which exercises skill structure and token counts) passed.

Prior Reviews

No existing human reviews. Two bot comments only (dogfood instructions, skill-validation results).

Consensus Summary

Finding	Severity	Consensus
Warning placed after add-default-channel code block	⚠️	2/3 (after dispute)
"Branch → channel mapping rules" framing implies exhaustive list; misses RC / inflight / point-sub-release branches	💡	3/3 facts agreed (after dispute, severity downgraded since the following verify-guardrail mitigates the worst case)
Unquoted --branch value (style)	—	discarded (style only)

[PureWeen]

⚠️ Documentation — The approval warning sits after the runnable darc add-default-channel code block. The existing "Promote a build" workflow in this same file (lines 156–159) puts the confirmation instruction before the bash fence, e.g.:

3. Show the user the command and wait for confirmation:

   darc add-build-to-channel ...

Moving the ⚠️ note above the code block would match that established pattern and removes the small risk that an agent which snippet-extracts the fenced command misses the gate (the top-level "explicit-confirmation" list at line 99 already covers the command globally, so this is consistency / belt-and-suspenders rather than a missing safety gate).

Flagged by: 2/3 reviewers (after dispute round).

[PureWeen]

💡 Documentation — Framing this as "Branch → channel mapping rules" reads as exhaustive, but dotnet/maui also ships branch shapes that aren't covered by the three bullets below:

• release/X.0.Yxx-rcN (e.g., release/10.0.1xx-rc1 / -rc2, release/9.0.1xx-rc1 / -rc2) — these get their own RC channels, not the general SDK channel.
• release/*-rc2.1 / release/*-preview6.1 point-sub-release branches.
• inflight/* and vendor-suffixed branches like release/10.0.1xx-meaipreview1.

The immediately-following "Always verify by listing existing mappings" guardrail (lines 44–48) already mitigates the worst-case failure — but reframing this heading as "common patterns (not exhaustive)" or adding an explicit RC bullet would close the gap for agents that read the rules block without internalizing the verify step.

Flagged by: 3/3 reviewers agreed on facts (after dispute round); severity downgraded from ⚠️ to 💡 since the verify guardrail mitigates.

[PureWeen]

Applied both review findings in 8bdac51:

1. ⚠️ Confirmation gate placement — moved the warning above the darc add-default-channel fenced block to match the pattern at lines 156–159 (the 'Promote a build' workflow), so snippet-extractors can't miss the gate.

2. 💡 RC and other branch shapes — reframed the bullet heading from 'Branch → channel mapping rules' to 'Common branch → channel patterns (not exhaustive — always verify with the command below)'. Added explicit coverage for:

   • RC release branches (release/X.0.Yxx-rcN → dedicated per-RC channels like .NET 10.0.1xx SDK RC 2, only active during the pre-release cycle)
   • Other shapes — point-sub-release (-rc2.1, -preview6.1), inflight/* mirrors, vendor-suffixed branches (e.g., release/10.0.1xx-meaipreview1)

   Verified the RC channels actually exist in BAR (e.g., .NET 10.0.1xx SDK RC 2 is channel ID 6577) — they just don't currently have active MAUI default-channel mappings because we're past RC for net9/net10.

The --source-repo vs --repo flag asymmetry between get-default-channels and add-default-channel left as-is — that's real darc CLI convention, not a typo.

[PureWeen]

Adversarial PR Review — Round 2

Methodology: 3 independent reviewers with adversarial consensus, refreshed against the latest commit (8bdac51).

Round 1 follow-up

Both round-1 findings are properly addressed:

• ✅ ⚠️ confirmation gate now sits above the darc add-default-channel bash fence (matches the "Promote a build" pattern in the same file).
• ✅ "Branch → channel mapping rules" reframed as "Common branch → channel patterns (not exhaustive)" with new RC bullet and "Other shapes" bullet covering -rc2.1/-preview6.1 point-sub-releases, inflight/* mirrors, and vendor-suffixed branches.

Verified against live data

I ran darc get-channels, darc get-default-channels --source-repo https://github.com/dotnet/maui, and git ls-remote to verify every empirical claim in the diff:

• ✅ .NET 10.0.1xx SDK RC 2 is a real channel (BAR ID 6577).
• ✅ All release/10.0.1xx-rc{1,2}, release/8.0.1xx-rc2.1 / -rc2.3, release/8.0.1xx-preview6.1, inflight/{current,ai,candidate}, and release/10.0.1xx-meaipreview1 branches exist in dotnet/maui.
• ✅ inflight/current has an active default channel mapping (→ .NET 10.0.1xx SDK); SR and preview claims confirmed.

Findings

One 💡 refinement on the round-2-added RC bullet. See inline comment.

CI Status

All required gates green or skipping-as-expected for a docs-only .github/skills/ change. maui-pr Azure pipeline skipping is expected. Build Analysis pending is a tracking placeholder, not a required gate.

Consensus Summary

Finding	Severity	Consensus
RC bullet's present-tense "map to" + sibling-find guidance can leave an agent without a verifiable sibling when MAUI has no active RC default mappings	💡	2/3 (merged from R1 phrasing + R2 logic-trap findings; severity taken from lower of the two)

No must-fix issues. The bullet is factually defensible (RC channels exist; mappings are temporary) and the surrounding guardrails mitigate the worst case, but tightening the wording would close the residual gap.

Prior reviews

My round-1 review is at #pullrequestreview-4330454121 — no other human reviews. Both round-1 findings are now resolved.

[PureWeen]

💡 Documentation — Two related observations on this RC bullet, both verified against live darc output:

1. Present-tense "map to" overstates current state. darc get-default-channels --source-repo https://github.com/dotnet/maui shows zero active RC default mappings right now (SR and preview entries are populated, RC rows are empty). The qualifier sentence ("only active during the corresponding pre-release cycle") explains why, but an agent skimming bullets may miss the qualifier.

2. The "find a previous RC sibling" guidance added at line 50 silently fails for RC. SR and preview siblings are findable in get-default-channels output; RC siblings are not (they're removed after each cycle). An agent that follows the verify-by-sibling guardrail for an RC branch outside an active cycle will get no result and has nothing in the skill telling it to stop rather than guess.

This isn't a blocker — the input-validation rule ("Channel names: Must match output from maestro_default_channels") catches a fabricated channel name before execution, and the add-default-channel explicit-confirmation gate ensures a human sees the proposed command. But a small wording tweak would close the residual gap:

RC release branches (release/X.0.Yxx-rcN) use dedicated per-RC channels (e.g., .NET 10.0.1xx SDK RC 2) only while their cycle is active — these default mappings are removed after the RC ships, so get-default-channels will show no RC sibling to copy from. If you can't find a sibling, stop and ask release engineering rather than guessing the channel name.

And correspondingly drop "the previous RC" from the sibling list at line 50 (or replace with the escalation hint above).

Flagged by: 2/3 reviewers (merged: R1 = phrasing certainty 💡, R2 = sibling-guardrail silent failure ❌; severity = 💡 per lower-of-the-two consensus rule). Targets content introduced in commit 8bdac51 in response to round-1 feedback — multi-round self-correction applied.

[PureWeen]

Round 2 finding applied in fd2ca2d.

Confirmed against live data: darc get-default-channels --source-repo https://github.com/dotnet/maui shows zero RC default mappings right now, so the round-1 phrasing ("map to") and the "previous RC" sibling hint were both subtly misleading.

Changes:

1. RC bullet: "map to" → "use ... only while their cycle is active", explicit note that mappings are removed post-ship, and a "stop and ask release engineering" escalation when no sibling can be found.
2. Verify step: dropped "the previous RC" from sibling examples, added a no-sibling escalation clause covering RC and other shapes that lack active mappings.

[PureWeen]

Adversarial PR Review — Round 3

Methodology: 3 independent reviewers with adversarial consensus, refreshed against fd2ca2db45.

Round 2 follow-up

✅ The round-2 finding is properly addressed:

• RC bullet at line 42 now makes the active-cycle dependency explicit and adds an escalation path.
• Sibling-find paragraph at line 50 drops "the previous RC" and adds the no-sibling escalation hint.
• Diff scope is clean — only the two intended lines changed (+2 / -2 vs. the round-2 head).

Verification against live data

• ✅ darc get-default-channels --source-repo https://github.com/dotnet/maui shows zero RC default mappings, consistent with the bullet's claim that they're "removed after the RC ships."
• ✅ All branch shapes still verified (release/10.0.1xx-rc{1,2}, inflight/*, release/10.0.1xx-meaipreview1, release/8.0.1xx-rc2.1, release/8.0.1xx-preview6.1).

Findings

One new ⚠️ surfaced by the round-3 wording. See inline comment.

CI Status

All required gates green or skipping-as-expected for a docs-only .github/skills/ change. No regressions vs. prior rounds.

Consensus Summary

Finding	Severity	Consensus
Escalation phrase "ask release engineering" is operationally undefined for an LLM agent and breaks the file's established "show/tell the user" pattern (lines 42 + 50)	⚠️	3/3 after dispute
"after the RC ships" timing imprecision (per-RC vs. at-GA)	—	discarded (1/3 after dispute — observable behavior is correctly described; mental-model nit only)

Prior reviews

Round 1 (#pullrequestreview-4330454121) and round 2 (#pullrequestreview-4330536253) findings are both fully addressed. Convergence is close — this is the only remaining substantive finding.

[PureWeen]

⚠️ Documentation — "ask release engineering" is operationally undefined for an LLM agent and breaks the file's own escalation convention. Same wording appears again at line 50.

Everywhere else this skill escalates, it tells the agent what to do with the user as the directly addressable principal:

• Line 56: "Show the user the exact command and wait for approval before running"
• Line 98: "Always show the user the exact command and wait for explicit approval before running"
• Line 144: "STOP — show the user the exact add-build-to-channel command and wait for explicit confirmation"
• Line 159: "Show the user the command and wait for confirmation"

The two new sentences (lines 42 and 50) say "stop and ask release engineering" — but the agent has no direct channel to release engineering. Plausible failure modes:

1. Agent halts silently without telling the user why.
2. Agent hallucinates having contacted someone ("I've asked release engineering and they said …").
3. Worst case: agent treats "ask" as the failed escape hatch and falls back to guessing the channel name — exactly the failure this PR is trying to guard against.

Suggested rewording, mirroring the file's pattern:

- If you can't find a sibling, stop and ask release engineering rather than guessing the channel name.
+ If you can't find a sibling, stop and tell the user to escalate to release engineering — do not guess the channel name.

And at line 50:

- stop and ask release engineering — do not guess the channel name.
+ stop and tell the user that release engineering needs to configure the channel mapping — do not guess the channel name.

Low risk, small wording change, closes the ambiguity gap on a safety-critical RC-branch path.

Flagged by: 3/3 reviewers after dispute round (R1=initial flag, R2+R3 follow-ups both AGREED at ⚠️). Targets content introduced in commit fd2ca2d in response to round-2 feedback — multi-round self-correction applied.

[PureWeen]

Round 3 finding applied in fdb1359.

Strong finding — 3/3 consensus and the reasoning is correct: the file's escalation convention everywhere else (lines 56, 98, 144, 159) is uniformly "show the user / tell the user" because the user is the only directly-addressable principal an LLM agent has. My round-2 phrase "ask release engineering" broke that pattern and could plausibly result in silent halt, hallucinated contact, or fallback-to-guessing.

Changes (suggestion applied verbatim):

• Line 42: stop and ask release engineering rather than guessing the channel name → stop and tell the user to escalate to release engineering — do not guess the channel name
• Line 50: stop and ask release engineering — do not guess the channel name → stop and tell the user that release engineering needs to configure the channel mapping — do not guess the channel name

[PureWeen]

Round 4 Review — Convergence

Verdict: Clean. No new findings.

Round-3 fix verification: Both occurrences of "ask release engineering" have been replaced with the "tell the user" escalation pattern that the rest of the file uses (lines 56, 98, 144, 159):

• Line 42 (RC bullet): "stop and tell the user to escalate to release engineering — do not guess the channel name."
• Line 50 (sibling-find): "stop and tell the user that release engineering needs to configure the channel mapping — do not guess the channel name."

The slight wording variance between the two is intentional and appropriate: line 42 is a quick-reference bullet; line 50 is the operational verify step.

Scope: Diff is exactly 2 insertions / 2 deletions in one file. No accidental edits.

End-to-end RC path: Agent reads RC bullet → runs darc get-default-channels → finds no RC sibling → tells the user release engineering needs to configure the mapping → halts without guessing. Coherent across all sections (patterns block, verify step, confirmation gate, explicit-confirmation list).

Methodology: 3 independent reviewers, adversarial consensus. 3/3 clean.

Round	Outcome
1	2 findings (warning placement, missing branch types) — both addressed
2	1 finding (RC bullet wording) — addressed
3	1 finding ("ask release engineering" undefined for an LLM) — addressed
4	0 findings — converged

CI is appropriately skipping (docs-only change). Ready to merge from this review scope.