bulk-rule-reviewer

Category: Tools & Productivity | Uploader: sfc-gh-myoung | Downloads: 0 | Version: v1.0（Latest）
Execute agent-centric reviews on all rules in rules/ directory and generate prioritized improvement report
Changelog: Source: GitHub https://github.com/sfc-gh-myoung/ai_coding_rules
Directory Structure

Current level: tree/main/skills/bulk-rule-reviewer/
📁 examples/
- 📄 full-bulk-review.md 12.7 KB
- 📄 shortcut-prevention.md 8.0 KB
📁 tests/
- 📄 validation-tests.md 11.7 KB
📁 workflows/
- 📄 aggregation.md 16.2 KB
- 📄 anti-shortcut-checklist.md 5.7 KB
- 📄 context-anchor.md 5.4 KB
- 📄 discovery.md 4.3 KB
- 📄 input-validation.md 6.7 KB
- 📄 inter-rule-gate.md 5.5 KB
- 📄 parallel-execution.md 9.9 KB
- 📄 parameter-collection.md 10.5 KB
- 📄 per-rule-verification.md 4.7 KB
- 📄 proactive-canary.md 4.9 KB
- 📄 reset-trigger.md 5.1 KB
- 📄 review-execution.md 21.5 KB
- 📄 subagent-prompt-template.md 9.2 KB
- 📄 summary-report.md 10.8 KB
📄 SKILL.md 33.8 KB
SKILL.md

---
name: bulk-rule-reviewer
description: Execute agent-centric reviews on all rules in rules/ directory and generate prioritized improvement report
version: 2.2.0
---

# Bulk Rule Reviewer

## Overview

Execute comprehensive agent-centric reviews on all rule files in `rules/` directory, then generate consolidated priority report. Designed for periodic quality audits, pre-release validation, and technical debt tracking.

### When to Use

- Periodic quality audits (quarterly/monthly)
- Pre-release validation before major version releases
- Technical debt tracking and prioritization
- Baseline quality measurement for improvement initiatives

### Inputs

**Required:**
- **review_date**: `YYYY-MM-DD` (default: today)
- **review_mode**: `FULL` | `FOCUSED` | `STALENESS` (default: FULL)
- **model**: Lowercase-hyphenated slug (default: `claude-sonnet-45`)

**Optional:**
- **filter_pattern**: Glob pattern (default: `rules/*.md`)
  - Examples: `rules/100-*.md` (Snowflake only), `rules/*-core.md` (cores only)
- **skip_existing**: Boolean (default: true) - Resume capability
- **overwrite**: Boolean (default: false) - If true, overwrite existing review files. If false, use sequential numbering (-01, -02, etc.) for conflicts
- **max_parallel**: Integer 1-10 (default: 5) - Concurrent sub-agent workers. Set to 1 for sequential execution (legacy behavior)
- **output_root**: Root directory for output files (default: `reviews/`). Subdirectories `rule-reviews/` and `summaries/` appended automatically. Supports relative paths including `../`.
- **timing_enabled**: `true` | `false` (default: `false`) - Enable execution timing

### Outputs

**Individual reviews:** `{output_root}/rule-reviews/<rule-name>-<model>-<date>.md` (up to 187 files)

**Master summary:** `{output_root}/summaries/_bulk-review-<model>-<date>.md` with sections:

(Default `output_root: reviews/`. With `output_root: mytest/` → `mytest/rule-reviews/...` and `mytest/summaries/...`)
1. Executive Summary (score distribution, dimension analysis)
2. Priority 1: Urgent (score <50, NOT_EXECUTABLE)
3. Priority 2: High (score 50-74, NEEDS_REFINEMENT)
4. Priority 3: Medium (score 75-89, EXECUTABLE_WITH_REFINEMENTS)
5. Priority 4: Excellent (score 90-100, EXECUTABLE)
6. Failed Reviews (execution errors)
7. Top 10 Recommendations (impact × effort prioritization)
8. Next Steps (immediate/short-term/long-term)
9. Appendix: All Rules by Score (sorted table)

## Critical Execution Protocol

### CRITICAL: Anti-Optimization Protocol

**FOUNDATIONAL PRINCIPLE:** This skill prioritizes ACCURACY over efficiency.

**Forbidden Optimization Thoughts:**
- "This will take too long"
- "I can save time by..."
- "Token costs are high"
- "The user won't notice if I..."
- "I should ask about time constraints"
- "Let me create a faster approach"
- "Let me batch these rules together"
- "I can validate multiple rules at once"
- "Let me process rules 4-8 efficiently"
- "I'll read several rules before reviewing"

