feat(review): learn from feedback explanations

Author: haasonsaas

TODO.md

@@ -29,7 +29,7 @@ This roadmap is derived from deep research into Greptile's public docs, blog, MC
 5. [ ] Weight reinforcement by reviewer role or trust level when GitHub identity is available.
 6. [x] Add rule-level reinforcement decay so old team preferences do not dominate forever.
 7. [x] Add path-scoped reinforcement buckets so teams can prefer different standards in `tests/`, `scripts/`, and production code.
-8. [ ] Persist explanation text from follow-up feedback replies and mine it into reusable review guidance.
+8. [x] Persist explanation text from follow-up feedback replies and mine it into reusable review guidance.
 9. [x] Learn "preferred phrasing" for accepted comments so comment tone and specificity improve over time.
 10. [x] Backfill existing stored reviews into the new outcome-aware feedback store for cold-start reduction.
 

src/review/feedback.rs

@@ -28,7 +28,10 @@ pub use record::{
 #[allow(unused_imports)]
 pub use semantic::{record_semantic_feedback_example, record_semantic_feedback_examples};
 #[allow(unused_imports)]
-pub use store::{DecayedFeedbackStats, FeedbackPatternStats, FeedbackStore, FeedbackTypeStats};
+pub use store::{
+    DecayedFeedbackStats, FeedbackExplanation, FeedbackPatternStats, FeedbackStore,
+    FeedbackTypeStats,
+};
 
 #[cfg(test)]
 mod tests {
@@ -49,6 +52,7 @@ mod tests {
         assert!(store.by_category_file_pattern.is_empty());
         assert!(store.by_rule.is_empty());
         assert!(store.by_rule_file_pattern.is_empty());
+        assert!(store.explanations_by_comment.is_empty());
     }
 
     #[test]
@@ -99,6 +103,19 @@ mod tests {
                 not_addressed: 5,
             },
         );
+        store.explanations_by_comment.insert(
+            "review-1::comment-1".to_string(),
+            FeedbackExplanation {
+                review_id: "review-1".to_string(),
+                comment_id: "comment-1".to_string(),
+                action: "accept".to_string(),
+                category: "Security".to_string(),
+                rule_id: Some("sec.auth.boundary".to_string()),
+                file_patterns: vec!["src/**".to_string()],
+                text: "Tenant boundaries must stay explicit.".to_string(),
+                updated_at: "2026-03-15T00:00:00Z".to_string(),
+            },
+        );
 
         let json = serde_json::to_string(&store).unwrap();
         let deserialized: FeedbackStore = serde_json::from_str(&json).unwrap();
@@ -116,6 +133,7 @@ mod tests {
             deserialized.by_rule["style.rule"].decayed_total_at(123),
             Some(2.0)
         );
+        assert_eq!(deserialized.explanations_by_comment.len(), 1);
     }
 
     #[test]
@@ -357,4 +375,56 @@ mod tests {
             "Should mention file pattern: {context}"
         );
     }
+
+    #[test]
+    fn generate_feedback_context_includes_feedback_explanation_guidance() {
+        let mut store = FeedbackStore::default();
+        let comment = crate::core::comment::Comment {
+            id: "comment-1".to_string(),
+            file_path: Path::new("src/auth.rs").to_path_buf(),
+            line_number: 10,
+            content: "Guard the tenant boundary before the query".to_string(),
+            rule_id: Some("sec.auth.boundary".to_string()),
+            severity: crate::core::comment::Severity::Error,
+            category: crate::core::comment::Category::Security,
+            suggestion: None,
+            confidence: 0.9,
+            code_suggestion: None,
+            tags: Vec::new(),
+            fix_effort: crate::core::comment::FixEffort::Medium,
+            feedback: Some("accept".to_string()),
+            status: crate::core::comment::CommentStatus::Open,
+            resolved_at: None,
+        };
+
+        assert!(store.record_feedback_explanation(
+            "review-1",
+            &comment,
+            &["src/**"],
+            "accept",
+            "This keeps tenant isolation explicit before any data access.",
+            "2026-03-15T00:00:00Z",
+        ));
+        assert!(store.record_feedback_explanation(
+            "review-2",
+            &crate::core::comment::Comment {
+                id: "comment-2".to_string(),
+                ..comment.clone()
+            },
+            &["src/**"],
+            "accept",
+            "Tenant isolation must stay explicit to avoid cross-account reads.",
+            "2026-03-15T00:01:00Z",
+        ));
+
+        let context = generate_feedback_context(&store);
+        assert!(
+            context.contains("sec.auth.boundary"),
+            "Should mention the rule: {context}"
+        );
+        assert!(
+            context.contains("tenant isolation"),
+            "Should surface explanation-derived guidance: {context}"
+        );
+    }
 }

