From 0f7b24dfb6abeaea3c3e5d1e11b2849efe4ab4e9 Mon Sep 17 00:00:00 2001 From: Yuchao Yan Date: Fri, 16 Oct 2026 16:25:28 +0800 Subject: [PATCH] docs(skills): prioritize native lint simplification in review Separate review direction from policy gates, remove framework-only test infrastructure, and distinguish one-time example evidence from continuous coverage. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/skills/develop-lintdiff-rule/SKILL.md | 11 ++++- .github/skills/lintdiff-rule-promote/SKILL.md | 15 ++++--- .../skills/typespec-lint-discovery/SKILL.md | 6 ++- .../skills/typespec-lint-implement/SKILL.md | 44 ++++++++++++++++--- .../skills/typespec-lint-validate/SKILL.md | 34 +++++++++----- 5 files changed, 85 insertions(+), 25 deletions(-) diff --git a/.github/skills/develop-lintdiff-rule/SKILL.md b/.github/skills/develop-lintdiff-rule/SKILL.md index 65c9b5a69c..0173765c77 100644 --- a/.github/skills/develop-lintdiff-rule/SKILL.md +++ b/.github/skills/develop-lintdiff-rule/SKILL.md @@ -353,8 +353,15 @@ the shared [test-claim matrix](../typespec-lint-validate/SKILL.md#test-claim-mat Follow its setup, typed-extraction, and exact-target guidance. Preserve required registered execution, suppression, cross-rule, package-isolation, and actual published-example proof in the appropriate layers rather than deleting it as -unit-test cleanup. This mapping supplements, not replaces, required focused -fixture, build, and corpus evidence. +unit-test cleanup. First establish that these claims require rule-specific +evidence: delete generic suppression/enablement proof without replacement and +reconcile stale PR promises, while retaining concrete rule-owned interactions +and regressions. For published examples, follow the shared +[documentation validation guidance](../typespec-lint-validate/SKILL.md#documentation-example-validation): +remove bespoke per-rule parsers rather than relocating them, and distinguish +existing shared continuous coverage from recorded one-time execution. +This mapping supplements, not replaces, required focused fixture, build, and +corpus evidence. Apply the [native rule documentation contract](../typespec-lint-implement/SKILL.md#native-rule-documentation) to the user-facing explanation and examples in `rule.md`. Keep emitted-reference diff --git a/.github/skills/lintdiff-rule-promote/SKILL.md b/.github/skills/lintdiff-rule-promote/SKILL.md index 5c256d7971..15d0c19616 100644 --- a/.github/skills/lintdiff-rule-promote/SKILL.md +++ b/.github/skills/lintdiff-rule-promote/SKILL.md @@ -520,7 +520,10 @@ below apply to individual-rule diagnostics, not every acceptance claim: preserve required registered execution/suppression, cross-rule interactions, registration/legacy names, package loading/isolation, and published-example proof in the appropriate existing layers. Do not silently drop that evidence -when removing framework-only unit cases. +when removing framework-only unit cases. Establish which claims need +rule-specific evidence first: delete generic suppression/enablement proof +without replacement, retaining concrete rule-owned interactions and regressions. +Reconcile stale PR promises rather than treating them as independent requirements. Create: @@ -617,10 +620,12 @@ library documentation following the - pass the [documentation example validation](../typespec-lint-validate/SKILL.md#documentation-example-validation) gate for the actual incorrect/correct snippets; preserve the diagnostic contrast rather than substituting an exempt default template response -- if native tests extract the authored Markdown examples, accept both CRLF and - LF fence line endings and verify that the expected snippets were found before - compiling them; do not mistake Windows checkout line endings for missing - examples or replace the final snippets with separate test-only copies +- do not add, retain or relocate bespoke per-rule Markdown parsers. Keep literal + semantic tests and validate actual published snippets through existing shared + infrastructure or recorded one-time execution. State whether the evidence is + continuous or one-time; do not claim copied fixtures validate the published + document. When existing shared tooling extracts snippets, handle CRLF and LF + and require an unambiguous match - follow the destination's authored-document conventions, including `## Impact` with the affected areas and `## Suppression` guidance when used by neighboring rules; explain when suppression is appropriate rather than only how to fix diff --git a/.github/skills/typespec-lint-discovery/SKILL.md b/.github/skills/typespec-lint-discovery/SKILL.md index d06faf6e9f..84e5cc5b73 100644 --- a/.github/skills/typespec-lint-discovery/SKILL.md +++ b/.github/skills/typespec-lint-discovery/SKILL.md @@ -62,7 +62,11 @@ Record these decisions in the brief before implementation: prove that requirement. Separate rule-owned decisions from guarantees supplied by those APIs or the linter framework; apply the [rule-test responsibility boundary](../typespec-lint-validate/SKILL.md#rule-test-responsibility-boundary) - when planning coverage. Mark unresolved API questions explicitly. + when planning coverage. Establish why the native guideline requires custom + traversal, SDK setup or a public API, not merely why the proposed architecture + uses it. Apply the + [simplification review guidance](../typespec-lint-implement/SKILL.md#simplification-and-review) + when feedback challenges that architecture. Mark unresolved API questions explicitly. - **Diagnostic contract:** specify the unit (property, operation, model, etc.), authored target, expected multiplicity, exemptions, and concise corrective message. Extra diagnostics and suppressed duplicates are behavior decisions. diff --git a/.github/skills/typespec-lint-implement/SKILL.md b/.github/skills/typespec-lint-implement/SKILL.md index 14c2b416d7..4b0c768fc7 100644 --- a/.github/skills/typespec-lint-implement/SKILL.md +++ b/.github/skills/typespec-lint-implement/SKILL.md @@ -62,8 +62,9 @@ discovery rather than silently choosing different semantics. `options.name` for wire-name policies, and target the authored `property`. Verify the repository's installed API rather than copying an obsolete shape. - Require a supported-input regression case for added complexity. Keep a scope - guard or SDK-name resolver when the contract requires it; do not remove it - solely to reduce code. Compare related rules' scope and name-resolution policy. + guard or SDK-name resolver when an independently justified native requirement + needs it, not merely because the current implementation and tests use it. + Compare related rules' scope and name-resolution policy. Apply the [discriminating coverage gate](../typespec-lint-validate/SKILL.md#contract-driven-coverage) before rewriting logic for an alleged miss. - Report each independently actionable violation on its authored target. Avoid @@ -76,6 +77,34 @@ discovery rather than silently choosing different semantics. - Apply the [native rule documentation contract](#native-rule-documentation) when writing or updating user-facing rule documentation. +## Simplification and review + +A rule brief and PR description record the proposed design, not a requirement +that overrides review asking to simplify, revert or consolidate it. + +- Record the requested direction and compare the smallest alternative using + existing native mechanisms before defending the current architecture. + For each behavior that would change, distinguish a required native guideline, + verified released compatibility, legacy parity and a choice introduced by + the proposal. Tests of that choice do not establish an independent requirement. +- A behavior difference is a tradeoff to assess, not by itself a reason to + reject simplification. Prefer extending an existing rule when its native + responsibility remains coherent; assess actual enablement and suppression + effects separately, distinguishing proposed IDs/APIs from released contracts. +- Name any specific unresolved policy choice, explicit request for another + maintainer's input or missing authorization. Do not invent a decision gate + solely because the reviewer challenges the proposed contract, and do not + accept a suggestion solely on reviewer authority. +- Keep permissions, required validation and source-immutability boundaries. + When the recommendation requires authorized source repair, report that + handoff separately from the design recommendation; do not silently diverge + in the promoted copy. Update the brief, tests, docs and PR claims together + when an in-scope redesign is authorized. +- Track replying separately from satisfying the request. An explanation of the + current design is not evidence that a simplification concern was addressed; + identify the implemented change, outstanding action or evidence-backed + qualified rejection without implying reviewer agreement. + ## Native rule documentation Write the main documentation for a TypeSpec author who does not know the source @@ -154,15 +183,18 @@ native contract and [test-claim mapping](../typespec-lint-validate/SKILL.md#test native-versus-legacy differences across implementation, actual published examples, authored/generated references, manual guides, and legacy mappings. - Recheck SDK impact and compatibility guidance. Show the fully qualified rule - ID and correct placement in suppression examples; when registered suppression - is an acceptance claim, preserve its control in integration coverage. + ID and correct placement in suppression examples. Retain registered + suppression coverage only for a concrete rule-owned interaction or + demonstrated regression, not merely because it was promised in the PR. - Reconcile task-owned unreleased Chronus entries with the final public behavior rather than accumulating stale intermediate fix descriptions. Consolidate only entries for the same unreleased feature/package where appropriate; retain distinct package and release classifications. - Evaluate reviewer suggestions against current code, the contract, and PR - promises before turning them into policy. Do not impose blanket bans on - isolated testers, integration tests, Markdown compilation, or helpers. + promises using the [simplification review guidance](#simplification-and-review). + Do not impose blanket bans on isolated testers, integration tests, compiling + examples or helpers. For Swagger/LintDiff migrations, apply the specific + [no-bespoke-parser guidance](../typespec-lint-validate/SKILL.md#documentation-example-validation). ## Deliverable diff --git a/.github/skills/typespec-lint-validate/SKILL.md b/.github/skills/typespec-lint-validate/SKILL.md index 00f2e32b69..0f1e25af2e 100644 --- a/.github/skills/typespec-lint-validate/SKILL.md +++ b/.github/skills/typespec-lint-validate/SKILL.md @@ -50,6 +50,12 @@ These are placement rules, not a mandatory set of suites for every rule. Use the repository's existing harnesses and organization; a distinct layer need not mean a new file per rule or a new general-purpose harness. +First establish that a claim needs rule-specific evidence. A PR promise alone +does not make generic suppression or enablement a rule-owned requirement. +Delete framework-only cases without replacement; do not relocate them merely +to preserve a checklist. Retain concrete rule-caused interactions, authored-node +deduplication and demonstrated regressions. Update stale PR claims accordingly. + Relocate required acceptance evidence instead of silently deleting it during unit-test cleanup. A registration or interaction test is not a framework-only test merely because it is unnecessary in the single-rule suite. Retain it in @@ -108,8 +114,8 @@ linter framework, or shared test harness in every rule suite. authored locations without asserting compiler object identity or traversal internals. - When updating an existing suite, remove framework-only cases within the task's - scope; retain any distinct rule assertion in a simpler case. If a genuine - framework regression needs coverage, place it in the owning framework/helper + scope without replacement; retain any distinct rule assertion in a simpler + case. If a genuine framework regression needs coverage, place it in the owning framework/helper suite rather than duplicating it across rules. Do not edit unrelated PRs unless that cleanup is explicitly part of the task. First account for required non-unit acceptance evidence through the @@ -188,17 +194,23 @@ first. The dimensions below are not an unconditional test matrix for every rule: ### Documentation example validation -Keep literal behavior fixtures independent of Markdown layout. In a dedicated -documentation test or existing example workflow, select the actual published +Keep literal behavior fixtures independent of Markdown layout. For Swagger/LintDiff +migrations, do not add bespoke per-rule Markdown parsers or relocate +them into a separate suite. Remove such parsers while retaining useful literal +semantic cases; a shared documentation-testing system belongs in a separate task. + +Use existing shared documentation/example infrastructure or a one-time scratch +execution against the actual published snippets. Record the document revision +or content hash, setup, command and diagnostic evidence in the validation +handoff or PR notes. A one-time receipt is not continuous documentation coverage. +When existing infrastructure extracts examples, select the actual published snippets by semantic section or stable identity, requiring an unambiguous match. Do not assert global fence counts, use positional fence indexes, or compile only -copied text while claiming to validate the published document. Markdown -compilation is useful evidence in its own layer, not a reason to couple every -rule case to documentation parsing. +copied text while claiming to validate the published document. Validate the actual incorrect/correct snippets through the repository's existing -example or focused test workflow, adding only the imports and service/resource -setup needed to compile them. Record that setup so the result is reproducible; +example workflow or one-time execution, adding only the imports and +service/resource setup needed to compile them. Record that setup so the result is reproducible; do not replace the published operation or response shape with an easier test. - Explicitly enable the target rule, including when its ruleset entry defaults @@ -216,8 +228,8 @@ do not replace the published operation or response shape with an easier test. require a documented template limitation for any handwritten fallback. - Record the example audience, chosen template/customization or justified handwritten exception, and diagnostic evidence in the validation handoff or - PR notes. Reuse existing example infrastructure or a scratch workflow instead - of forcing ARM dependencies into a Core unit-test suite. If no suitable + PR notes. Reuse existing shared example infrastructure or one-time execution + instead of forcing ARM dependencies into a Core unit-test suite. If no suitable workflow is available, report the missing evidence rather than claiming this gate passed; do not add a new general-purpose harness just for the examples.