[Epic] AI Engineering Checklist

## Summary

Apply the **AI Engineering Checklist** to `dotnet/sdk` to assess our current AI-adoption maturity, close the highest-leverage gaps, and turn the results into tracked, owned backlog items.

The `dotnet/`sdk repo already has a real AI-engineering surface (e.g. Copilot instructions). This epic is about moving from "assets exist" to "agents reliably operate, validate, and compound" across the whole repo.

---

## Tier 1 — Foundation readiness

**Goal:** agents can understand the SDK's repos, conventions, architecture, setup, and operating rules.

- [x] **(P0)** Refresh/verify the AI context entry points cover the whole repo. Ensure top-level architecture, key subsystems, and the feature/config story are discoverable.
- [x] https://github.com/dotnet/sdk/pull/55055
- [x] **(P0)** Add a PR checklist item + agent-assisted step: does this change require updates to AI context, instructions, docs, commands, tests, or workflow guidance — in the **same PR**?
- [x] https://github.com/dotnet/sdk/pull/55204
- [ ] **(P1)** Document end-to-end dev recipes for recurring SDK change types.
- [x] https://github.com/dotnet/sdk/pull/55199
- [x] **(P1)** Add/extend path-scoped instructions for high-change or high-risk areas.
- [x] https://github.com/dotnet/sdk/pull/55198
- [x] **(P1)** Strengthen explicit agent guardrails: do-not-touch boundaries (generated manpages, `.xlf`), non-interactive command invocations, secret handling — consolidate into the context entry point.
- [x] https://github.com/dotnet/sdk/pull/55218
- [x] **(P1)** Document multi-repo/VMR context (runtime, roslyn, msbuild, templating) so agents understand sibling-repo dependencies and where changes really belong.
- [x] https://github.com/dotnet/sdk/pull/55432
- [x] **(P1)** Make important architecture/product claims source-linked to code, PRs, issues, ADRs, or runbooks; reduce uncited synthesis.
- [x] https://github.com/dotnet/sdk/pull/55304
- [x] **(P1)** Document explicit dependency rules: approved feeds, version policy, package health, and security expectations (extend the "External Dependencies" guidance).
- [x] https://github.com/dotnet/sdk/pull/55319
- [ ] **(P1)** Improve repo indexing / code search / context tooling so agents discover existing patterns before changing code.

## Tier 2 — Feedback readiness

**Goal:** agents can validate work with fast, concrete, machine-readable signals.

- [x] **(P0)** Ensure agents can run targeted tests for common change areas and get actionable failures.
- [x] https://github.com/dotnet/sdk/pull/55532
- [ ] **(P0)** Make the agent-facing suite deterministic: quarantine/tag flaky tests and separate them so "100% green" can be a real gate.
- [ ] #55859
- [x] **(P0)** Enable/standardize AI-assisted code review as a first pass before human review across SDK PRs.
- [x] https://github.com/dotnet/sdk/pull/54924
- [ ] **(P1)** Package CI logs and test results in agent-readable form and make failures easy to map back to source changes.
- [ ] **(P1)** Ground AI review in SDK-specific checklists (correctness, architecture, security, perf, tests, maintainability).
- [ ] **(P1)** Make important integration/e2e workflows agent-runnable (SWA already leads here — generalize the pattern).
- [ ] **(P1)** Treat missing test hooks, opaque runtime state, and unstructured signals as AI-enablement gaps in the backlog.

## Tier 3 — Workflow adoption

**Goal:** agents are part of the normal engineering flow from shaping through hardening.

- [ ] **(P0)** Add a spec-first / plan-first playbook for non-trivial SDK work.
- [ ] **(P0)** Add an explicit **discovery-before-generation** step to agent instructions/skills (read nearby code + conventions before writing), distinct from Tier 1 documentation.
- [ ] **(P0)** Encode a definition-of-done: agents run format, lint, build, and relevant tests before presenting work as complete.
- [ ] **(P0)** Keep generated diffs scoped and reviewable (PR-size guidance, checkpoints, incremental commits).
- [ ] **(P0)** Set review expectations so AI-generated code receives equal-or-stronger scrutiny.
- [ ] **(P1)** Make the AI review pass a prerequisite to human review; update guidelines so humans confirm/extend AI findings.
- [ ] **(P1)** Add a review-comment-to-harness loop: recurring comments become instructions, tests, analyzer rules, or skills.
- [ ] **(P1)** Make plans reviewable before a large diff appears: keep planning and implementation separable so the plan can be approved first.

## Tier 4 — SDK-specific leverage

**Goal:** target the engineering workflows that consume the most time or cause the most risk.

- [ ] **(P0)** Run an AI-focused retrospective + workflow inventory to identify the SDK's highest-toil activities.
- [ ] **(P1)** Systematize existing bets into supported workflows: `analyze-sdk-issue` / `reproduce-sdk-issue` for triage & repro; `ci-analysis` + SWA CI-repair skills for build-break/CI repair; `generate-release-notes` for release/status; `update-xlf-on-comment` and man-page generation for docs/loc drift.
- [ ] **(P1)** Ensure high-risk SDK code areas have specialized review coverage (skills/checklists).
- [ ] Expand product-specific machine-readable context/tools (CLI output, MCP, `detect-netsdk-diagnostics`) so agents can inspect SDK/build state.
- [ ] **(P1)** Pilot each new AI workflow on 3–5 real items with an owner and stop condition before broad rollout; add throttling/rollback for bulk workflows.

## Tier 5 — Compounding system

**Goal:** the SDK's AI system improves when agents or humans discover gaps.

- [ ] **(P1)** Adopt a **correct-once** principle: recurring agent failures are fixed in the harness (instructions/skills/tests/analyzers), not only in the current PR.
- [ ] **(P1)** Create a lightweight intake for AI artifact updates (who updates instructions/skills, and how).
- [ ] Capture successful prompts/plans/review comments for reuse; package repeated tasks into skills (extend the existing skill library + `ValidateSkill.cs`).
- [ ] **(P1)** Give AI artifacts owners and review expectations like source code; add a DRY/stale-artifact audit cadence and a retirement path.
- [ ] **(P1)** Assign ownership for the context-refresh process (automation health, human review, stale-context cleanup).