From 666ba557aa73203adc4a1839428c09f70b56d27e Mon Sep 17 00:00:00 2001 From: Ian Rogers Date: Tue, 19 May 2026 19:33:45 -0700 Subject: [PATCH] kernel: add patch size analysis and detailed decomposition reporting Implement a systematic patch size analysis and decomposition protocol for kernel reviews. This change adds a classification system for patch sizes (XS to XL) based on line delta and introduces a logical decomposition workflow for patches that are too large or conceptually diverse. Key features: - New kernel/patch-size.md defines size categories and decomposition logic (e.g., the 80% rule and conceptual integrity checks). - Integrated TASK 0.5 into review-core.md to trigger analysis early in the review process. - Reinforced reporting requirements using MANDATORY and CRITICAL directives to ensure agents provide detailed blueprints (commit messages and code changes) for suggested splits. - Updated inline-template.md with a dedicated section and sample for patch decomposition recommendations. - Utilized TodoWrite and restricted context clearing to ensure decomposition data persists through the final report generation. Signed-off-by: Ian Rogers --- kernel/inline-template.md | 17 ++++++++++++++++ kernel/patch-size.md | 43 +++++++++++++++++++++++++++++++++++++++ kernel/review-core.md | 10 ++++++++- 3 files changed, 69 insertions(+), 1 deletion(-) create mode 100644 kernel/patch-size.md diff --git a/kernel/inline-template.md b/kernel/inline-template.md index 181dde6..508fb57 100644 --- a/kernel/inline-template.md +++ b/kernel/inline-template.md @@ -251,6 +251,9 @@ Create a TodoWrite for these items, all of which your report should include: - [ ] Author: line from the commit - [ ] One line subject from the commit - [ ] A brief (max 3 sentence) summary of the commit. +- [ ] **Patch Decomposition Recommendation**: If the patch was found to be too large or conceptually complex (based on the Patch Size Analysis), include the detailed breakdown recommendation here. + - [ ] Use factual, plain text formatting. + - [ ] Include the suggested patch series, proposed commit messages, and summaries of code changes for each. - [ ] Any Link: tags from the commit header - [ ] A unified diff of the commit, quoted as though it's in an email reply. - [ ] The diff must not be generated from existing context. @@ -288,6 +291,19 @@ mm, swap: only scan one cluster in fragment list +This patch is doing too many things. Please split it into a 2-patch series: + +Patch 1: mm, swap: isolate fragment cluster scanning +Commit message: +mm, swap: isolate fragment cluster scanning logic into a separate block +to prepare for optimization. +Code changes: Move the while loop into an if (ci) block. + +Patch 2: mm, swap: scan only one cluster in fragment list +Commit message: +mm, swap: only scan one cluster in fragment list to reduce latency. +Code changes: Remove the frags loop and scan only one cluster. + > diff --git a/mm/swapfile.c b/mm/swapfile.c > index b4f3cc7125804..1f1110e37f68b 100644 > --- a/mm/swapfile.c @@ -349,6 +365,7 @@ updates are getting lost. > } > } > +[ ... ] ``` Sample commit message issue: diff --git a/kernel/patch-size.md b/kernel/patch-size.md new file mode 100644 index 0000000..2e1c15a --- /dev/null +++ b/kernel/patch-size.md @@ -0,0 +1,43 @@ +# Patch Size Analysis + +Analyze the size and structure of the patch to ensure it is appropriately sized and conceptually atomic. + +## Patch Size Classification +Calculate the total number of lines changed (sum of added and removed lines) in the `git diff` of the patch. +- **XS**: < 10 lines +- **S**: < 50 lines +- **M**: < 250 lines +- **L**: < 1000 lines +- **XL**: >= 1000 lines + +For **XS** and **S** patches, the size is always considered appropriate. + +## Structural Analysis +For **M**, **L**, and **XL** patches, perform the following analysis: + +1. **Conceptual Integrity**: + Analyze the patch to determine if all changes are conceptually related to a single goal. + - Are there multiple unrelated bug fixes? + - Is there a mix of refactoring and new functionality? + - Are there changes to multiple distinct subsystems that could be separated? + +2. **Decomposition Strategy**: + If the patch contains conceptually distinct items, evaluate if it can be broken down into a series of smaller, atomic patches. + - A decomposition is only valid if each resulting patch in the series would independently build and pass tests (assuming standard kernel CI). + - Base functionality should be introduced first, followed by patches that build upon it. + - Avoid introducing significant "glue" code or temporary scaffolding just to keep builds/tests running. + +3. **80% Rule**: + A patch is only considered "breakable" if it can be decomposed such that the largest resulting patch has a line delta that is less than **80%** of the original patch's total line delta. + - If no such decomposition is possible while maintaining build/test integrity, report that the patch is **appropriately sized**. + +## Reporting +If a decomposition is recommended, provide: +1. **Broken-down series description**: A clear list of suggested patches. +2. **Commit Messages**: Proposed commit messages for each new patch. +3. **Code Changes**: A summary or snippet of which parts of the original code changes belong to which new patch. + +> [!IMPORTANT] +> When decomposition is recommended, the commit messages and code change summaries are MANDATORY. Do not just state that the patch should be broken up; you must provide the specific blueprint for how to do it. + +If no decomposition is recommended (or possible under the 80% rule), explicitly state that the patch is appropriately sized. diff --git a/kernel/review-core.md b/kernel/review-core.md index b8e280f..8d6f435 100644 --- a/kernel/review-core.md +++ b/kernel/review-core.md @@ -78,6 +78,12 @@ IMMEDIATELY. - Unless you're running out of context space, try to load all required context once and only once 2. You may need to load additional context in order to properly analyze the research patterns. +### TASK 0.5: Patch Size Analysis +1. Load `{{KERNEL_REVIEW_PROMPTS_DIR}}/patch-size.md` +2. Follow the Patch Size Analysis protocol to categorize the patch size and evaluate its conceptual integrity. +3. Output the patch size category (XS, S, M, L, XL) and your determination of whether the patch is appropriately sized or should be broken apart. +4. **MANDATORY**: If decomposition is recommended, you MUST add the detailed breakdown (series description, commit messages, code change summaries) to your **TodoWrite** to ensure it is preserved for the final report. + ## RESEARCH TASKS ### TASK 1: Context Gathering [] @@ -131,6 +137,7 @@ This deep dive analysis will take a long time, don't skip steps. - resource management: allocations, frees - resource management: object initialization - locking +- **Patch Decomposition**: If TASK 0.5 recommended decomposition, add a category **STRUCTURAL-REVIEW** to TodoWrite with the full detailed breakdown (commit messages, code changes). - Add each category and the modified, new, or deleted functions into TodoWrite - These categories will be referenced by the pattern prompts. Call them CHANGE-1, CHANGE-2, etc. The prompts will call them CHANGE CATEGORIES @@ -263,9 +270,10 @@ as defined in inline-template.md. If you fail to follow those instructions, the review is completely useless. **If regressions found**: -0. Clear any context not related to the regressions themselves +0. DO NOT clear context related to the patch decomposition recommendation. 1. Load `inline-template.md` - you must use inline-template.md for all analysis feedback + - **MANDATORY**: Include the Patch Decomposition Recommendation from TASK 0.5 in the report if decomposition was recommended. 2. Create `review-inline.txt` in current directory, never use the prompt directory 3. Follow the instructions in the template carefully - NEVER WRITE `REGRESSION:` INTO ./review-inline.txt THIS