Angular Best Practices Rules Reviewer

Rules Reviewer Agent

Review Angular best practice rules for accuracy, validity, and usefulness.

Core Mission

Verify each rule is legitimate, accurate, and valuable for Angular development. Don't just check formatting—verify the rule is a real best practice.

Review Process

1. Validity Check - "Is this a real rule?"

• Search Angular official docs (angular.dev) for guidance
• Look for community consensus (blogs, conference talks, GitHub discussions)
• Check if the pattern is recommended or discouraged
• Flag rules that seem made up or contradict best practices

2. Accuracy Check - "Is the code correct?"

• Verify code examples compile and work with Angular 17+
• Check for deprecated APIs or outdated syntax
• Ensure examples demonstrate the actual problem/solution

3. Usefulness Check - "Would AI actually need this?"

Evaluate each rule against these criteria:

Score: Count Keep answers (0-4)

• 4/4: High-value rule, keep as-is
• 2-3/4: Useful but may need improvement
• 0-1/4: Consider removing or merging

4. Format Check - "Does it meet standards?"

Read config/criteria.json for exact format thresholds.

Tools to Use

• WebSearch: Find Angular documentation and community consensus
• WebFetch: Read angular.dev docs, GitHub discussions, blog posts
• Read: Check the rule file content
• Grep/Glob: Find related rules or patterns in the codebase

Output Format

Produce a structured review for each rule:

## Rule Review: [rule-name.md]

### Usefulness Assessment

| Criteria | Rating | Notes |
|----------|--------|-------|
| Would AI make this mistake? | Keep/Improve/Remove | [Explain] |
| Is this AI-discoverable? | Keep/Improve/Remove | [Explain] |
| Is guidance specific enough? | Keep/Improve/Remove | [Explain] |
| Does it prevent real bugs? | Keep/Improve/Remove | [Explain] |

**Usefulness Score:** X/4

### Validity: VALID | QUESTIONABLE | INVALID
**Evidence:** [Links to Angular docs, blog posts, discussions]

### Accuracy: ACCURATE | OUTDATED | INCORRECT
**Angular Version:** Tested against Angular 17+
**Code Issues:** [Any syntax errors, deprecated APIs, or problems]

### Format: PASS | MINOR ISSUES | MAJOR ISSUES
**Lines:** X/50
**Code Blocks:** X (max 2)

### Verdict: KEEP | IMPROVE | REMOVE

**Recommendation:** [Specific changes needed or removal reason]

Review Commands

Single Rule Review

Review rules/typescript/ts-readonly.md

Perform full validity + accuracy + value + format check with research.

Batch Audit

Audit all rules in rules/core/

Review multiple rules. Read prompts/audit-batch.md for the batch audit output template.

Quick Validity Check

Is rules/angular/signal-computed.md a real best practice?

Fast check focusing on validity with evidence.

Rewrite Rule

Rewrite rules/core/pattern-facade.md to be more actionable

Improve rule based on review findings.

Skill Quality Review

When reviewing a SKILL.md file (not a rule file), read references/skill-best-practices.md for quality criteria. Evaluate frontmatter, directory structure, instruction voice, and negative triggers.

Important Guidelines

Code Blocks: Quality Over Quantity

• Rules do NOT need both incorrect + correct examples
• A single "correct" example is fine if the incorrect pattern is obvious
• Focus on demonstrating the RIGHT way, not cataloging wrong ways
• 1-2 code blocks max, prefer fewer if clearer

When to Use TEXT-ONLY Format

Some rules work better as a single sentence with inline code instead of code blocks:

Convert to TEXT-ONLY when:

• The rule is a single syntax difference (e.g., import type vs import { type })
• The pattern is a naming convention (e.g., "Use PascalCase for types")
• The guidance is informational, not a code pattern

When Incorrect + Correct IS Needed

Use both incorrect and correct examples when:

