vsadov/satori/api-proposal

API Proposal Skill

Create complete, terse, and empirically grounded API proposals for dotnet/runtime. The output should have a high chance of passing the API review process.

Prototype first, proposal second. Proposals without working prototypes are speculative — they get sent back because reviewers can't verify the design works. The prototype IS the evidence.

When to Use This Skill

Use this skill when:

• Asked to propose a new API for dotnet/runtime
• Given a vague API idea or incomplete sketch that needs to be turned into a complete proposal
• Given an existing underdeveloped api-suggestion issue to refine
• Asked to prototype an API and draft a proposal
• Asked to "write an API proposal", "draft an api-suggestion", or "improve this proposal"

Core Principles

1. TERSENESS: Proposals are reviewed live by humans during API review meetings who often lack prior context. Long text is counterproductive unless warranted by design complexity. Focus on WHAT problem and HOW to solve it.

1. Empirically grounded: Build and test a working prototype BEFORE writing the proposal. The prototype validates the design, surfaces edge cases, and produces the exact API surface via ref source generation.

1. Claims backed by evidence: Every motivating claim must have at least one concrete scenario. "This is useful" without showing who needs it and how they'd use it is the #1 reason proposals get sent back.

1. Context-driven depth: The amount of supporting text should be proportional to how much new information the proposal introduces — not just API surface size. A small API introducing a novel concept needs more justification than a large API adding async counterparts to existing sync methods.

Common Pitfalls

These are failure modes that LLM agents hit repeatedly when drafting proposals. Check your output against this list before publishing.

• Verbosity creep: Writing 3 paragraphs of motivation when 3 sentences would suffice. Live reviewers have limited time per proposal — respect it.
• Invented scenarios: Fabricating usage examples or motivation not grounded in real code patterns found during research. If you can't find real-world evidence, say so honestly rather than inventing it.
• Raw ref dump: Pasting the entire GenerateReferenceAssemblySource output instead of curating it to show only the new/changed API surface. The proposal should be the edited API shape, not a build artifact.
• Non-compilable examples: Usage examples that reference types, methods, or overloads that don't exist or have wrong signatures. Always verify examples against the prototype.
• Over-scoping risk sections: Writing lengthy risk analyses for straightforward additions (e.g., a new overload with no ambiguity risk). Match depth to actual risk.
• Inventing design decisions: Listing decisions that are obvious or self-evident just to fill the section. If the design is straightforward, say so or omit the section.

Modular Phases

This skill has 6 phases. Each can run independently (e.g., "just draft the proposal from my existing prototype"). When running the full pipeline, execute in order.

Phase 0: Gather Input & Assess Context

1. Accept input in any form: issue URL, text description, API sketch, or vague idea.

1. If the input is an existing GitHub issue, read it in full and identify:

• What sections are missing or underdeveloped
• Whether the proposed API surface is concrete or still vague
• Any reviewer feedback in comments (especially if api-needs-work label is present)

1. Identify the target: namespace, area label, affected types, target library under src/libraries/.

1. Assess novelty: Is this a well-understood pattern extension (async variant, new overload, casing option) or something introducing a novel concept? This determines the depth of the proposal.

1. Evaluate existing workarounds: Before proceeding, research what users can do TODAY without this API.

• Present the workaround(s) to the user for evaluation
• Explain trade-offs: performance penalty? excessive boilerplate? bad practices?
• This is a checkpoint: If a workaround is acceptable, the user may decide to shelve the proposal
• Only proceed to prototyping if workarounds are genuinely insufficient

1. Search for prior proposals on the same topic:

• Search dotnet/runtime issues for related proposals (e.g., api-suggestion, api-needs-work, or closed issues)
• If duplicates exist, surface them — don't block work, but note them for linking later
• Look for clues in reviewer feedback: what caused a prior proposal to be marked api-needs-work? Why was it closed or stalled? Learn from that history to avoid repeating the same mistakes

1. Ask clarifying questions if the proposal is too vague to prototype.

Phase 1: Research

The skill contains baked-in examples and guidelines for writing good proposals (see references/proposal-examples.md and references/api-proposal-checklist.md). The agent does NOT need to search for api-approved issues as templates — the baked-in references are sufficient. Phase 0's search for related issues on the same topic is a separate concern and is still required.

What the agent DOES at runtime:

1. Read the Framework Design Guidelines digest at docs/coding-guidelines/framework-design-guidelines-digest.md. Validate that proposed names follow the conventions.

1. Read existing APIs in the target namespace to ensure consistency:

• Naming patterns (e.g., TryX pattern, XAsync pattern, overload shapes)
• Type hierarchies and interface implementations
• Parameter ordering conventions

1. Read the reference documentation for updating ref source at docs/coding-guidelines/updating-ref-source.md.