src/review/feedback/context.rs

@@ -1,5 +1,15 @@
 use super::store::FeedbackStore;
 
+const MIN_EXPLANATION_OBSERVATIONS: usize = 2;
+const MAX_EXPLANATION_GUIDANCE_ITEMS: usize = 4;
+
+#[derive(Default)]
+struct ExplanationGuidanceBucket {
+    accepted: usize,
+    rejected: usize,
+    snippets: Vec<String>,
+}
+
 /// Generate feedback context to inject into the review prompt.
 ///
 /// Scans the feedback store for statistically significant patterns
@@ -39,6 +49,80 @@ pub fn generate_feedback_context(store: &FeedbackStore) -> String {
         }
     }
 
+    let mut explanation_buckets =
+        std::collections::HashMap::<String, ExplanationGuidanceBucket>::new();
+    for explanation in store.explanations_by_comment.values() {
+        let bucket_key = explanation
+            .rule_id
+            .as_deref()
+            .map(|rule_id| format!("rule::{rule_id}"))
+            .unwrap_or_else(|| format!("category::{}", explanation.category));
+        let bucket = explanation_buckets.entry(bucket_key).or_default();
+        if explanation.action == "accept" {
+            bucket.accepted += 1;
+        } else {
+            bucket.rejected += 1;
+        }
+
+        if let Some(snippet) = explanation_snippet(&explanation.text) {
+            let already_seen = bucket
+                .snippets
+                .iter()
+                .any(|existing| existing.eq_ignore_ascii_case(&snippet));
+            if !already_seen {
+                bucket.snippets.push(snippet);
+            }
+        }
+    }
+
+    let mut explanation_guidance = explanation_buckets
+        .into_iter()
+        .filter_map(|(bucket_key, bucket)| {
+            let total = bucket.accepted + bucket.rejected;
+            if total < MIN_EXPLANATION_OBSERVATIONS
+                || bucket.snippets.is_empty()
+                || bucket.accepted == bucket.rejected
+            {
+                return None;
+            }
+
+            let snippets = bucket
+                .snippets
+                .into_iter()
+                .take(2)
+                .collect::<Vec<_>>()
+                .join("; ");
+            if snippets.is_empty() {
+                return None;
+            }
+
+            let label = format_explanation_bucket_label(&bucket_key);
+            if bucket.accepted >= bucket.rejected {
+                Some((
+                    total,
+                    format!(
+                        "- Reviewers accepted similar {label} findings when they noted: {snippets}",
+                    ),
+                ))
+            } else {
+                Some((
+                    total,
+                    format!(
+                        "- Reviewers rejected similar {label} findings when they noted: {snippets} — avoid flagging them unless the same concern clearly applies",
+                    ),
+                ))
+            }
+        })
+        .collect::<Vec<_>>();
+    explanation_guidance
+        .sort_by(|left, right| right.0.cmp(&left.0).then_with(|| left.1.cmp(&right.1)));
+    patterns.extend(
+        explanation_guidance
+            .into_iter()
+            .take(MAX_EXPLANATION_GUIDANCE_ITEMS)
+            .map(|(_, guidance)| guidance),
+    );
+
     patterns.truncate(10);
 
     if patterns.is_empty() {
@@ -54,3 +138,33 @@ pub fn generate_feedback_context(store: &FeedbackStore) -> String {
     }
     context
 }
+
+fn explanation_snippet(text: &str) -> Option<String> {
+    let snippet = text
+        .replace("\r\n", "\n")
+        .split(['\n', '.', '!', '?'])
+        .map(str::trim)
+        .find(|segment| !segment.is_empty())?
+        .chars()
+        .take(140)
+        .collect::<String>();
+
+    if snippet.is_empty() {
+        None
+    } else {
+        Some(snippet)
+    }
+}
+
+fn format_explanation_bucket_label(bucket_key: &str) -> String {
+    if let Some(rule_id) = bucket_key.strip_prefix("rule::") {
+        format!("rule `{rule_id}`")
+    } else if let Some(category) = bucket_key.strip_prefix("category::") {
+        match category {
+            "BestPractice" => "best practice".to_string(),
+            _ => category.to_lowercase(),
+        }
+    } else {
+        "feedback".to_string()
+    }
+}