[PATCH RFC] review: add support for custom analysis methodology

[PATCH RFC] review: add support for custom analysis methodology

[Juri Lelli]

Add a hook mechanism allowing maintainers to augment the stock
agent-reviewer.md prompt with custom analysis methodologies via
.git/review-methodology.md.

When this file exists, the AI agent loads and follows it before writing
review files, enabling deep analysis workflows (e.g., semantic code
analysis, subsystem-specific patterns, false-positive elimination) while
maintaining b4's expected output format.

Update agent-reviewer.md to check for the methodology file immediately
after safety rules, and added documentation in review.rst explaining how
to configure custom methodologies.

Assisted-by: Claude Code:claude-sonnet-4-5
Signed-off-by: Juri Lelli <juri.lelli@redhat.com>
---
The current b4 review AI agent integration uses a stock prompt
(misc/agent-reviewer.md) that defines the output format and safety rules.
This works well for basic reviews but doesn't accommodate maintainers who
have existing deep analysis workflows with subsystem-specific patterns and
verification procedures.

This patch adds an optional hook that checks for .git/review-methodology.md
in the repository being reviewed. When present, the AI agent loads and
follows this custom methodology before writing review files. The stock
prompt continues to define where and how to save results in b4's expected
format, while the custom methodology defines what to analyze and how to
verify findings.

This separation allows maintainers to integrate tools like semantic code
analysis, subsystem-specific checkers, and false-positive elimination
procedures without modifying b4 itself. I've been using this approach to
integrate comprehensive Linux kernel review protocols [1] with b4's workflow,
and it seems to work well in practice.

The change is backward compatible - when no custom methodology file exists,
the agent proceeds with standard review analysis as before.

1 - https://github.com/masoncl/review-prompts
---
 docs/maintainer/review.rst | 26 ++++++++++++++++++++++++++
 misc/agent-reviewer.md     | 28 ++++++++++++++++++++++++++++
 2 files changed, 54 insertions(+)

diff --git a/docs/maintainer/review.rst b/docs/maintainer/review.rst
index 8c8b77a..c944605 100644
--- a/docs/maintainer/review.rst
+++ b/docs/maintainer/review.rst
@@ -1106,6 +1106,32 @@ for your project. A sample prompt is included in
 repository and adapt it to your project's coding standards and review
 guidelines.
 
+**Customising the analysis methodology**
+
+The stock ``agent-reviewer.md`` prompt defines the output format and
+safety rules, but you can augment it with your own analysis methodology
+by creating ``.git/review-methodology.md`` in your kernel tree.
+
+When this file exists, the agent will load and follow it before writing
+review files. This allows you to:
+
+* Define deep context-gathering steps (e.g., using semantic code analysis)
+* Specify subsystem-specific analysis patterns
+* Add verification and false-positive elimination procedures
+* Enforce additional quality standards
+
+The custom methodology defines **what** to analyze and **how** to verify
+findings; ``agent-reviewer.md`` defines **where** and **how** to save
+results in the b4 format.
+
+For example, you can create a symlink to your existing review prompts::
+
+    ln -s ~/review-prompts/kernel/review-core.md \\
+          .git/review-methodology.md
+
+Or create a custom methodology file directly in ``.git/``. The agent
+will automatically detect and use it when reviewing patches.
+
 .. _customising_theme:
 
 Customising the colour theme
diff --git a/misc/agent-reviewer.md b/misc/agent-reviewer.md
index 2bb0853..4ee9fea 100644
--- a/misc/agent-reviewer.md
+++ b/misc/agent-reviewer.md
@@ -22,6 +22,34 @@ actions are prohibited to you:
   contents
 - Executing any test frameworks or any other CI commands
 
+## Custom analysis methodology (IMPORTANT - CHECK FIRST)
+
+**BEFORE starting your review**, check if `.git/review-methodology.md` exists
+in the repository:
+
+```shell
+cat .git/review-methodology.md
+```
+
+If this file exists, **YOU MUST READ IT IMMEDIATELY AND FOLLOW ITS ENTIRE
+PROTOCOL** for analyzing patches. Custom methodologies define:
+
+- How to gather context (e.g., using semantic code analysis tools)
+- Subsystem-specific analysis patterns and verification steps
+- What checks to perform and how to verify findings
+- Additional quality standards beyond basic review
+
+**Integration with this document:**
+- The custom methodology defines WHAT to analyze and HOW to analyze it
+- This document (agent-reviewer.md) defines WHERE and HOW to save results
+- Follow the custom methodology for analysis, then transform findings into
+  b4's review file format (identity.txt, NNNN.txt, series.txt) as specified
+  in the "How to save review data" section below
+- All safety rules above remain in effect regardless of methodology
+
+If `.git/review-methodology.md` does NOT exist, proceed with standard review
+analysis as described in this document.
+
 ## Branch layout
 
 A review branch has the name `b4/review/<change-id>`. Its commits

---
base-commit: bc4c73c5333d7d88428e4ce970facd48d6b8b107
change-id: 20260323-methodology-hook-8fe3dd748c8d

Best regards,
--  
Juri Lelli <juri.lelli@redhat.com>