ace-review 0.49.0

data/handbook/prompts/focus/phase/correctness.md

@@ -0,0 +1,51 @@
+---
+name: correctness
+description: Correctness-focused review - logic errors, missing functionality, and bugs
+last-updated: '2026-02-16'
+---
+
+# Correctness Focus
+
+## What to Review
+
+### Logic Errors & Bugs
+- Off-by-one errors, boundary conditions, nil/null handling
+- Incorrect boolean logic, missing negations, wrong operators
+- Race conditions and concurrency issues
+- Infinite loops or unreachable code paths
+- Type mismatches and coercion errors
+
+### Missing Functionality
+- Unhandled edge cases specified in requirements
+- Missing return values or incomplete branches
+- Required validations that are absent
+- Promised behavior not implemented
+
+### Error Handling
+- Exceptions that are swallowed silently
+- Missing error handling for I/O, network, or system calls
+- Error messages that leak internal details
+- Recovery paths that leave state inconsistent
+
+### Security-Affecting Issues
+- Input that reaches dangerous operations unsanitized
+- Path traversal or injection vectors
+- Secrets or credentials exposed in code or logs
+- Missing authentication or authorization checks
+
+### Contract Violations
+- Method signatures that don't match their callers
+- API responses that deviate from documented contracts
+- Broken invariants or preconditions
+- Interface implementations that violate expectations
+
+## DO NOT Review
+
+The following are explicitly out of scope for this review phase:
+
+- **Style & Formatting** — indentation, whitespace, brace placement
+- **Performance Optimization** — algorithm efficiency, caching, query tuning
+- **Naming Conventions** — variable names, method names, class names
+- **Documentation Completeness** — missing docs, comment quality, README updates
+- **Refactoring Suggestions** — alternative designs, DRY improvements, simplification
+- **Alternative Approaches** — different libraries, patterns, or architectures

data/handbook/prompts/focus/phase/polish.md

@@ -0,0 +1,43 @@
+---
+name: polish
+description: Polish-focused review - simplification, clarity, and readability suggestions
+last-updated: '2026-02-16'
+---
+
+# Polish Focus
+
+> **ALL findings in this review are NON-BLOCKING suggestions.**
+> Nothing here should prevent merge. These are opportunities to improve clarity,
+> reduce complexity, or clean up after the functional work is complete.
+
+## Suggestions for Improvement
+
+### Simplification Opportunities
+- Code that could be expressed more concisely without losing clarity
+- Overly defensive checks that duplicate validations done elsewhere
+- Abstractions that add indirection without adding value
+- Conditional chains that could be simplified with guard clauses or early returns
+
+### Naming Clarity
+- Variables, methods, or classes whose names don't convey their purpose
+- Abbreviations that reduce readability
+- Boolean methods missing `?` suffix (Ruby convention)
+- Names that are technically accurate but misleading in context
+
+### Dead Code & Duplication
+- Unreachable code, unused variables, or commented-out blocks
+- Duplicated logic that could be extracted into a shared method
+- Imports or requires that are no longer needed
+- TODO/FIXME comments that refer to completed work
+
+### Documentation Gaps
+- Public methods or APIs missing documentation
+- Complex logic that would benefit from an explanatory comment
+- Missing or outdated inline examples
+- CHANGELOG entries that should accompany the change
+
+### Readability
+- Long methods that could be broken into well-named smaller methods
+- Deeply nested conditionals that obscure the main flow
+- Magic numbers or strings that should be named constants
+- Inconsistent ordering of method definitions (public before private)

data/handbook/prompts/focus/phase/quality.md

