Bug Fix 🐛

Prevents qe-writing-002 from creating violations of qe-writing-001 when suggesting to break up long sentences.

Problem

qe-writing-002 was suggesting to break long sentences into multiple sentences, but NOT adding blank lines between them:

❌ Bad suggestion:
But we can model time series with persistent growth. These models use a law of large numbers.

This violated qe-writing-001 (one sentence per paragraph - separated by blank lines).

Solution

• ✅ Added inline constraint to qe-writing-002: "Breaking long sentences up can be useful sometimes, but each sentence must be in its own paragraph block separated by blank lines"
• ✅ Changed category from rule to style (advisory rather than mechanical)
• ✅ Self-contained explanation (no need for external links)

Correct Behavior Now

✅ Good suggestion:
But we can model time series with persistent growth.

These models use a law of large numbers.

Impact

• Prevents conflicting edits between rules processed sequentially
• Maintains consistency with qe-writing-001
• Clear guidance for LLM on proper sentence breaking

Full Changelog: https://github.com/QuantEcon/action-style-guide/blob/main/CHANGELOG.md

Simplification ✨

Removes a redundant and confusing CRITICAL instruction from the writing prompt.

What Changed

• ❌ Removed: "CRITICAL: The 'Current text' and 'Suggested fix' MUST be different (fixes must change something). Even if the visual difference is subtle (like whitespace changes), ensure the suggested fix actually corrects the violation."

Why

1. Redundant: Obviously fixes should change something - that's what "fix" means!
2. Confusing: Was causing LLM to second-guess valid fixes, especially whitespace changes
3. Already handled: The validate_fix_quality() function already checks if current_text == suggested_fix
4. Simpler is better: Following "simplicity above all" principle

Result

• ✅ Cleaner, more focused prompt
• ✅ Less confusion for the LLM
• ✅ Relies on existing validation logic instead of pre-warning
• ✅ Updated writing prompt version to 0.3.23

Full Changelog: https://github.com/QuantEcon/action-style-guide/blob/main/CHANGELOG.md

Bug Fix 🐛

Fixes issue where whitespace violations (qe-writing-008) were being detected but not applied.

Problem

• LLM detected 6 whitespace violations
• All 6 were skipped: "Applied 0/6 fixes"
• Warning: "Fix quality warnings: 6"
• Root cause: Prompt instruction "Current text and Suggested fix MUST be different" was interpreted too strictly
• LLM avoided reporting whitespace fixes because they looked visually "the same"

Solution

• ✅ Clarified CRITICAL instruction: "must change something" instead of "MUST be different"
• ✅ Added explicit note: "Even if the visual difference is subtle (like whitespace changes), ensure the suggested fix actually corrects the violation"
• ✅ LLM now understands that subtle differences (whitespace) are valid and important

Impact

• Fixes qe-writing-008 (Remove excessive whitespace) rule application
• Should improve fix application rate for all subtle text changes
• Updated writing prompt version to 0.3.22

Full Changelog: https://github.com/QuantEcon/action-style-guide/blob/main/CHANGELOG.md

Critical Fix 🚨

This is a patch release fixing a critical bug introduced in v0.3.19 that prevented PR comments from displaying violation details.

What Was Broken

