Add rule template and documentation

[Sean Wheeler (sdwheeler)]

Add rule template and documentation

• Fixes AB#633680

[Copilot]

🟡 Changes recommended

The template contains invalid YAML placeholders and heading/link inconsistencies that should be corrected before approval.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds a reusable PSScriptAnalyzer rule documentation template and authoring guidance.

Changes:

• Defines standard article structure and placeholders.
• Documents required and optional sections.
• Provides configuration, suppression, and example guidance.

File summaries

File	Summary
docs/rule-template.md	Adds the reusable rule documentation template.
docs/rule-template-docs.md	Documents how to complete the template.

Review details

Suppressed comments (4)

docs/rule-template.md:5

• The frontmatter is not valid YAML while the placeholders are present: an unquoted scalar beginning with {{ is parsed as a flow collection and causes frontmatter parsers to fail. Since this is a documentation template, keep the template itself parseable by quoting the placeholder values (and preserve the quotes when authors replace them).

description: {{Brief description of the rule behavior}}
ms.date: {{MM/DD/YYYY}}
ms.topic: reference
title: {{RuleName}}

docs/rule-template.md:40

• This introduces a second top-level examples section immediately after the required ## Example, so anyone copying the template gets a redundant empty section and an inconsistent hierarchy. Keep one ## Example section and place the scenario heading directly beneath it as the optional additional example structure.

## Examples

### {{Scenario name}}

docs/rule-template.md:73

• The repository's rule articles make Parameters an H3 under the configuration section and individual settings H4 headings (for example, docs/Rules/PlaceOpenBrace.md:31-45). Making Parameters an H2 and each setting an H3 breaks the documented heading hierarchy and conflicts with the guidance file.

## Parameters

### {{SettingName}}

docs/rule-template.md:95

• This reference link has no definition in this file, and the repository does not contain a using-scriptanalyzer.md target at the referenced relative path, so every article copied from the template will publish a broken Further reading link. Point this reference to the same Microsoft Learn URL used by the repository README (or add the intended local document).

[02]: ../using-scriptanalyzer.md

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.