• The distinction is subtle but critical (e.g., catchError placement in RxJS)
• The anti-pattern is common and AI frequently generates it
• The performance/bug impact isn't obvious without contrast
• Operator choice matters (e.g., mergeMap vs switchMap)

Code Example Best Practices

Good examples:

• 2-3 lines max per block
• Include inline comments explaining WHY, not just what
• Show the minimum code needed to demonstrate the pattern
• Use realistic but simple variable names

Signs of bloat:

• More than 5 lines in a code block
• Multiple variants of the same pattern
• Setup/boilerplate that obscures the core pattern
• Showing 3+ ways to do the same thing

Rules to Flag for Removal

Remove rules where:

• Basic CS knowledge: early exit, Set vs Array lookups (AI knows)
• Basic JS patterns: closure mechanics, function reference stability
• TypeScript defaults: Type inference AI already uses
• Well-documented in Angular: Easy to find on angular.dev

Decision Criteria Must Be Specific

Bad: "Use when you have complex state" Good: "Use when components orchestrate 3+ services with interdependent async operations"

Bad: "Avoid when not needed" Good: "Avoid when you have only 2 variants with no expected growth"

Verify Against Real Angular Docs

Before approving a rule: 1. Search angular.dev for the topic 2. Check if Angular has official guidance 3. If Angular docs cover it well, the rule should add unique value 4. If the rule contradicts Angular docs, flag it

Batch Audit Prompt

Audit multiple rule files for usefulness to AI agents, validity, accuracy, and format.

Instructions

1. List all files in the target directory 2. For each file, assess usefulness + format 3. Categorize into KEEP / IMPROVE / REMOVE 4. Produce summary report with recommendations

Usefulness Check (per file)

Format Check (per file)

• [ ] Under 50 lines
• [ ] 1-2 code blocks
• [ ] Single sentence description
• [ ] Clear decision criteria

Output Format

## Batch Audit Report: {directory}

### Statistics
| Metric | Value |
|--------|-------|
| Total Rules | X |
| Avg Lines/Rule | X.X |
| Code Blocks | X |

### Usefulness Summary

| Category | Keep | Improve | Remove |
|----------|------|---------|--------|
| Signals (X) | X | X | X |
| TypeScript (X) | X | X | X |
| ... | ... | ... | ... |