1. Research existing usage of the APIs being modified or extended. This is especially important when the proposal changes existing API behavior, adds overloads that could cause ambiguity, or has compatibility implications.

• Search the local repo (grep/ripgrep) for internal usage of the affected types and methods within dotnet/runtime. This is the most up-to-date source for how APIs are used within the framework itself.
• Search [grep.app](https://grep.app) for .NET code patterns in public repos to gauge ecosystem usage volume and discover common consumption patterns. This helps answer: "how widely is this API used today?" and "what patterns would benefit from the new API?"
• Check [apisof.net](https://apisof.net) for TFM and version availability of the affected APIs. This helps assess the API's reach and cross-platform surface.
• What to look for: usage volume and popularity, common calling patterns, code that might break with the proposed changes (overload resolution, behavioral changes), and code that would benefit from the new API.

Phase 2: Prototype

If the user already has a prototype, ask for the published branch link and/or commit hash. Skip steps 1–3 below, but still run all steps in Prototype Validation against the provided branch/commit before proceeding to Phase 3.

1. Create a new branch: api-proposal/<short-name>. The prototype must be kept as a single commit on this branch.

• Commit the initial prototype as a single commit.
• When addressing feedback before publication, amend the existing commit or squash locally and force-push so the branch history remains a single commit. This is the one place the repo's no-force-push rule doesn't apply — nothing links to the commit yet.
• After publication, use Phase 6 instead: a force-push invalidates the commit URL the proposal links to.

1. Implement the API surface with:

• Complete triple-slash XML documentation on all public members
• Proper #if guards for TFM-specific APIs

1. Write comprehensive tests:

• Use [Theory] with [InlineData]/[MemberData] where applicable
• Cover edge cases, null inputs, boundary conditions
• Test any interaction with existing APIs

1. Search dotnet/runtime for adoption sites. Before writing any proposal text, systematically search the entire local repo (grep/ripgrep) for every place the new API could or should be used. This serves two purposes: validating that the API shape works in diverse real-world contexts, and producing the adoption catalog required in the proposal (see Phase 4, section 6).

What to search for:

• Manual workarounds, verbose boilerplate, or older idioms that the new API directly replaces
• Call sites of the existing APIs being extended (e.g., if adding an overload, find every call to the current overloads)
• Patterns that would become simpler, more efficient, or more correct with the new API
• Third-party or test code within the repo that exercises the same scenario

How to catalog results:

• Record every hit with file path and a one-line description of how the new API applies
• Classify each site into one of three categories:
• Updated: Already converted in the prototype commit (pick a representative set of the most diverse and impactful sites)
• Candidate: Could be converted but was intentionally deferred (e.g., different area, risk of churn, needs area-owner review)
• Inapplicable: Initially matched the search but doesn't actually benefit from the new API (brief reason why)
• The catalog should be thorough — err on the side of listing too many sites rather than too few

1. Apply the new API at representative sites. From the catalog above, convert a diverse, representative set of adoption sites in the prototype commit. Prioritize sites that exercise different aspects of the API (different overloads, edge cases, interaction with other APIs). The remaining "Candidate" sites are listed in the proposal but left unconverted.

Prototype Validation (all steps required)

Prerequisite: Follow the build and test workflow in the build-and-test skill — complete the baseline build, configure the environment, and use the component-specific workflow for the target library. All build and test steps below assume the baseline build has already succeeded.

Step 1: Build and test

Build the src and test projects, then run all tests for the target library using the workflow described in the build-and-test skill. All tests must pass with zero failures.

Building the test project separately is critical for detecting source breaking changes that ApiCompat won't catch:

• New overloads/extension methods causing wrong method binding in existing code
• New generic overloads causing overload resolution ambiguity
• Pay attention to compilation warnings, not just errors

Step 2: Check TFM compatibility

Inspect the library's .csproj for TargetFrameworks. If it ships netstandard2.0 or net462 artifacts:

• Verify the prototype compiles for ALL target frameworks, not just $(NetCoreAppCurrent)
• Ensure .NET Core APIs form a superset of netstandard/netfx APIs
• Use #if guards where types like DateOnly, IParsable<T> restrict parts of the surface to .NET Core
• Failure to maintain superset relationship risks breaking changes on upgrade/type-forward

Step 3: Generate reference assembly source

cd src/libraries/<LibraryName>/src
dotnet msbuild /t:GenerateReferenceAssemblySource

For System.Runtime, use dotnet build --no-incremental /t:GenerateReferenceAssemblySource.

This:

• Produces the exact public API diff to use in the proposal
• Validates that only intended APIs were added (no accidental public surface leakage)
• The ref/ folder changes must be committed as part of the prototype