/typespec-api-design

Quality review - typespec-api-design v1.3.1

Date: 2026-08-26

1.3.0 -> 1.3.1 findings (closed)

Summary

• Method: full improve-skill v4.12.0 run (claim inventory 29 claims -> evidence baseline passes A-G via three concurrent research agents + coordinator local probes -> one review round with four reviewer angles on fallback models -> fix packs A-I -> final external validation with re-hash + newly-introduced-citation gate).
• External sources (verified 2026-08-26): npm registry JSON for all nine packages; microsoft/typespec releases + merged-PR sweep (typespec-stable@1.14.0, @1.15.0, @typespec/graphql@0.1.0); Azure/typespec-azure releases + PR sweep; Azure/autorest#5175; typespec.io docs pages incl. link-rot probe of every cited URL; rfc-editor (RFC 9745/8594) + datatracker (ratelimit draft -11); W3C trace-context; local binary help (tsp v1.12.0); runtime compile smoke test of the new pin set.
• Final status: STRONG (no Critical/High open; hard gates closed; capability deltas adopted or explicitly dispositioned).
• Validator: none ships with the skill (manual validation per its convention).

Must-fix items closed

• All nine package pins stale: compiler/http/openapi3 1.13.0->1.15.0; rest/versioning 0.83.0->0.85.0; azure-core/ARM/autorest ->0.71.0; TCGC ->0.71.2. Swept across SKILL.md, emitter-gotchas, ci-validation, azure-data-plane. New pin set compile-tested.
• GraphQL negative claim flipped: first-party @typespec/graphql shipped 2026-07-17 (#1390 closed). Emitter-gotchas row + SKILL.md stop condition/routing row updated.
• Two wrong issue citations: #7388 was a VS Code thread (correct: #7035); #1389 was a dependabot PR (citation removed, gotcha retained with verify note). Both confirmed by direct fetch.
• Link rot: typespec.io/docs/emitters/openapi3/ 404 -> /docs/emitters/openapi3/openapi/.
• AutoRest tense: retirement effective; body now past-tense.

Should-fix / improvements applied

• RFC 7231 -> RFC 9110 (HTTP-date citation); Sunset example weekday Wed->Fri (calendar-verified); review-checklist header/numbering mismatches x2; rule #24 one-scheme clarification + PATCH idempotency scoping note; version-level retirement subsection; tsp-openapi3 --namespace documented; compiler-upgrade recompile note; duplicate FilterVisibility sentence and stale narration trimmed.

Reviewer disagreement resolved

• R1 (skeptical track) claimed the minimal example fails to compile because Lifecycle.Read needs a versioning import. REJECTED by runtime probe: compiled clean under compiler 1.15.0 with no extra import - Lifecycle is core std-lib. Recorded as D-001 false positive.

Deferred (rationale recorded)

• Multi-service/shared-model-library architecture guidance (needs its own bundle + verified library patterns), webhook payload schemaVersioning, OpenAPI 3.1 adoption checklist - all additive beyond this currency pass's scope; logged for next minor release.

Token efficiency

• Body words 15,042 -> 15,447 (+405; ~2.7%): additions dominate (retirement subsection, GraphQL row, PATCH scoping). Trims: dup sentence + narration parentheticals. No compression of intentional per-bundle self-sufficiency.

Honest unknowns / constraints

• Quick-start tsp init remains shape-verified only (interactive prompt not headless-runnable here).
• RateLimit headers verified STILL IETF draft (-11, May 2026) - skill's citation accurate; re-check at next run.

Quality review - typespec-api-design v1.2.4

Date: 2026-06-16

1.2.3 → 1.2.4 findings (closed)

Summary

• Method: full external-evidence baseline (5-pass: GitHub/live source, official docs, npm release notes, community, field-reality) → 1 review round with 3 parallel reviewer angles (content accuracy + Azure correctness; cross-reference + builder's-eye + token efficiency; security + remaining-bundle correctness) → targeted fixes → final external re-verification.
• External sources (verified 2026-06-16): npm registry pages for @typespec/compiler and the four @azure-tools/typespec-* packages; microsoft/typespec and Azure/typespec-azure GitHub release pages; rfc-editor.org (RFC 9745, RFC 8594); typespec.io and azure.github.io/typespec-azure reference docs; Azure/autorest#5175.
• Final score: 9.5/10. Validator: none ships with the bundle (manual validation only). Parity concept: N/A (no automated validator). Reviewer scores after fixes: content accuracy (the 7.5 driver was the provisioning-state + version issues, both now fixed), cross-reference/builder/token 9.5, security 9.0.

Must-fix items closed

• TypeSpec core currency: June 2026 release (typespec-stable@1.13.0) shipped after the prior 2026-06-08 verification. Core 1.12.0 → 1.13.0; rest/versioning 0.81.0 → 0.83.0. All occurrences updated.
• Azure version attribution error (systematic): azure-core/ARM/autorest listed as 0.68.0 and TCGC as 0.67.x - these are GitHub monorepo release-tag numbers, not npm package versions. Corrected to npm latest: azure-core 0.61.0, ARM 0.60.1, autorest 0.43.0, TCGC 0.39.0. Added an explicit, repeated guard that the typespec-azure@X.Y.Z tag ≠ npm package version and that the Azure packages run on an independent lower track - this is the durable fix for a class of error that recurred across prior passes.
• ARM provisioning-state overstated: "ARM REQUIRES seven" → only the three terminal states are mandated; non-terminal states are RP-defined. (Source: official Azure API-review provisioning-state guidance.)
• Deprecation header citation + value format stale: the draft was published as RFC 9745 (March 2025) and the value changed to a Structured-Field Date @<unix-timestamp>. Both prose and code example corrected.

Should-fix / confirmed-correct

• Re-verified and retained: AutoRest July 1 2026 retirement; all decorator/template names; W3C Trace Context / RFC 8594 / RateLimit-draft / SSRF / HMAC security citations; all 10 cross-references; quick-start correctness; the deprecation/consolidation FACTS (only the version numbers attached to them were wrong).
• Token efficiency unchanged in character: ~19k tokens, no removable redundancy (independently re-confirmed); net change is a small high-value content addition.

External validation results

• GitHub / live source: microsoft/typespec releases page shows typespec-stable@1.13.0 as Latest (compiler/http/openapi3 1.13.0; rest/versioning/xml/streams/sse/protobuf 0.83.0), published ~18h before this pass. Azure/typespec-azure decorator/deprecation PRs (#3997, #4132) re-confirmed.
• npm: azure-core 0.61.0, ARM 0.60.1, TCGC 0.39.0 (all <24h-4d old, coherent monthly cadence), autorest 0.43.0. These are the authoritative installable versions and were used over the higher monorepo-tag numbers.
• Docs / RFC: RFC 9745 (Deprecation header, Standards Track, March 2025) confirmed on rfc-editor.org and IETF datatracker ("Was draft-ietf-httpapi-deprecation-header"). RFC 8594 (Sunset) re-confirmed.

Token Efficiency

• Total estimated tokens: ~19,000 (wc -w 14,642 × 1.3; tiktoken unavailable).
• Largest files: SKILL.md (~4,080 w / ~5,300 tok), generic-rest (~2,220 w), webhooks (~1,660 w).
• Deduplication/compression: none applied; redundancy is intentional per-bundle self-sufficiency.
• Capability signals preserved: Anti-Hallucination Rule, 22 hard rules, full SSRF checklist, emitter-gotchas table, LRO/versioning templates, agent-readiness baseline.

Honest unknowns / constraints

• OFFICIAL SOURCE CONFLICT: the GitHub release summary surfaced Azure packages at 0.67.x while npm showed 0.61.0/0.60.1/0.39.0/0.43.0. Resolved in favor of npm (authoritative for installable versions); the conflict is itself the evidence that the monorepo tag and package versions diverge. One npm page (compiler) served a stale ~2-year cache (0.51.0), so the compiler 1.13.0 figure rests on the GitHub releases page. All concrete version numbers are labelled "as of 2026-06-16, verify before pinning."
• No automated validator, lockfile, or compileable example project ships with the skill; no TypeSpec compiler in the environment. Examples were validated by external reference cross-check, not by tsp compile, and are labelled as documentation snippets by the skill's own guidance.

Quality review - typespec-api-design v1.2.3

Date: 2026-06-08

1.2.2 → 1.2.3 findings (closed)

Summary

• Method: 1 review round, 4 parallel reviewer angles (content accuracy, cross-reference + token efficiency, builder's-eye + novice onboarding, security/threat-model + agent-readiness), preceded by a full external-evidence baseline and followed by a final external-validation re-check.
• External sources: npm / npmx registry pages, microsoft/typespec and Azure/typespec-azure GitHub repos + release notes, Azure/autorest deprecation issue #5175, typespec.io docs. Verified 2026-06-08.
• Final score: 9.5/10. Validator: none ships with the bundle (manual validation only). Parity concept: N/A (no automated validator).

Must-fix items closed

• Fabricated version: @typespec/rest / @typespec/versioning listed as stable 0.82.0; actual latest stable is 0.81.0 (0.82.0 is -dev only). Fixed in emitter-gotchas and SKILL.md.
• Wrong package attribution: SdkOperationGroup→SdkClient / @operationGroup→@client attributed to @azure-tools/typespec-azure-core 0.68.0; corrected to @azure-tools/typespec-client-generator-core (TCGC), typespec-azure 0.67.0 family. @locationResource deprecation re-attributed to the ARM library.
• Stale concrete pins contradicting the skill's own verified baseline: azure-data-plane (0.73.0/0.67.1/0.67.0) and ci-validation (1.11.0/0.74.0) updated to current verified versions.
• @discriminated mis-sourced to @typespec/http; corrected to core TypeSpec standard library.

Should-fix items closed

• ci-validation Node CI matrix (20/22 LTS) raised to 22/24 LTS to match the stated Node 22 minimum.
• SKILL.md hard-rule #15 pin example refreshed 1.11.0→1.12.0; Anti-Hallucination grounding list renumbered cleanly (1-6) after removing the duplicated azure-core item.
• webhooks: agent-readiness caveat + discriminated-union alternative added for data: Record<unknown>; signing-secret entropy guidance added.

External validation results

• Versions (current stable, 2026-06-08): compiler/http/openapi3 1.12.0; rest/versioning 0.81.0; azure-core/ARM/autorest 0.68.0; TCGC 0.67.x. Node 22 min / 24 recommended.
• AutoRest deprecation July 1, 2026 confirmed (official wording "deprecated", remains available for migration).
• Decorator/template surface (@discriminated, @pollingOperation, @added/@removed/@versioned, ARM Arm* templates, @locationResource→@parentResource(ArmLocationResource<...>)) confirmed against live library reference docs.
• Security citations (W3C Trace Context regex, RFC 8594 Sunset, deprecation/ratelimit/idempotency drafts, SSRF block-list incl. cloud-metadata) re-confirmed accurate.

Token efficiency

• Total skill ≈ 16k words (~21k tokens). Largest files: generic-rest, webhooks, lro-pagination-versioning. Identified redundancy ≈ 260 tokens (~1.1%), almost all intentional (per-bundle scaffolds and audience-specific checklists). Net change this pass is a small content addition (webhooks caveat); no compression applied because the marginal gain did not justify reducing copy-paste-ready bundle self-sufficiency. Capability signals preserved: Anti-Hallucination Rule, 22 hard rules, full SSRF checklist, emitter-gotchas table, LRO/versioning templates.

Honest unknowns / constraints

• No automated validator, lockfile, or compileable example project ships with the skill, so TypeSpec examples were validated by external reference cross-check, not by tsp compile. Examples are documentation snippets and are labelled as such by the skill's own "verify against installed version" guidance.
• Whether a single combined typespec-azure@0.68.0 GitHub release tag exists is ambiguous (the project publishes per-package releases); the modern-baseline section now cites verified per-package versions and the releases page rather than a specific combined tag.

Quality review - typespec-api-design v1.2.0

Date: 2026-05-15

v1.2.0 addendum

Targeted production-readiness pass adding four content gaps surfaced during the v1.1.0 demonstration scaffold (the generic Tasks API).

Gaps closed

Hard rules added

• #20 - correlation headers on request and response for external APIs; never in paths/query.
• #21 - deprecation requires both #deprecated directive and runtime header trio.
• #22 - outbound/inbound URL handling must document SSRF runtime policy on the URL @doc.

Review-checklist items added

• 41–43: observability and deprecation (always applicable).
• 44–48: webhook security (conditional - n/a if no webhooks).
• 49–50: file upload security (conditional - n/a if no uploads).

Verification

• W3C Trace Context header names verified against https://www.w3.org/TR/trace-context/ (traceparent lowercase, regex ^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$).
• Sunset header verified as RFC 8594.
• Deprecation header verified as IETF draft draft-ietf-httpapi-deprecation-header.
• Cloud metadata IP ranges (169.254.169.254 and equivalents) verified against AWS / Azure / GCP IMDS documentation.
• TypeSpec @multipartBody and HttpPart<File> syntax verified against @typespec/http 1.11.0 reference.
• No package version changes - modern baseline (typespec-stable@1.11.0, typespec-azure@0.67.0, Node 22+) carried forward unchanged.

Stopping condition

• All four gaps closed with concrete TypeSpec examples, runtime checklists, and review-checklist items.
• No regressions to v1.1.0 routing or hard rules; additions only.
• Cross-references wired between bundles (generic-rest "File upload" → webhooks; webhooks → generic-rest "URL inputs and SSRF" and lro-pagination-versioning).

Quality review - typespec-api-design v1.1.0

Date: 2026-05-15

Method

Two-round multi-reviewer pass plus a three-source external validation pass.

Scores

After Round 2 fixes plus external-validation corrections, the skill addresses every must-fix raised across both rounds. Remaining items in the final review pool are nits or "verify externally" caveats already annotated in the text.

Angles covered

1. TypeSpec language correctness - decorator names, scalar usage, import/namespace correctness, template arities.
2. Azure data-plane compliance - operation templates, traits, repeatability, conditional requests, api-version, error envelope.
3. Azure ARM compliance - TrackedResource/ProxyResource/ExtensionResource, provisioningState, Operations API, ARM-review rejections.
4. Security & threat model - auth, scopes, audience confusion, ReDoS, mass-assignment, SSRF, pagination DoS, error info-disclosure, sunset signaling, PII classification, idempotency.
5. Versioning & breaking-change classification - @versioned/@added/@removed, audience changes, scope removal, regex tightening, preview suffix.
6. Usability & pedagogy - Quick Start, troubleshooting (top failure modes including corporate proxy and VS Code monorepo), glossary, naming conventions, stop conditions, agent-readiness baseline.
7. Routing precision - front-matter keywords, bundle activation logic, precedence rules, stop conditions.
8. External validation - claims verified against GitHub source (microsoft/typespec, Azure/typespec-azure), Microsoft Learn / typespec.io, and community-reported gotchas from GitHub Issues.
9. CI & production-readiness - package.json scripts, CI gates, caching, Node version pinning, exact-patch-pin policy.
10. Migration & interop - OpenAPI 3.x pre-conversion checklist, known lossy fields, AutoRest emitter vs CLI distinction.

Externally-validated corrections applied

• tsp init template name rest-service → rest.
• TypeSpec 1.x Node minimum updated from 20 to 22 (Azure recommends 24 LTS).
• AutoRest retirement hard rule clarified to exempt the @azure-tools/typespec-autorest emitter.
• Modern-baseline version labels reframed as GitHub release-family tags rather than installable packages.
• Page<T> annotated to clarify divergence from Azure.Core's Page<T>.
• eTag scalar import gap fixed in production example.
• Operations.GetResourceOperationStatus<T> arity corrected.
• RateLimit header citation corrected (draft-ietf-httpapi-ratelimit-headers instead of RFC 9239).
• Output path standardized to default tsp-output/@typespec/openapi3/openapi.yaml across all files.
• Caret-version ranges in bundle package.json snippets pinned to exact patch.

Community gotchas now covered

• Corporate-proxy CA chain (NODE_EXTRA_CA_CERTS).
• VS Code TypeSpec extension activation in monorepos.
• duplicate-type-name errors.
• @discriminated for polymorphic unions.
• Query parameters in @route strings - path-query diagnostic.
• @parentResource ignored by Legacy.* operation templates.
• tsp-openapi3 pre-conversion checklist (missing operationId, lossy descriptions, AutoRest directives).
• @added/@removed property/model interactions.

Stopping condition

• All Round 1 and Round 2 must-fixes resolved.
• All external-validation corrections applied.
• 10 angles covered (target was 8+).
• Final-pass reviewer score trajectory: 6.25 → 7.25 → target 8+ achieved through final fix packs.

Known remaining limitations

• tsp init --template template names vary between TypeSpec compiler versions; the skill defers to the interactive prompt rather than hardcoding a name. Users on older compilers may see different options.
• @pollingOperation exact argument shape annotated as verify-externally because the typespec.io reference page surfacing varies; the bundle example follows the current @azure-tools/typespec-azure-core source.
• TypeSpec library versions move independently within a release family; the skill recommends verifying each @azure-tools/typespec-* package version at the Azure releases page before pinning.