@@ -0,0 +1,42 @@
+---
+name: quality
+description: Quality-focused review - structure, performance, architecture, and standards
+last-updated: '2026-02-16'
+---
+
+# Quality Focus
+
+## What to Review
+
+### Performance Issues
+- Unnecessary allocations, repeated computation, or redundant I/O
+- N+1 queries, missing indexes, unoptimized database access
+- Missing caching where repeated lookups occur
+- Resource leaks (file handles, connections, memory)
+
+### Architecture Compliance
+- ATOM layer violations (atoms with side effects, organisms bypassing molecules)
+- Circular dependencies between modules or layers
+- Components exceeding their single responsibility
+- Improper coupling between unrelated subsystems
+
+### Standards Adherence
+- Project coding conventions not followed
+- Inconsistent patterns compared to surrounding code
+- Configuration cascade (ADR-022) not used correctly
+- CLI framework patterns (ADR-023) not followed
+
+### Test Coverage Gaps
+- New code paths without corresponding tests
+- Edge cases exercised in code but not in tests
+- Test assertions that don't verify meaningful behavior
+- Missing integration tests for cross-component interactions
+
+## DO NOT Review
+
+The following are explicitly out of scope for this review phase:
+
+- **Cosmetic Improvements** — whitespace, formatting, comment rewording
+- **Alternative Implementations** — different algorithms or libraries that would also work
+- **Polish & Simplification** — renaming for clarity, dead code removal, readability tweaks
+- **Documentation Style** — prose quality, markdown formatting, doc organization

data/handbook/prompts/focus/quality/performance.md

@@ -0,0 +1,48 @@
+---
+name: performance
+description: Performance optimization review focus
+last-updated: '2026-01-08'
+---
+
+# Performance Focus
+
+## Performance Optimization Review
+
+### Algorithm Efficiency
+- Time complexity analysis
+- Space complexity considerations
+- Optimal data structure selection
+- Algorithm choice justification
+
+### Database Performance
+- Query optimization
+- Index usage
+- N+1 query prevention
+- Connection pooling
+- Transaction scope
+
+### Caching Strategy
+- Cache invalidation logic
+- Cache key design
+- TTL appropriateness
+- Cache warming strategies
+
+### Resource Management
+- Memory usage patterns
+- Connection management
+- File handle cleanup
+- Thread safety
+
+### Frontend Performance
+- Bundle size optimization
+- Lazy loading implementation
+- Image optimization
+- Critical rendering path
+- Web Worker usage
+
+### Scalability Considerations
+- Horizontal scaling readiness
+- Stateless design
+- Queue and async processing
+- Rate limiting implementation
+- Load balancing compatibility

data/handbook/prompts/focus/quality/security.md

@@ -0,0 +1,47 @@
+---
+name: security
+description: Security vulnerability review focus
+last-updated: '2026-01-08'
+---
+
+# Security Focus
+
+## Enhanced Security Review
+
+### Input Validation
+- All user inputs validated and sanitized
+- Proper parameter filtering
+- File upload restrictions
+- Size and type validations
+
+### Authentication & Authorization
+- Secure session management
+- Proper password handling
+- Role-based access control
+- Token security (JWT, OAuth)
+
+### Data Protection
+- Encryption at rest and in transit
+- PII handling compliance
+- Secure credential storage
+- API key management
+
+### Common Vulnerabilities
+- SQL Injection prevention
+- XSS (Cross-Site Scripting) protection
+- CSRF (Cross-Site Request Forgery) tokens
+- Directory traversal prevention
+- Command injection protection
+- XXE (XML External Entity) prevention
+
+### Security Headers
+- Content Security Policy
+- X-Frame-Options
+- X-Content-Type-Options
+- Strict-Transport-Security
+
+### Dependency Security
+- Known vulnerability scanning
+- License compliance
+- Supply chain security
+- Outdated package detection

data/handbook/prompts/focus/scope/docs.md