**Required Mindset:**
- "I will complete the full process for each rule"
- "Quality signals are worth the cost"
- "The user authorized ACT knowing the scope"
- "Previous runs completed successfully at this pace"

**If you find yourself thinking about optimizing the review process itself:**
1. STOP
2. Re-read this section
3. Return to the comprehensive process
4. Do NOT ask the user about time/complexity

**IMPORTANT DISTINCTION:**
- Optimizing the SKILL EXECUTION (forbidden)
  - "I can review faster by skipping rubric consultation"
  - "I'll batch these reviews to save time"
  - "Let me create a template"
- Evaluating RULE OPTIMIZATION (required)
  - Scoring Token Efficiency dimension
  - Identifying verbose patterns in rules
  - Recommending rule consolidation

**The user has already considered timing and scope. Proceed with the work.**

### MANDATORY: One Rule At A Time

**NEVER batch multiple rules.** Each rule MUST be processed individually:

1. Read ONE rule file completely
2. Run schema validator for THAT rule
3. Apply ALL 6 scored rubrics to THAT rule
4. Write review file for THAT rule
5. THEN move to next rule

**Forbidden patterns:**
- `for f in rules/*.md; do` (batch shell loops for validation)
- Reading multiple rules before writing any reviews
- "Let me process rules 4-8 together"
- Creating templates to speed up reviews
- Parallelizing any review steps
- Combining schema validation for multiple files
- "Efficient batch processing"

**Why batching fails:**
- Context overflow loses rubric details mid-batch
- Template-based reviews miss rule-specific issues
- Shortcut thinking violates rubric requirements
- Evidence requirements (15+ line refs) impossible without focused reading

**Canary Check - Batching Detection:**

Before EACH rule review, verify:
- [ ] I am reviewing exactly ONE rule
- [ ] I have not combined multiple rules in this tool call
- [ ] My previous tool call was for ONE rule only
- [ ] I am NOT creating a "faster approach"

If ANY check fails: STOP, re-read Anti-Optimization Protocol, resume with ONE rule.

### Required Progress Output

After EACH rule review, output exactly:
```
[N/<total_rules>] Complete: {filename} → {score}/100
```

This output MUST appear after writing EACH review file. If you see yourself planning to output multiple completion messages at once, you are batching - STOP immediately.

### MANDATORY ENFORCEMENT

This skill MUST execute the complete rule-reviewer workflow for each rule file.

### Context Anchor Protocol (CRITICAL)

**These sections MUST remain in active context throughout execution. NEVER summarize or drop them:**

1. **Anti-Optimization Protocol** (this section, lines 52-86)
2. **Skills vs Rules distinction** (lines 188-218)  
3. **Evidence Requirements** (lines 309-345)

**When context pressure occurs:**
- Summarize completed rule file contents FIRST
- Summarize completed review contents SECOND
- NEVER summarize anchor sections

**Structural Enforcement (MANDATORY):** Re-read `TEMPLATE.md` every 5 rules:

```python
if rule_number % 5 == 0:
    read_file("skills/rule-reviewer/examples/TEMPLATE.md")
```

**Drift Detection:** If any review file is <2500 bytes OR format deviates, immediately re-read:
1. `skills/rule-reviewer/examples/TEMPLATE.md` (output format specification)
2. `SKILL.md` (full protocol)

**Format Deviation Check:** After EVERY review, verify the output matches TEMPLATE.md structure:
- Executive Summary table with exact headers: `| Dimension | Raw (0-10) | Weight | Points | Notes |`
- All 7 required sections present in order
- If deviation detected: re-read TEMPLATE.md and regenerate the review

**See:** `workflows/context-anchor.md` and `workflows/inter-rule-gate.md` for full protocol

### How Skills Work Together

**IMPORTANT:** Skills cannot "invoke" other skills programmatically. Skills are documentation that guides agent behavior, not callable subroutines.

**Correct pattern:**
1. Load `skills/rule-reviewer/SKILL.md` to understand the review workflow
2. Load `skills/rule-reviewer/rubrics/*.md` as needed for each dimension
3. Execute the review workflow for each rule file
4. Write review to `reviews/rule-reviews/` following rule-reviewer's output format
5. Continue to next rule

**Why this matters:**
- The rule-reviewer skill documents a proven, high-quality review process
- Following its workflow ensures consistency and completeness
- Progressive disclosure (loading rubrics as needed) manages context efficiently
- Each rule deserves full evaluation per the documented process

