Merge pull request #75 from lufftw/review/pattern-tree-dp

review: Complete pattern + solutions audit (24/24 patterns)

Author: lufftw

docs/contracts/solution-contract.md

@@ -227,6 +227,8 @@ Constraints:
 
 Each solution class SHOULD be preceded by a block comment explaining the approach.
 
+**Keep it concise**: Block comments should have **3-4 bullet points maximum**. Focus on key algorithmic insights, not exhaustive explanations.
+
 **No blank line** between the comment block and the class definition:
 
 ```python
@@ -247,8 +249,9 @@ class SolutionSlidingWindow:   # ← No blank line
 # ============================================
 # Solution {N}: {Approach Name}
 # Time: O(?), Space: O(?)
-#   - {Key insight or implementation detail}
-#   - {Additional notes}
+#   - {Key insight 1}
+#   - {Key insight 2}
+#   - {Key insight 3 (optional)}
 # ============================================
 class ClassName:   # ← No blank line before class/function
 ```
@@ -257,9 +260,56 @@ class ClassName:   # ← No blank line before class/function
 |-----------|----------|-------------|
 | Solution number & name | ✅ | e.g., `Solution 1: Sliding Window` |
 | Time/Space complexity | ✅ | e.g., `Time: O(n), Space: O(n)` |
-| Bullet points | Recommended | Key insights, implementation details |
+| Bullet points (3-4 max) | ✅ | Key insights only, avoid verbose explanations |
 | **No blank line** | ✅ | Comment block directly followed by class/function |
 
+**What NOT to include in block comments:**
+
+- ❌ Lengthy "Algorithm Insight" or "State Definition" sections
+- ❌ Detailed step-by-step pseudocode
+- ❌ Redundant restating of code logic
+- ❌ More than 4 bullet points
+
+#### Internal Function Comments
+
+Internal comments **within methods** are acceptable and encouraged for documenting:
+
+- Key state transitions
+- Non-obvious logic or edge case handling
+- Invariant maintenance
+
+```python
+class Solution:
+    def maxPathSum(self, root: Optional[TreeNode]) -> int:
+        self.global_max = float('-inf')
+
+        def max_contribution(node: Optional[TreeNode]) -> int:
+            if not node:
+                return 0
+
+            # Prune negative branches - they can only decrease path sum
+            left_gain = max(0, max_contribution(node.left))
+            right_gain = max(0, max_contribution(node.right))
+
+            # Path through this node as apex: left → node → right
+            path_through_here = node.val + left_gain + right_gain
+            self.global_max = max(self.global_max, path_through_here)
+
+            # Return single-branch max to parent (can't fork upward)
+            return node.val + max(left_gain, right_gain)
+
+        max_contribution(root)
+        return self.global_max
+```
+
+**Internal comment guidelines:**
+
+| ✅ Good | ❌ Bad |
+|---------|--------|
+| Explains WHY (non-obvious reasoning) | Restates WHAT the code does |
+| Documents invariant or constraint | Comments obvious operations |
+| Marks key algorithmic transitions | Excessive line-by-line comments |
+
 ---
 
 ## SOLUTIONS Metadata

docs/guides/pattern-review.md