### Rules to REMOVE (AI already knows)
| Rule | Reason |
|------|--------|
| `rule.md` | [Why AI doesn't need this] |

### Rules to IMPROVE (too vague)
| Rule | Issue | Fix |
|------|-------|-----|
| `rule.md` | [Problem] | [Specific fix] |

### High-Value Rules (4/4 usefulness)
- rule1.md
- rule2.md

### Priority Actions
1. Remove rules AI already knows
2. Add thresholds to vague rules
3. Fix deprecated code examples

Processing

For large audits:

• Group by subdirectory
• Assess usefulness first, then format
• Focus on REMOVE candidates

Single Rule Review Prompt

Review this rule file for usefulness to AI agents, validity, accuracy, and format.

Review Checklist

1. Usefulness (Would AI need this?)

2. Validity (Is this real?)

3. Accuracy (Is code correct?)

4. Format

Output Format

## Rule Review: {filename}

### Usefulness Assessment

| Criteria | Rating | Notes |
|----------|--------|-------|
| Would AI make this mistake? | ✅/⚠️/❌ | [explanation] |
| Is this AI-discoverable? | ✅/⚠️/❌ | [explanation] |
| Is guidance specific enough? | ✅/⚠️/❌ | [explanation] |
| Does it prevent real bugs? | ✅/⚠️/❌ | [explanation] |

**Usefulness Score:** X/4

### Validity: ✅ | ⚠️ | ❌
**Evidence:** [links to Angular docs or community sources]

### Accuracy: ✅ | ⚠️ | ❌
**Angular Version:** 17+
**Code Issues:** [any problems]

### Format: ✅ | ⚠️ | ❌
**Lines:** X/50
**Code Blocks:** X

### Verdict: ✅ KEEP | ⚠️ IMPROVE | ❌ REMOVE
**Recommendation:** [specific action or removal reason]

SKILL.md Quality Best Practices

Reference guide for writing high-quality SKILL.md files in this project. Based on skills-best-practices.

Frontmatter

Required Fields

---
name: angular-best-practices-<library>
description: >-
  <What it does>. <When it activates>.
  <Negative triggers — when NOT to use>.
  Install alongside angular-best-practices for full coverage.
version: "1.1.0"
tags: [angular, <library>, <domain>]
globs:
  - "**/*.ts"
  - "**/*.<pattern>.ts"
---

Description Best Practices

1. First sentence: What the skill does (action-oriented) 2. Activation trigger: When the skill should activate (e.g., "Activates when working with @ngrx/store") 3. Negative triggers: When NOT to use (e.g., "Do not use for React, Vue, or AngularJS 1.x projects") 4. Cross-reference: "Install alongside angular-best-practices for full coverage."

Negative triggers prevent false activation on similar-sounding but unrelated tasks.

Tags

• Include angular as the first tag
• Add the library name as a tag (e.g., ngrx, primeng)
• Add the domain (e.g., state-management, ui-components, i18n)
• 3-5 tags total

Globs

• Always include "**/*.ts"
• Add library-specific patterns (e.g., "**/*.reducer.ts", "**/*.store.ts")
• Add template files if the skill affects templates ("**/*.html")

Directory Structure

skills/<skill-name>/
  SKILL.md          # < 500 lines; main instructions
  AGENTS.md         # Generated by build — do not edit manually

For internal contributor skills (.claude/skills/):

.claude/skills/<skill-name>/
  SKILL.md          # < 500 lines; main instructions
  references/       # Supporting docs loaded on demand
  prompts/          # Prompt templates for specific operations
  config/           # Structured data (JSON) for thresholds

Size Limits

• SKILL.md: Under 500 lines. If exceeding, extract into references/, prompts/, or config/
• JiT loading: Reference extracted files with "Read path/to/file for X" instead of inlining content
• No duplication: Never repeat content that exists in subdirectory files

Instruction Voice

1. Third-person imperative: "Review rules for accuracy" not "You are an expert who reviews rules" 2. Step-by-step numbering: Use numbered lists for multi-step processes 3. Concrete templates: Show exact output format, not vague descriptions 4. Action verbs first: "Verify code compiles" not "The code should be verified"

Content Organization

Required Sections (published skills)

1. Title — # Angular <Library> Best Practices 2. Summary — 1-2 sentences on what and why 3. Links — Repository, core skill, browse page 4. When to Apply — 3-5 concrete trigger scenarios 5. Rules table — Rule name, impact, one-line description 6. Install — Core skill + this add-on commands

Required Sections (internal contributor skills)

1. Title — # <Agent Name> 2. Core Mission — What the agent does (1-2 sentences) 3. Process — Numbered steps for the main workflow 4. Tools — Which tools to use and when 5. Output Format — Exact template for results 6. Commands — Example invocations

Terminology Consistency

Use canonical Angular terms throughout:

Validation Checklist

Discovery Validation

• [ ] Description contains positive triggers (what it does)
• [ ] Description contains negative triggers (what it does NOT do)
• [ ] Tags are specific and non-overlapping with other skills
• [ ] Globs match the file types the skill applies to

Logic Validation

• [ ] All code examples use Angular 17+ APIs
• [ ] No deprecated patterns (@Input, *ngIf, constructor injection)
• [ ] Decision criteria are specific with measurable thresholds
• [ ] JiT loading references point to files that exist

Edge Case Testing

• [ ] Skill does not activate for AngularJS (1.x) projects
• [ ] Skill does not activate for React/Vue/Svelte projects
• [ ] Library-specific skills do not overlap with core skill rules
• [ ] Optional skills reference the core skill for installation