### Protocol Violations (FORBIDDEN)

Agents commonly attempt these shortcuts. **ALL ARE FORBIDDEN:**

- **Skipping rubric consultation** - Scoring without reading dimension rubrics
- **Batch optimization** - Aggregating multiple rules into single review
- **Parallel shortcuts** - Running concurrently unless max_parallel set
- **Token-saving shortcuts** - Generating abbreviated reviews
- **Time-saving shortcuts** - Estimating scores without proper analysis
- **Template-based reviews** - Using examples/ as templates without actual analysis
- **Skipping schema validation** - Not running `ai-rules validate`

### Required Actions

- Load rule-reviewer/SKILL.md to understand complete workflow
- Load rubrics/*.md files as needed for each dimension being scored
- Run `ai-rules validate` for each rule
- Perform Agent Execution Test (count blocking issues)
- Score all dimensions according to review_mode (FULL/FOCUSED/STALENESS)
- Generate specific recommendations with line numbers
- Write complete review to reviews/rule-reviews/ with proper formatting
- Follow workflows sequentially (discovery → review-execution → aggregation → summary-report)
- Show progress every 10 reviews (not more frequently)

### Progress Display Protocol

**CRITICAL: Minimize console output during execution.**

Canary checks, dimension scoring, and evidence gathering are INTERNAL PROCESSING.
Do NOT display intermediate analysis to the user.

**Starting/Complete examples:**
- `[45/<total_rules>] Starting: 310-zsh-scripting-core.md`
- `[45/<total_rules>] Complete: 310-zsh-scripting-core.md → 95.5/100`
- Every 10 rules: brief aggregate summary (e.g., "Progress: 50/<total_rules>, avg 87.2")

**DO NOT DISPLAY (internal processing only):**
- Pre-Rule Canary check questions/answers
- Post-Read Canary verification details
- Agent Execution Test blocking issue scans
- Dimension score calculations and breakdowns
- Evidence citations during processing
- Rubric consultation notes
- "3 unique things" verification output

**Rationale:** Canary checks ensure quality but are self-verification, not user communication.
The review FILE contains all evidence and analysis. Console output should show only progress.

**If canary check FAILS:** Log failure reason briefly, then proceed with reset protocol.

### Execution Acknowledgment

**Before proceeding, agent must confirm:**
- [ ] Will follow rule-reviewer workflow for each rule (complete process)
- [ ] Will load and consult rubrics for dimension scoring
- [ ] Will run schema validation for each rule
- [ ] Will perform Agent Execution Test for each rule
- [ ] Will NOT optimize for time/tokens at expense of quality
- [ ] Will NOT calculate projected completion times
- [ ] Will NOT ask about time constraints mid-execution
- [ ] Will NOT create template-based reviews
- [ ] Will NOT propose "faster" alternatives
- [ ] Will use resume capability (skip_existing) if interrupted

**If cannot commit to ALL items: STOP and report error.**

### Why This Process Cannot Be Shortened

**CRITICAL UNDERSTANDING:**

This skill is designed for **quality assurance**, not efficiency. Short-circuiting defeats its purpose.

**Agent Behavior Pattern Observed:**
Agents frequently attempt to "optimize" by:
- Creating template-based reviews without analysis
- Asking about time constraints mid-execution
- Proposing "streamlined" approaches
- Calculating projected completion times
- Expressing concern about token costs

**ALL OF THESE ARE FORBIDDEN.**

**Why Agents Do This:**
- Pattern matching to "helpful" behavior (offering options)
- Misapplying token-efficiency principles from rules to skills
- Anthropomorphizing user patience/time constraints
- Attempting to be "considerate" of resources

**Why This Is Wrong:**
1. **User has already authorized:** "ACT" means proceed with full scope
2. **Scope is acceptable:** Comprehensive review of all rules is expected
3. **Quality cannot be compromised:** One bad rule costs more than comprehensive review
4. **Skills ≠ Rules:** Token efficiency principles don't apply here

**Correct Behavior:**
- Execute the full workflow for each rule
- Do NOT calculate or mention projected completion times
- Do NOT ask about time constraints
- Do NOT propose "faster" alternatives
- Trust that the user understands the scope

**Detection Test:**
If you're thinking "Should I ask the user about..." - the answer is NO.
The user authorized ACT. Proceed with the work.

**Skills vs. Rules - Different Optimization Goals:**

**Rules (e.g., 100-snowflake-core.md):**
- **Usage Frequency:** Loaded repeatedly (100s-1000s of times)
- **Token Efficiency:** CRITICAL (repeated cost multiplier)
- **Optimization Goal:** Minimize tokens while preserving quality
- **Acceptable Size:** Minimize (5K-8K tokens ideal)
- **Design Priority:** Token budget discipline

**Skills (e.g., bulk-rule-reviewer):**
- **Usage Frequency:** Used occasionally (quarterly/monthly)
- **Token Efficiency:** IRRELEVANT (one-time QA cost)
- **Optimization Goal:** Maximize quality regardless of tokens
- **Acceptable Size:** Whatever it takes (50K-100K acceptable)
- **Design Priority:** Comprehensive coverage

**Why This Matters:**

You may have noticed rule files emphasize token efficiency (TokenBudget metadata, optimization guidelines). That's correct for rules because they're loaded frequently by many agents.

**Skills are different.** They're used for specialized tasks a few times per year. Token efficiency is NOT a design goal for skills.

**Example:**
- **Rule (100-snowflake-core.md):** Loaded 100+ times per month → 5K tokens × 100 = 500K monthly cost → Token efficiency matters
- **Skill (bulk-rule-reviewer):** Used 4 times per year → 50K tokens × 4 = 200K annual cost → Token efficiency irrelevant

**For this skill specifically:**
- **Cost:** ~50K tokens × 4 reviews/year = 200K tokens/year ≈ $1.80 annually
- **Value:** Comprehensive quality assurance for the full current rule set
- **ROI:** One prevented bad rule saves 10-100× the token cost

**DO NOT apply rule token-efficiency principles to skill execution.**

**Common Efficiency Instincts (ALL WRONG):**

1. **"I can create streamlined reviews to save time"**
   - **Reality:** Streamlined reviews miss critical issues
   - **Impact:** False confidence in rule quality, undetected blocking issues
   - **Consequence:** Agents fail in production with "streamlined" rules

2. **"Template-based reviews are consistent"**
   - **Reality:** Templates skip actual analysis
   - **Impact:** Miss rule-specific issues, score drift, no improvement signal
   - **Consequence:** Repository degrades over time with passing scores

3. **"Batch processing multiple rules is efficient"**
   - **Reality:** Aggregation loses per-rule detail
   - **Impact:** Cannot track individual rule improvements
   - **Consequence:** Actionable recommendations impossible

4. **"This will take too long"**
   - **Reality:** Comprehensive review completes efficiently with measured execution
   - **Impact:** Premature optimization based on incorrect estimate
   - **Consequence:** Unnecessary shortcuts for non-existent problem

5. **"Token costs are too high"**
   - **Reality:** 50K tokens ≈ $0.45 for repository-wide quality audit (quarterly = $1.80/year)
   - **Impact:** False economy—one bad rule costs more in debugging
   - **Consequence:** Penny-wise, pound-foolish optimization
   - **Category Error:** Applying rule token-efficiency principles to skill execution (wrong context)

**The Real Cost:**
- Short-circuited review: 5 minutes, $0.05, ZERO quality signal
- Comprehensive review: Produces actionable improvements across the current repository
- Debugging one bad rule in production: 2+ hours, frustrated users

**Annual Economic Reality:**

- **Annual skill usage:** 4 bulk reviews
- **Cost per review:** $0.45 (50K tokens)
- **Annual cost:** $1.80
- **One bad rule in production:** Debug time 2-4 hours, token cost 50K-100K ($0.45-$0.90), opportunity cost from delayed features
- **Cost to prevent:** $0.45 per review
- **ROI:** 10-100× return

**Token Efficiency Category Error:**

Skills are NOT rules. Do not apply rule optimization principles here:
- "Skills should be token-efficient like rules" → WRONG context
- "Skills should be comprehensive regardless of tokens" → CORRECT context

**When Shortcuts Are Acceptable:**
**NEVER.** If time/tokens are constraints, use these instead:
- Set `filter_pattern` to review subset (e.g., `rules/100-*.md`)
- Set `review_mode: STALENESS` for quick check (1 dimension)
- Split into multiple sessions with `skip_existing: true`

**DO NOT create a "fast mode" that compromises quality.**

**Time Expectations (Measured - DO NOT RECALCULATE):**

**Actual Performance (2026-01-06 run):**
- Current repository rule count reviewed comprehensively
- Execution completes efficiently

**DO NOT:**
- Recalculate these numbers during execution
- Project "time remaining"
- Express concern about duration
- Ask if this is acceptable

**These numbers are provided for INFORMATION only.**
**Your job is to execute, not to optimize or question timing.**

**If you find yourself calculating time:**
- STOP
- You're optimizing instead of executing
- Return to the workflow

### Verification

Each review must contain:
- Executive Summary with scores table (all 6 dimensions for FULL mode)
- Schema Validation Results (from `ai-rules validate` output)
- Agent Executability Verdict (based on Agent Execution Test)
- Dimension Analysis sections (detailed scoring rationale)
- Critical Issues list (specific line numbers)
- Recommendations (prioritized with expected score improvements)
- Post-Review Checklist
- Conclusion

**CRITICAL: Evidence-Based Verification (MANDATORY)**

Every review MUST include evidence proving the file was actually read:

| Requirement | Minimum | Example |
|-------------|---------|---------|
| Line references | ≥15 distinct | "line 47", "lines 120-135" |
| Direct quotes | ≥3 with line numbers | `Line 156: "Use pd.to_datetime() with explicit format"` |
| Metadata citation | TokenBudget value | "TokenBudget ~6550 declared at line 12" |
| Pattern names | ≥2 exact names | "Anti-Pattern 2: Using Deprecated datetime.utcnow()" |
| Code references | ≥1 function/class name | "The `ensure_python_datetime()` helper at lines 330-350" |

**Zero-Recommendation Rule:**

Reviews with "No recommendations" or "None required" MUST justify with:
1. At least 3 specific attempts to find issues (with line references)
2. Explicit statement: "Searched for [X, Y, Z] issues at lines [A, B, C] - none found"

**If a review contains zero recommendations AND zero line references = AUTOMATIC REJECTION**

Even excellent rules (95-100 score) should have at least LOW severity suggestions:
- Minor terminology consistency opportunities
- Potential future-proofing considerations
- Cross-reference enhancement possibilities
- Example expansion opportunities

**Violation consequences:**
- Invalid reviews rejected from summary
- Execution halted with protocol violation error
- User notified of shortcut attempt

**Quality gate:**
- Review file size 3000-8000 bytes (typical for FULL mode)
- < 2000 bytes = too abbreviated (VIOLATION)
- All required sections present (VIOLATION if missing)
- ≥15 line references present (VIOLATION if missing)
- ≥3 direct quotes with line numbers (VIOLATION if missing)

### Shortcut Detection and Prevention

**During execution, HALT immediately if agent exhibits:**

**RED FLAGS (Stop and Self-Correct):**

1. **Suggesting efficiency improvements mid-review**
   - Example: "To save time, I'll create streamlined reviews..."
   - **Action:** STOP. Re-read this skill. Return to comprehensive process.

2. **Creating reviews <2500 bytes (FULL mode)**
   - **Detection:** `wc -c review_file` shows <2500
   - **Action:** DELETE abbreviated review. Re-do with full analysis.

3. **Not loading rubrics before scoring**
   - **Detection:** Dimension score provided without `read_file(rubrics/[dimension].md)`
   - **Action:** HALT. Load rubric. Re-score with rubric guidance.

4. **Batch processing mentions**
   - Example: "I'll process rules 1-10 together..."
   - **Action:** STOP. Review one rule at a time. No exceptions.

5. **Skipping schema validation**
   - **Detection:** Review lacks "Schema Validation Results" section with actual output
   - **Action:** HALT. Run `ai-rules validate`. Include output.

6. **Using examples/ as templates**
   - **Detection:** Review text matches example patterns without rule-specific details
   - **Action:** DELETE review. Re-analyze actual rule content.

7. **Time/token concerns mentioned**
   - Example: "Given the large number of rules..."
   - **Action:** STOP. Re-read "Why This Process Cannot Be Shortened" section.

8. **Applying rule optimization to skills**
   - Example: "To improve token efficiency..." (category error)
   - **Action:** STOP. Skills are NOT rules. Different optimization goals.

**HALT IMMEDIATELY if you:**
1. Generate review text without reading the actual rule file
2. Use the same review text for multiple rules
3. Create reviews in a loop without individual analysis
4. Think "I'll create a template and fill in details"
5. Calculate "time remaining" or "rules per minute"
6. Consider asking the user about scope/timing

**Self-Correction Trigger Words:**
If you think or write any of these phrases, you're taking a shortcut:
- "To save time..."
- "For efficiency..."
- "Given the large number..."
- "This would take approximately..."
- "Should I continue with..."
- "Would you prefer..."
- "Let me create a streamlined..."

**Immediate Action:**
1. DELETE any work done with shortcuts
2. Re-read the Anti-Optimization Protocol
3. Resume comprehensive process
4. Do NOT notify user of the self-correction (just fix it)

**Self-Correction Protocol:**

**If shortcut detected:**
1. ACKNOWLEDGE: "I was attempting [shortcut]. This violates skill protocol."
2. DELETE: Remove any abbreviated/templated reviews created
3. RESET: Re-read bulk-rule-reviewer/SKILL.md and rule-reviewer/SKILL.md
4. RESUME: Return to comprehensive process at last valid checkpoint
5. COMMIT: "I will complete comprehensive reviews without shortcuts."

**User Intervention:**

If agent repeatedly attempts shortcuts despite self-correction:
- User should STOP execution
- Report skill design flaw
- Do NOT proceed with compromised reviews


## Workflow

### Parameter Collection

Collect ALL parameters (required AND optional) using `ask_user_question` tool.

**See:** `workflows/parameter-collection.md`

**MANDATORY:** Prompt for ALL parameters in batched questions (max 4 per call):
- Do NOT silently apply defaults for optional parameters
- User must explicitly confirm each setting
- If `ask_user_question` unavailable, fall back to text-based prompting

### [OPTIONAL] Timing Start

**When:** Only if `timing_enabled: true` in inputs  
**MODE:** Safe in PLAN mode

**See:** `../skill-timing/workflows/timing-start.md`

**Action:** Capture `run_id` in working memory for later use.

**Note:** Timing tracks the entire bulk review process (all stages), not individual rule-reviewer calls.

### [OPTIONAL] Checkpoint: skill_loaded

**When:** Only if timing was started  
**Checkpoint name:** `skill_loaded`

**See:** `../skill-timing/workflows/timing-checkpoint.md`

### Stage 1: Discovery

Find all `.md` files in `rules/` directory, apply filter_pattern, sort alphabetically.

**See:** `workflows/discovery.md`

### [OPTIONAL] Checkpoint: discovery_complete

**When:** Only if timing was started  
**Checkpoint name:** `discovery_complete`

**See:** `../skill-timing/workflows/timing-checkpoint.md`

### Stage 2: Review Execution (Parallel or Sequential)

**Execution mode depends on `max_parallel` parameter:**

#### Parallel Execution (default: max_parallel ≥ 2)

When `max_parallel >= 2`, use parallel sub-agents for faster execution:

1. **Partition rules** into N groups (where N = max_parallel)
2. **Launch N sub-agents** in background, each assigned a group
3. **Each sub-agent** loads rule-reviewer skill and processes its rules independently
4. **Monitor progress** via agent_output polling
5. **Aggregate results** when all sub-agents complete

**Benefits:**
- 5× speedup (~50 minutes instead of 4-6 hours)
- Fresh context per sub-agent (eliminates drift)
- Isolated failures (one agent failing doesn't stop others)

**See:** `workflows/parallel-execution.md` for full implementation
**See:** `workflows/subagent-prompt-template.md` for sub-agent prompt

**File writes:** All sub-agents write directly to `{output_root}/rule-reviews/`. No conflicts because each sub-agent reviews different rules (unique filenames).

#### Sequential Execution (max_parallel = 1)

When `max_parallel = 1`, use legacy sequential processing (single agent reviews all rules).

**Use sequential when:**
- Debugging/troubleshooting the skill
- Very small rule sets (< 10 rules)
- Explicit user preference

---

**CRITICAL: This is where shortcut temptation peaks. Resist it.**

**Execution Protocol: No Mid-Stream Questions**

**RULE:** Once user types "ACT", do NOT:
- Ask about time constraints
- Propose alternative approaches
- Calculate projected completion times
- Express concern about scope
- Request clarification on depth/quality trade-offs

**The ACT command means:**
- User understands the scope of a full-repository review
- User wants comprehensive reviews (3000-8000 bytes each)
- User prioritizes accuracy over speed

**If you catch yourself about to ask "Should I..." or "Would you prefer...":**
- STOP
- The answer is: Continue with comprehensive reviews
- Return to the workflow

For each rule file:
1. **INTER-RULE GATE (every 5 rules):** If rule_number % 5 == 0, execute `workflows/inter-rule-gate.md`
2. **PRE-RULE CANARY:** Execute 3 canary questions from `workflows/proactive-canary.md`
3. Extract rule name from path
4. Check if review exists (if skip_existing=true)
5. **READ the actual rule file into working memory**
6. **POST-READ CANARY:** Verify you can name 3 specific things unique to THIS rule
7. **LOAD rule-reviewer/SKILL.md if not already loaded**
8. **LOAD relevant rubrics for dimensions being scored**
9. **RUN `ai-rules validate` on the rule file**
10. **PERFORM Agent Execution Test (count blocking issues)**
11. **MID-REVIEW CANARY (after dimension 3):** Check rubric loading and reference reuse
12. **SCORE each dimension according to rubric, citing line numbers and quotes**
13. **GENERATE specific recommendations with line numbers**
14. **VERIFY review authenticity (see workflows/per-rule-verification.md)**
    - Must have ≥15 line references
    - Must cite direct quotes from rule
    - Must include rule-specific findings
    - **FAILURE triggers `workflows/reset-trigger.md`**
15. **WRITE complete review to reviews/rule-reviews/ directory** (respects overwrite parameter)
16. Store (rule_name, score, verdict, review_path)
17. Show progress every 10 reviews

**CRITICAL:** Step 5 (READ the actual rule file) MUST happen BEFORE steps 10-13. Reviews generated without reading the file will fail verification at step 14.

**DRIFT PREVENTION:** Steps 1, 2, 6, 11 are canary/gate checks that detect optimization drift BEFORE it produces compromised output. These are NOT optional.

**Time per rule:** Efficient execution with comprehensive analysis
**Quality:** Comprehensive, reliable, actionable

**ANTI-PATTERN ALERT:**

If you're thinking ANY of these thoughts, STOP and re-read this skill:
- "This will take too long" → Comprehensive review completes efficiently
- "I can optimize this" → NO. Quality > efficiency
- "Templates would be faster" → Templates = zero signal
- "Token costs are high" → $0.45 for 129 rules is cheap QA (Skills ≠ Rules)
- "Users won't notice abbreviated reviews" → They will. Bad rules escape.

**Correct Agent Self-Talk During Execution:**

**WRONG (Optimization-Seeking):**
- "I've done 10 rules in 8 minutes, so 129 will take 90 minutes..."
- "This seems like a lot of work, should I ask the user?"
- "Maybe I can create a template to speed this up..."
- "Let me calculate the token cost..."

**RIGHT (Execution-Focused):**
- "Next rule: 101a-snowflake-streamlit-visualization.md"
- "Reading rule file... Running schema validation... Counting blocking issues..."
- "Scoring dimension 1: Actionability... Evidence: line 52..."
- "Writing review... Next rule: 101b-snowflake-streamlit-performance.md"

**Notice the difference:**
- WRONG: Meta-thinking about the process
- RIGHT: Executing the process

**Your internal monologue should be task steps, not process analysis.**

**Reminder:** 
- ONE bad rule in production costs 100× more than comprehensive review
- Skills are NOT rules → Token efficiency is irrelevant (different optimization goals)

**See:** `workflows/review-execution.md` for orchestration details, resume capability, error handling.

### [OPTIONAL] Checkpoint: reviews_complete

**When:** Only if timing was started  
**Checkpoint name:** `reviews_complete`

**See:** `../skill-timing/workflows/timing-checkpoint.md`

### Stage 3: Aggregation

For each review file:
1. Read first 150 lines only (context management)
2. Extract: overall score, verdict, critical issues, dimension scores
3. Build lightweight data structure (no full content)
4. Calculate statistics: average, median, distribution

**See:** `workflows/aggregation.md` for parsing strategy and statistics calculations.

### [OPTIONAL] Checkpoint: aggregation_complete

**When:** Only if timing was started  
**Checkpoint name:** `aggregation_complete`

**See:** `../skill-timing/workflows/timing-checkpoint.md`

### Stage 4: Summary Report

Generate master summary with:
- Prioritized sections (Priority 1-4)
- Rules sorted by score within tiers
- Impact × effort ratios for recommendations
- Write to `reviews/summaries/_bulk-review-<model>-<date>.md`

**See:** `workflows/summary-report.md` for report format and section generation.

### [OPTIONAL] Checkpoint: summary_complete

**When:** Only if timing was started  
**Checkpoint name:** `summary_complete`

**See:** `../skill-timing/workflows/timing-checkpoint.md`

### [OPTIONAL] Timing End (Compute)

**When:** Only if timing was started  
**MODE:** Safe in PLAN mode (outputs to STDOUT only)

**See:** `../skill-timing/workflows/timing-end.md` (Step 1)

**Action:** Capture STDOUT output for metadata embedding.

### [MODE TRANSITION: PLAN → ACT]

Request user ACT authorization before file modifications.

### [OPTIONAL] Timing End (Embed)

**When:** Only if timing was started  
**MODE:** Requires ACT mode (appends metadata to file)

**See:** `../skill-timing/workflows/timing-end.md` (Step 2)

**Action:** Parse STDOUT, append timing metadata section to summary report file.

## Critical Design Decisions

**Context Management:** Parse only first 150 lines of each review (scores/verdicts only). Full details remain in individual files.

**Stateless Execution:** Review failures don't stop batch. Resume via skip_existing parameter.

**See:** `workflows/aggregation.md` for complete strategy.

## Error Handling

**Review failure:** Continue with next file, log error, mark FAILED in summary.

**Context overflow:** Switch to minimal output mode, report warning, continue.

**File write failure:** Print OUTPUT_FILE directive for manual save, continue.

**Empty rules directory:** Report error, exit gracefully without empty summary.

**Partial completion:** Resume capability allows continuation using existing reviews.

## Usage Examples

### Basic Invocation (All Rules, Full Review)

```
Use the bulk-rule-reviewer skill.

review_date: 2026-01-06
review_mode: FULL
model: claude-sonnet-45
```

### Filtered Review (Snowflake Rules Only)

```
Use the bulk-rule-reviewer skill.

review_date: 2026-01-06
review_mode: FULL
model: claude-sonnet-45
filter_pattern: rules/100-*.md
```

### Force Re-Review (Overwrite Existing)

```
Use the bulk-rule-reviewer skill.

review_date: 2026-01-06
review_mode: FULL
model: claude-sonnet-45
overwrite: true
```

**Note:** Use `overwrite: true` to replace existing reviews. Use `skip_existing: false` combined with `overwrite: false` (default) to create new versions with sequential numbering (-01, -02).

### Re-Review with Sequential Numbering (Preserve History)

```
Use the bulk-rule-reviewer skill.

review_date: 2026-01-06
review_mode: FULL
model: claude-sonnet-45
skip_existing: false
overwrite: false
```

This creates `-01`, `-02` versions without overwriting previous reviews.

### Staleness Check Only

```
Use the bulk-rule-reviewer skill.

review_date: 2026-01-06
review_mode: STALENESS
model: claude-sonnet-45
```

## Success Criteria

- All matching rules reviewed (or filtered subset)
- Individual review files written to `reviews/rule-reviews/`
- Master summary report generated with valid path
- Prioritized improvement list included
- No context overflow during execution
- Resume capability functional (existing reviews skipped)
- Error handling graceful (failed reviews don't stop batch)

## Expected Outcomes

**Score distribution:** Average, median, distribution by priority tier.

**Dimension analysis:** Average scores for all 6 dimensions.

**Critical issues summary:** Count of rules with 0, 1-2, 3+ critical issues.

**Prioritized recommendations:** Top 10 rules to improve (impact × effort), estimated effort, expected score improvement.

**Next steps:** Immediate actions, short-term goals, long-term strategy.

## Installation Requirements

**Dependency:** rule-reviewer skill (required)

**Skill location resolution supports two patterns:**

1. **Installed Skill (Recommended):** Install `rule-reviewer` via agent tool's skill management
2. **Local Skill (Fallback):** Ensure `skills/rule-reviewer/` exists in project

**Auto-detection:** Automatically detects which pattern is available.

**Error handling:** If neither found, execution stops with installation guidance.

## Validation

**See:** `workflows/input-validation.md` for validation workflow and code patterns.

**Key Requirements:**
- `review_date`: YYYY-MM-DD format (valid calendar date)
- `review_mode`: FULL | FOCUSED | STALENESS (uppercase)
- `model`: lowercase-hyphenated (e.g., claude-sonnet-45)
- `filter_pattern`: rules/*.md glob (optional, must match ≥1 file)
- `skip_existing`: boolean true/false (optional, default: true)
- `max_parallel`: integer 1-10 (optional, default: 1)
- Environment: rules/ exists and readable, reviews/rule-reviews/ and reviews/summaries/ writable

**Execution:** Validate inputs before Stage 1 (Discovery). Fail fast on errors.

## Examples

- `examples/full-bulk-review.md` - Complete walkthrough example

## Related Skills

- **rule-reviewer** - Single rule review (required dependency)
- **rule-creator** - Create new rules (complementary)

## References

### Rules

- `rules/002h-claude-code-skills.md` - Skill authoring best practices
- `rules/002-rule-governance.md` - Rule schema and standards
- `rules/000-global-core.md` - Foundation patterns
Comments 0
Latest | Hot
Please login before commenting.
Loading comments...