• Parser couldn't extract Current text and Suggested fix from LLM responses
• PR comments showed violations without the actual problematic text or fixes
• Caused by mismatch: prompts instructed LLM to use ~~~markdown fences, but parser only looked for \``markdown`

What's Fixed

• ✅ Parser now accepts both backtick (```) and tilde (~~~) code fences
• ✅ Regex patterns updated: (?:\``|~~~)` matches either fence type
• ✅ PR comments now correctly display Current text and Suggested fix sections

Impact

• Severity: Critical - affected all PR comment generation
• Introduced: v0.3.19 (when we switched to tilde fences)
• Fixed: v0.3.21

Recommendation: Update immediately if using v0.3.19 or v0.3.20

Full Changelog: https://github.com/QuantEcon/action-style-guide/blob/main/CHANGELOG.md

What's Changed

Improved Writing Prompt Clarity

• Accurate single-rule processing: Updated prompt to reflect that we check one rule at a time, not all rules at once
• Clearer instructions: Emphasizes checking ONLY the provided rule, avoiding confusion
• Simplified category descriptions: Concise explanations of rule vs style categories
• Better focused output: Rule-specific summary messages

Bug Fixes

• Fixed qe-writing-001 false positives: Simplified rule definition to prevent reporting already-correct text
• Fixed duplicate explanations in PR comments: Removed list formatting from all category prompts (affects all 8 categories)

Technical Details

• Updated version metadata in prompts to reflect architecture
• Follows "simplicity above all" principle from development guidelines
• More maintainable and understandable prompt structure

Files Changed: 11 files (prompts, rules, version)
Categories Affected: All 8 (writing, math, code, jax, figures, references, links, admonitions)

Full Changelog: https://github.com/QuantEcon/action-style-guide/blob/main/CHANGELOG.md

What's Changed

LLM Prompt Output Format Updates

This release completes the migration to tilde fence markers by updating all LLM prompts to use the same format in their output examples.

Changed

• LLM prompt output format - Updated all 8 category prompts to use tilde fences in output examples
  • Changed from triple backticks to ~~~markdown for "Current text" and "Suggested fix" blocks in prompt templates
  • LLM now generates responses that match GitHub handler's tilde fence format (v0.3.16)
  • Ensures consistency between what LLM is instructed to output and what GitHub handler expects
  • Completes migration from 4-backtick approach (v0.3.15) to tilde fence standard

Technical Details

• Affects all category prompts: writing, math, code, jax, figures, references, links, admonitions
• LLM instructions now show ~~~markdown fences for code block examples
• Maintains compatibility with nested MyST Markdown directives containing triple backticks
• All tests updated and passing

Full Changelog: v0.3.16...v0.3.17

Changed

• PR comment markdown formatting - Use four backticks for code blocks to prevent rendering issues when MyST Markdown content contains nested directives with three-backtick code blocks
• Affects all PR comment formatting functions

🎨 Two-Comment PR System

This release introduces intelligent separation of automatic fixes from style suggestions requiring human review.

Key Changes

Separate Handling for Rule vs Style Categories:

• Rule category violations (mechanical fixes) - Automatically applied
  • Rules: qe-writing-001, 002, 004, 005, 006, 008
  • Applied fixes posted as collapsible PR comment for reference
• Style category violations (subjective suggestions) - Require human review
  • Rules: qe-writing-003 (logical flow), 007 (visual elements)
  • Suggestions posted as OPEN PR comment for immediate visibility
  • Prevents over-enthusiastic LLM from making subjective changes

New PR Comment Structure:

• Comment 1: Applied Fixes Report (collapsible) - Reference for what was automatically fixed
• Comment 2: Style Suggestions Report (open) - Prominently visible for human review

Technical Implementation

• Enhanced rule extraction to capture category field from rule definitions
• Modified review logic to filter fixes by category before applying
• Added two new comment formatters: format_applied_fixes_report() and format_style_suggestions_report()
• Updated main.py to post two separate PR comments based on violation category

Why This Matters

This change addresses the observation that "style type fixes the LLM is sometimes over enthusiastic." By separating mechanical fixes (automatically applied) from stylistic suggestions (human review required), we maintain automation efficiency while preserving editorial control over subjective improvements.

Full Changelog: https://github.com/QuantEcon/action-style-guide/blob/main/CHANGELOG.md

v0.3.13 - Complete Single-Rule Evaluation System

🎯 Major Achievement: Guaranteed Comprehensive Rule Coverage

This release completes the implementation of the single-rule evaluation architecture, ensuring every rule is checked with proper sequential fix application and optimal evaluation order.

✨ What's New

Hardcoded Rule Evaluation Order

• Optimal sequence guaranteed: Rules now checked in scientifically-determined priority order
• Order: Mechanical → Structural → Stylistic → Creative
• Writing rules priority:
  1. qe-writing-008: Whitespace formatting (mechanical)
  2. qe-writing-001: Paragraph structure (structural)
  3. qe-writing-004: Capitalization (mechanical)
  4. qe-writing-006: Title capitalization (mechanical)
  5. qe-writing-005: Bold/italic formatting (mechanical)
  6. qe-writing-002: Clarity and conciseness (stylistic)
  7. qe-writing-003: Logical flow (creative)
  8. qe-writing-007: Visual elements (creative)

Sequential Fix Application (v0.3.12)

• Fixed critical bug: Each rule now checks the content AFTER previous fixes applied
• Before: All rules checked original content, then all fixes applied at end
• After: Rule 008 → fix → Rule 001 checks updated content → fix → Rule 004 checks updated content...
• Result: More accurate detection, fewer duplicate violations

Rule Numbering Reverted (v0.3.11)

• Restored original rule numbering (001=paragraph, 002=clarity, etc.)
• Renumbering experiment (v0.3.10) didn't solve LLM focus issues
• Maintenance simplicity prioritized over numbering schemes

🏗️ Architecture

Single-Rule Evaluation

• 8 separate LLM calls (one per writing rule)
• Each rule gets focused attention with only that rule in the prompt
• Guaranteed coverage: Impossible for LLM to skip rules
• Sequential processing: Each rule sees results of previous fixes

Trade-offs

• ✅ Reliability: 100% guaranteed comprehensive rule coverage
• ✅ Accuracy: Later rules check cleaned content, not original messy content
• ✅ Transparency: Clear which rule found which violation
• ❌ Cost: 8× API calls for writing category (more expensive)
• ❌ Time: Takes longer due to sequential processing

📊 Reporting

PR Body (Summary)

• Total issues count from ALL 8 rules
• Grouped by category and rule
• First 2 examples per rule
• Concise and scannable

Detailed Report (PR Comment)

• EVERY violation from ALL 8 rules
• Complete details: location, current text, fix, explanation
• Organized by category
• Posted as collapsible comment

🔧 Technical Details

Evaluation Order: Defined in RULE_EVALUATION_ORDER constant (reviewer.py)
Fix Application: Immediate after each rule (current_content updated)
Violation Collection: Accumulated in all_violations array
Reporting: Uses complete violations array at the end

📈 Version History (Recent)

• v0.3.13 (2025-10-10): Hardcoded optimal rule evaluation order
• v0.3.12 (2025-10-10): Sequential fix application after each rule
• v0.3.11 (2025-10-10): Single-rule evaluation architecture, reverted numbering
• v0.3.10 (2025-10-10): Rule renumbering experiment (reverted in v0.3.11)
• v0.3.9 (2025-10-10): Detailed reports as PR comments

🚀 Upgrade Guide

No breaking changes for users. The action now:

1. Checks rules in optimal order automatically
2. Applies fixes sequentially for better accuracy
3. Provides comprehensive reporting from all rules

Simply use the latest version:

uses: QuantEcon/action-style-guide@v0.3.13
# or use floating tag for latest v0.3.x
uses: QuantEcon/action-style-guide@v0.3

📝 Full Changelog

See CHANGELOG.md for complete details.

🐛 Bug Fix Release

This release fixes a critical issue where PRs would fail to create when the description exceeded GitHub's 65KB limit.

Fixed

PR Body Length Error (422 Validation Failed)

• Fixed "body is too long (maximum is 65536 characters)" error
• Completely redesigned PR description format to be much more concise
• Now groups violations by rule instead of listing each individually
• Shows first 2 examples per rule with count (e.g., "15 occurrences")
• Includes automatic truncation at 60KB with warning if needed
• Reduces PR body size by ~90% for lectures with many violations
• All details still available in the diff

Changed

Added Version to PR Description

• PR body now includes action version in summary section
• Makes it easy to track which version created each PR

Example New Format

Before (could be 100KB+):

• Listed every single violation with full current/fix text
• Could easily exceed 65KB limit

After (typically <10KB):

This format is much more scannable and stays well under the GitHub limit even for lectures with 100+ violations.

Full Changelog: https://github.com/QuantEcon/action-style-guide/blob/main/CHANGELOG.md