@@ -16,9 +16,10 @@ This guide defines the systematic review process for pattern documentation in th
 - [3. Review Scope](#3-review-scope)
 - [4. Review Criteria](#4-review-criteria)
 - [5. Review Process](#5-review-process)
-- [6. Recording Reviews](#6-recording-reviews)
-- [7. Branch and Commit Protocol](#7-branch-and-commit-protocol)
-- [8. Quality Tiers](#8-quality-tiers)
+- [6. Combined Pattern + Solutions Review Workflow](#6-combined-pattern--solutions-review-workflow)
+- [7. Recording Reviews](#7-recording-reviews)
+- [8. Branch and Commit Protocol](#8-branch-and-commit-protocol)
+- [9. Quality Tiers](#9-quality-tiers)
 
 ---
 
@@ -201,17 +202,72 @@ For each review checkpoint:
 
 ---
 
-## 6. Recording Reviews
+## 6. Combined Pattern + Solutions Review Workflow
 
-### 6.1 Review Log Location
+### 6.1 Context-Driven Solutions Audit
+
+When reviewing pattern templates, **simultaneously audit the corresponding solutions**. Reading `templates.md` first provides the algorithmic context needed to improve solution quality.
+
+**Workflow:**
+
+```
+1. Read docs/patterns/{pattern}/templates.md completely
+2. For each problem referenced in templates.md:
+   a. Read the corresponding solutions/{problem}.py
+   b. Apply dual-perspective quality criteria (see 6.2)
+   c. Improve comments and naming with pattern context
+3. Record both template and solution findings in pattern-review-log.md
+```
+
+**Why Context Matters:**
+
+| Without Context | With Context |
+|-----------------|--------------|
+| Generic variable names like `l`, `r`, `res` | Semantic names like `left_boundary`, `right_exclusive`, `max_contribution` |
+| Vague comments "loop through array" | Precise comments "extend window until constraint violated" |
+| Missing invariant documentation | Explicit invariant: "dp[i] represents optimal cost to reach position i" |
+
+### 6.2 Dual-Perspective Quality Criteria
+
+Solutions should satisfy both **pedagogical clarity** (teaching effectiveness) and **engineering quality** (production maintainability).
+
+| Aspect | Pedagogical (Professor) | Engineering (Tech Lead) |
+|--------|------------------------|-------------------------|
+| **Comments** | Explain WHY the approach works | Keep concise, avoid redundancy |
+| **Naming** | Self-documenting algorithm intent | Consistent, refactorable |
+| **Structure** | Progressive logic flow | Minimal coupling, clean interfaces |
+| **Complexity** | Explicit analysis with reasoning | Practical performance notes |
+
+**Quality Fusion Guidelines:**
+
+1. **Block comments**: Concise 3-4 bullet points (see Solution Contract)
+2. **Internal comments**: Document key transitions and non-obvious logic
+3. **Variable naming**: Semantic names reflecting algorithmic role
+4. **State documentation**: Explicit invariants where applicable
+
+### 6.3 Solutions Audit Checklist
+
+For each solution file touched during pattern review:
+
+- [ ] Block comment follows concise format (3-4 bullet points)
+- [ ] Variable names are semantic and consistent with pattern vocabulary
+- [ ] Key algorithmic transitions are documented inline
+- [ ] State/invariant is explicit where applicable
+- [ ] No redundant comments that merely restate the code
+
+---
+
+## 7. Recording Reviews
+
+### 7.1 Review Log Location
 
 All review findings must be recorded in:
 
 ```
 docs/reviews/pattern-review-log.md
 ```
 
-### 6.2 Log Entry Format
+### 7.2 Log Entry Format
 
 ```markdown
 ## [Pattern Name] Review - [Date]
@@ -253,24 +309,24 @@ docs/reviews/pattern-review-log.md
 - [ ] {Documentation update needed}
 ```
 
-### 6.3 What NOT to Record
+### 7.3 What NOT to Record
 
 - Changes made without issues (silent fixes)
 - Personal preferences overridden
 - Temporary debugging observations
 
 ---
 
-## 7. Branch and Commit Protocol
+## 8. Branch and Commit Protocol
 
-### 7.1 Branch Naming
+### 8.1 Branch Naming
 
 ```
 review/pattern-{pattern_name}
 review/pattern-quality-audit-{date}
 ```
 
-### 7.2 Commit Structure
+### 8.2 Commit Structure
 
 ```bash
 # Review log commit
@@ -292,7 +348,7 @@ Impact: {What this fixes}
 Refs: docs/reviews/pattern-review-log.md#{pattern}-{date}"
 ```
 
-### 7.3 PR Requirements
+### 8.3 PR Requirements
 
 Each review PR must include:
 
@@ -306,9 +362,9 @@ Each review PR must include:
 
 ---
 
-## 8. Quality Tiers
+## 9. Quality Tiers
 
-### 8.1 Tier Definitions
+### 9.1 Tier Definitions
 
 | Tier | Criteria | Examples |
 |------|----------|----------|
@@ -317,15 +373,15 @@ Each review PR must include:
 | **Tier 3 (Bronze)** | Major issues, needs improvement | Newly generated patterns |
 | **Tier 4 (Draft)** | Critical issues or incomplete | Work in progress |
 
-### 8.2 Promotion Criteria
+### 9.2 Promotion Criteria
 
 ```
 Tier 4 → Tier 3: All critical issues resolved
 Tier 3 → Tier 2: All major issues resolved
 Tier 2 → Tier 1: Peer-reviewed, community validated
 ```
 
-### 8.3 Current Pattern Status
+### 9.3 Current Pattern Status
 
 | Pattern | Current Tier | Last Review |
 |---------|--------------|-------------|