@@ -0,0 +1,38 @@
+---
+name: docs
+description: Documentation review scope focus
+last-updated: '2026-01-08'
+---
+
+# Documentation Scope Focus
+
+## FOCUS COMBINATION: Documentation
+
+When reviewing documentation, expand your analysis with:
+
+### Documentation Quality Section
+Add after "API & Interface Review":
+- README completeness
+- API documentation coverage
+- Code comment quality
+- Example code accuracy
+- Setup instructions clarity
+- Troubleshooting guides
+
+### Documentation File Analysis
+Include in "Detailed File-by-File Feedback":
+- Markdown formatting issues
+- Broken links and references
+- Outdated information
+- Missing sections
+- Unclear explanations
+- Grammar and spelling
+
+### Documentation Gaps
+Add to "Prioritised Action Items":
+- Undocumented features
+- Missing API endpoints
+- Unclear configuration options
+- Absent migration guides
+- Missing architecture decisions
+- Incomplete changelogs

data/handbook/prompts/focus/scope/spec.md

@@ -0,0 +1,58 @@
+---
+name: spec
+description: Specification and proposal review scope focus
+last-updated: '2026-01-08'
+---
+
+# Specification Review Focus
+
+## FOCUS COMBINATION: Specification
+
+When reviewing specifications, proposals, or task definitions, analyze:
+
+### Goal Clarity
+
+- Single, well-defined objective stated clearly
+- No ambiguous terms ("appropriate", "etc.", "and/or", "as needed")
+- Purpose is immediately understandable
+- Success criteria explicitly defined
+- Scope boundaries are clear (what's in vs out)
+
+### Usage Expectations
+
+- Target audience/user clearly identified
+- Usage scenarios or user stories provided
+- Expected inputs and outputs defined
+- Integration points with existing systems described
+- Constraints and limitations stated
+
+### Test Strategy
+
+- Acceptance criteria are testable and verifiable
+- Test scenarios or examples provided
+- Edge cases and error conditions considered
+- Performance expectations quantified where applicable
+- Validation approach defined
+
+### Completeness Check
+
+- All required sections present
+- Dependencies identified and documented
+- Assumptions explicitly stated
+- Risks or unknowns acknowledged
+- No undefined references or placeholders
+
+### Implementation Feasibility
+
+- Requirements are technically achievable
+- Effort estimates are realistic
+- Required resources/dependencies available
+- No contradictory requirements
+- Constraints are reasonable and achievable
+
+### Consistency & Traceability
+
+- Terminology used consistently throughout
+- No contradicting statements
+- Requirements traceable to goals
+- Changes from previous versions noted (if applicable)

data/handbook/prompts/focus/scope/tests.md

@@ -0,0 +1,36 @@
+---
+name: tests
+description: Test quality and coverage review scope focus
+last-updated: '2026-01-08'
+---
+
+# Test Scope Focus
+
+## FOCUS COMBINATION: Tests
+
+When reviewing test files, expand your analysis with:
+
+### Test Quality & Coverage (Expanded)
+- Detailed test framework analysis (RSpec, Jest, Vitest, etc.)
+- Coverage metrics and gaps
+- Test organization and naming
+- Assertion quality and specificity
+- Mock/stub appropriateness
+- Edge case coverage
+- Error condition testing
+- Integration test requirements
+
+### Test Architecture Alignment
+- Test structure mirrors code structure
+- Proper test isolation
+- Shared examples and helpers usage
+- Test data management
+- Fixture and factory patterns
+
+### Test File Analysis
+Include test files in "Detailed File-by-File Feedback" with focus on:
+- Test completeness
+- Test clarity and documentation
+- Test performance
+- Flaky test identification
+- Test maintainability

data/handbook/prompts/format/compact.md

@@ -0,0 +1,12 @@
+# Compact Review Format
+
+## Minimalist Output Structure
+
+Focus only on:
+1. **Critical Issues** - Must fix before merge
+2. **High Priority** - Should fix before merge
+3. **Approval Status** - Single line recommendation
+
+Use bullet points and keep descriptions under 50 words each.
+No detailed explanations unless critical for understanding.
+Omit sections with no findings.

data/handbook/prompts/format/detailed.md

@@ -0,0 +1,39 @@
+# Detailed Review Format
+
+## Enhanced Output Structure
+
+### Deep Diff Analysis
+For each significant change:
+- **Intent**: What the change aims to achieve
+- **Impact**: Effects on the codebase
+- **Alternatives**: Other approaches considered
+
+### Code Quality Assessment
+- **Complexity metrics**: Cyclomatic complexity, cognitive load
+- **Maintainability index**: Based on code patterns
+- **Test coverage delta**: Change in coverage percentage
+
+### Architectural Analysis
+- **Pattern compliance**: Adherence to design patterns
+- **Dependency changes**: New or modified dependencies
+- **Component boundaries**: Interface changes
+
+### Documentation Impact Assessment
+- **Required updates**: What documentation needs updating
+- **API changes**: Breaking or non-breaking changes
+- **Migration notes**: For breaking changes
+
+### Quality Assurance Requirements
+- **Test scenarios**: Additional test cases needed
+- **Integration points**: Areas requiring integration testing
+- **Performance benchmarks**: Metrics to monitor
+
+### Security Review
+- **Attack vectors**: Potential security issues
+- **Data flow**: How sensitive data is handled
+- **Compliance**: Regulatory requirements
+
+### Refactoring Opportunities
+- **Technical debt**: Areas that could be improved
+- **Code smells**: Patterns that suggest refactoring
+- **Future-proofing**: Preparing for upcoming changes

data/handbook/prompts/format/standard.md

@@ -0,0 +1,16 @@
+# Standard Review Format
+
+## Output Formatting Rules
+
+• Use ✅ / ⚠️ / ❌ icons or colour words (🔴, 🟡, 🟢) for quick scanning.
+• In "Detailed File-by-File" include: **Issue – Severity – Location – Suggestion – (optionally) code snippet**.
+• In "Prioritised Action Items" group by severity:
+  🔴 Critical (blocking) / 🟡 High / 🟢 Medium / 🔵 Nice-to-have.
+• In "Approval Recommendation" present tick-box list:
+
+    [ ] ✅ Approve as-is
+    [ ] ✅ Approve with minor changes
+    [ ] ⚠️ Request changes (non-blocking)
+    [ ] ❌ Request changes (blocking)
+
+Pick ONE status and briefly justify.

data/handbook/prompts/guidelines/icons.md

@@ -0,0 +1,19 @@
+# Icon Usage Guidelines
+
+## Visual Indicators
+
+### Status Icons
+- ✅ **Success/Good**: Working correctly, best practice followed
+- ⚠️ **Warning**: Potential issue, needs attention
+- ❌ **Error/Blocking**: Must fix, prevents merge
+- 💡 **Suggestion**: Improvement opportunity
+- ❓ **Question**: Needs clarification
+- 📝 **Note**: Important information
+- 🎯 **Focus**: Key area for review
+
+### Severity Colors
+- 🔴 **Critical**: Blocking issues requiring immediate fix
+- 🟡 **High**: Important issues that should be addressed
+- 🟢 **Medium**: Improvements that would enhance quality
+- 🔵 **Low**: Nice-to-have enhancements
+- ⚪ **Info**: Neutral information or context

data/handbook/prompts/guidelines/tone.md

@@ -0,0 +1,21 @@
+# Review Tone Guidelines
+
+## Communication Style
+
+### Professional Tone
+- Concise and direct feedback
+- Focus on code, not the coder
+- Use "we" instead of "you" when suggesting improvements
+- Acknowledge good practices before critiquing
+
+### Constructive Feedback
+- Start with positives when possible
+- Frame issues as opportunities for improvement
+- Provide specific examples and alternatives
+- Explain the reasoning behind suggestions
+
+### Educational Approach
+- Share knowledge without condescension
+- Link to relevant documentation or resources
+- Explain best practices and patterns
+- Help the author learn and grow