Require template-first lint documentation examples

.github/skills/do-linter-development-task-one-by-one/SKILL.md

@@ -836,6 +836,14 @@ one session to execute both publication phases.
 > and ruleset enablement unless the evidence requires reporting a blocker.
 > Pass the same no-skill-edits/no-skill-update-PR ownership constraint.
 >
+> Enforce the shared
+> [example authoring policy](../typespec-lint-implement/SKILL.md#example-authoring)
+> in promotion documentation: use supported standard templates instead of raw
+> routes whenever they can demonstrate both incorrect and correct behavior.
+> Require a documented template limitation for handwritten exceptions; a generic
+> HTTP audience does not waive an available ARM template pair. Verify diagnostic
+> evidence for the actual final snippets before publication and review handoff.
+>
 > Follow promotion through draft PR creation or update. Record the absolute
 > promotion worktree and canonical promotion PR URL. A confirmed source defect
 > returns `source-repair-required` with the complete cycle handoff immediately;

.github/skills/lintdiff-rule-promote/SKILL.md

@@ -576,9 +576,11 @@ library documentation following the
   mechanics merely to explain the migration
 - include realistic TypeSpec incorrect and correct examples
 - apply the shared [example authoring policy](../typespec-lint-implement/SKILL.md#example-authoring):
-  choose the example audience independently of the destination package, use
-  standard templates with named customizations for ARM resource scenarios, and
-  justify any handwritten ARM exception
+  use supported standard templates for the incorrect/correct pair whenever they
+  can preserve the diagnostic contrast, rather than raw routes; choose the
+  audience independently of the destination package, but do not use generic HTTP
+  labeling to omit a supported ARM template pair for an ARM-applicable rule;
+  justify handwritten exceptions with the inspected template limitation
 - 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
@@ -939,9 +941,10 @@ promotion diff. The review should inspect:
   rationale, and any Swagger/LintDiff provenance being confined to a provenance
   section
 - example audience and template selection under the shared authoring policy,
-  justified handwritten ARM exceptions, and diagnostic evidence for the final
-  incorrect/correct snippets with the target rule enabled; compilation or a
-  passing exempt default-template example alone does not satisfy this gate
+  template-based incorrect/correct examples whenever supported, justified
+  handwritten exceptions, and diagnostic evidence for the final snippets with
+  the target rule enabled; generic HTTP labeling, compilation, or a passing
+  exempt default-template example alone does not satisfy this gate
 - generated docs and formatting drift, especially after rule renames:
   `packages/<target>/README.md`,
   `website/src/content/docs/docs/libraries/<library>/reference/linter.md`, and

.github/skills/typespec-lint-implement/SKILL.md

@@ -103,12 +103,19 @@ audience: a shared Core rule can still need an ARM resource example.
 - For ARM resource scenarios, use standard ARM operation templates in both the
   incorrect and correct examples. Express the violation through supported named
   customization arguments and omit unchanged defaults.
-- For data-plane or generic examples, use authoring patterns appropriate to that
-  audience; do not introduce ARM solely because the rule also applies to ARM.
-- Before using a handwritten ARM route or operation, inspect the relevant
-  template's customization points. If none can express the rule-owned behavior
-  being explained, record that limitation and the reason for the handwritten
-  example in validation evidence or PR notes. Brevity alone is not a reason.
+- For every audience, prefer supported standard operation templates over raw
+  routes or handwritten operations whenever templates can demonstrate both the
+  incorrect and correct behavior. Inspect the relevant template's customization
+  points before choosing handwritten examples. Use the template appropriate to
+  the audience; do not introduce ARM solely because the rule also applies to ARM.
+- Choosing a generic HTTP audience does not waive template selection. If an
+  ARM-applicable rule can demonstrate its behavior with standard ARM templates,
+  include that template-based incorrect/correct pair rather than using only raw
+  routes. Additional audience-specific examples may supplement it.
+- Use handwritten routes or operations only when no suitable supported template
+  can preserve the rule-owned diagnostic contrast. Record the inspected
+  template/customization limitation and the reason for the exception in validation
+  evidence or PR notes. Brevity or destination package alone is not a reason.
 - Preserve the semantic contrast when adopting templates. Both examples must
   reach the rule's intended check; the correction should fix the violation,
   not merely switch to an exempt construct. For an implicit-response-body rule,

.github/skills/typespec-lint-validate/SKILL.md

@@ -117,6 +117,10 @@ do not replace the published operation or response shape with an easier test.
   or made the correction pass only through an exemption. For implicit response
   examples, preserve implicit payloads rather than switching to explicit
   `@body` or `@bodyRoot` bodies outside the rule's scope.
+- Enforce the template-first authoring policy: when supported templates can
+  demonstrate the incorrect/correct pair, require those templates instead of raw
+  routes. A generic HTTP audience or successful compilation is not an exception;
+  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