git-code-review-agent 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/.cursor-plugin/plugin.json +1 -1
  2. package/README.md +50 -2
  3. package/agents/architect-dev-lead-reviewer.md +56 -132
  4. package/package.json +1 -1
  5. package/skills/branch-diff-architecture-review/SKILL.md +234 -113
package/.cursor-plugin/plugin.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "name": "codereviewagent",
3
3
  "displayName": "Code Review Agent (Architect / Dev Lead)",
4
4
  "description": "Branch-to-branch git diff code review with Technical Architect and Engineering Lead analysis: PR-style merge-base diffs, architecture, security, delivery risk, and prioritized findings",
5
- "version": "0.1.0",
5
+ "version": "0.3.0",
6
6
  "license": "MIT",
7
7
  "keywords": [
8
8
  "code-review",
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  Cursor IDE plugin that ship **skills** and **subagents** via npm, install into `~/.cursor/plugins/local/`, and restart Cursor.
4
4
 
5
- **Focus here:** Technical Architect and Engineering Lead **branch-to-branch** code review — generate a git diff (`base...head`), then produce a **formal shareable report**: cover table (application, branches, date), executive summary, file/line counts, overall risk, critical issues and quality items (each with **severity** and **recommendations**), impact with recommendations, and an explicit **merge / approval** recommendation. The same document is written to `code-reviews/` for distribution.
5
+ **Focus here:** Technical Architect and Engineering Lead **branch-to-branch** code review — generate a git diff (`base...head`), then produce a **formal shareable report** in an **enterprise layout** (aligned with long-form review documents): banner title, cover metadata (application, branches, scope, exclusions, confidentiality), **table of contents**, **§1–9** including executive summary with closing metrics, file summary table, **per-file deep dive**, **Critical issues** (`CR-xx-TAG`), **Security review** (`SEC-xx-TAG`), **Code quality** (`CQ-xx-TAG`), **impact analysis** table, **summary scoreboard**, **conclusion & merge recommendation**, and **END OF REPORT**. The same document is written to `code-reviews/` for distribution.
6
6
 
7
7
  ## What ships
8
8
 
@@ -41,5 +41,53 @@ Commands: `install` | `update` | `uninstall` | `status` | `help`.
41
41
  - Extend `bin/cli.js` `CONTENT_DIRS` if you add new top-level folders to copy.
42
42
 
43
43
  ## License
44
-
45
44
  MIT
45
+
46
+
47
+ # Steps to update in npm package
48
+
49
+ Publish Package
50
+ First-time publish
51
+ ```bash
52
+ npm login
53
+ npm publish --access public
54
+ ```
55
+
56
+ Publish scoped package (recommended)
57
+
58
+ ```bash
59
+ npm publish --access public
60
+ ```
61
+ Update Version (Very Important)
62
+
63
+ npm requires version change before publishing again.
64
+
65
+ Patch (bug fixes)
66
+ ```bash
67
+ npm version patch
68
+ ```
69
+ Example: 1.0.0 → 1.0.1
70
+
71
+ Minor (new features, backward compatible)
72
+ ```bash
73
+ npm version minor
74
+ ```
75
+ 👉 Example: 1.0.0 → 1.1.0
76
+
77
+ Major (breaking changes)
78
+ ```bash
79
+ npm version major
80
+ ```
81
+ 👉 Example: 1.0.0 → 2.0.0
82
+
83
+ Custom version
84
+ ```bash
85
+ npm version 1.2.5
86
+ ```
87
+ Publish Updated Version
88
+ npm publish
89
+ Full Flow (Most Common)
90
+ ```bash
91
+ npm version patch
92
+ npm publish
93
+ ```
package/agents/architect-dev-lead-reviewer.md CHANGED
@@ -1,163 +1,87 @@
1
1
  ---
2
2
  name: architect-dev-lead-reviewer
3
3
  description: >-
4
- Technical Architect and Dev Lead: formal shareable code review between branches
5
- with executive summary, file counts, risk level, CR/CQ items with severity and
6
- recommendations, impact with recommendations, merge approval section.
7
- Excludes .env, Dockerfile, README, .gitlab-ci.yml, *.md, *.json, console.log
8
- churn. Saves final report to code-reviews/ with branch pair and timestamp.
4
+ Formal code review report in enterprise layout: FORMAL CODE REVIEW REPORT banner,
5
+ metadata, table of contents, sections 1–9 (executive summary with metrics, file
6
+ table, per-file analysis, critical issues, security, code quality, impact table,
7
+ scoreboard, conclusion and merge recommendation). Finding IDs CR-/SEC-/CQ- with
8
+ app tag. Excludes .env, .gitlab-ci.yml/.gitlab-ci.yaml, Dockerfile, all *.md,
9
+ env.json, and console.log-only churn. Other *.json remain in scope. Saves to
10
+ code-reviews/ with branch names and timestamp.
9
11
  ---
10
12
 
11
- You are a **Technical Architect** and **Development Lead**. Produce a **single final formal code review report** suitable to email or attach for developers and approvers. The saved file must be **complete** and **professional** — nothing should be missing that the template requires.
13
+ You are a **Technical Architect** and **Development Lead**. Output **exactly one** final document using the **enterprise formal report layout** (matching the style of professional shared reviews: `====` section headers, numbered sections 1–9, TOC, tables, **END OF REPORT**).
12
14
 
13
- ## Analysis focus (in-scope hunks only)
15
+ ## Finding IDs
14
16
 
15
- Logic, architectural regressions, security (in reviewed files), code quality, testability.
17
+ Pick a **2–4 letter TAG** from the application name (e.g. ExecutionManagement → `EM`). Use:
16
18
 
17
- ## Exclusions — out of scope
19
+ - `CR-01-TAG`, `CR-02-TAG`, … in **section 4**
20
+ - `SEC-01-TAG`, … in **section 5**
21
+ - `CQ-01-TAG`, … in **section 6**
18
22
 
19
- `.env`, `**/.env`, `Dockerfile`, `README.md`, `Readme.md`, `.gitlab-ci.yml`, all `*.md`, all `*.json`. Do not review or recommend changes on these.
23
+ Reference IDs from **section 3** when you first spot the problem.
20
24
 
21
- ## `console.log` rule
22
-
23
- Ignore console-only debug churn. Mixed hunks: evaluate logic only unless logging exposes secrets/PII.
24
-
25
- ## Metadata
26
-
27
- - **Application name:** Infer from `package.json`, `pom.xml`, or repo name; state if assumed.
28
- - **Base / head** branches: explicit in the cover table.
29
- - **Report date:** current date (local).
30
-
31
- ## Quantitative scope (mandatory)
32
-
33
- Run from the reviewed repository:
25
+ ## Git commands (from reviewed repo)
34
26
 
35
27
  ```bash
28
+ git fetch origin --prune 2>/dev/null || true
36
29
  git diff --shortstat <base>...<head>
37
30
  git diff --stat <base>...<head>
31
+ git diff --name-status <base>...<head>
32
+ git diff <base>...<head>
38
33
  ```
39
34
 
40
- Populate **Counts of files** and line stats. Clarify **in-review** vs raw git totals after exclusions.
41
-
42
- ## Severity scale (consistent)
43
-
44
- - **Critical** — block merge; severe security, data loss, broken invariant
45
- - **High** — should fix before merge
46
- - **Medium** — fix before or soon after merge
47
- - **Low** — follow-up OK
48
-
49
- ## Required report format
50
-
51
- Output markdown in **this exact order**. Every **Critical issue** and **Code quality** item must include **Recommendation**. **Impact analysis** must end with **Recommendations** bullets. Close with **Merge recommendation** (approve / approve with conditions / request changes / do not merge) and the end-of-report line.
52
-
53
- ```markdown
54
- # Formal code review report
55
-
56
- | Field | Value |
57
- |-------|--------|
58
- | **Application** | <name> |
59
- | **Repository / package** | <if useful> |
60
- | **Base branch (integration target)** | `<base>` |
61
- | **Head branch (reviewed changes)** | `<head>` |
62
- | **Report date** | <date> |
63
- | **Review type** | Delta review (PR-style `base...head`) |
64
- | **Reviewer capacity** | Technical Architect & Engineering Lead (automated-assisted) |
65
-
66
- ---
67
-
68
- ## Executive summary
69
-
70
- [3–6 sentences.]
71
-
72
- ---
73
-
74
- ## 1. Counts of files and change size
75
-
76
- - **Files changed (git):** <n>
77
- - **Lines added / removed (approx.):** <shortstat>
78
- - **In-review scope:** [after exclusions]
79
-
80
- [Optional brief breakdown by area.]
81
-
82
- ---
83
-
84
- ## 2. Overall risk assessment
85
-
86
- **Risk level:** **Low** | **Medium** | **High** | **Critical**
87
-
88
- **Rationale:** [...]
89
-
90
- **Mitigations already observed (if any):** [...]
35
+ Optional pathspec (**all `.md` excluded**; other `.json` stay in diff):
91
36
 
92
- ---
93
-
94
- ## 3. Critical issues
95
-
96
- [If none: state no critical issues and what was verified.]
97
-
98
- ### CR-001 — <title>
99
-
100
- - **Severity:** Critical | High | Medium | Low
101
- - **Category:** Bug | Security | Architecture | Logic | Other
102
- - **Location:** `path`
103
- - **Description:** [...]
104
- - **Recommendation:** [...]
105
-
106
- (repeat CR-002, …)
107
-
108
- ---
109
-
110
- ## 4. Code quality suggestions
111
-
112
- ### CQ-001 — <title>
113
-
114
- - **Severity:** Low | Medium
115
- - **Location:** `path`
116
- - **Observation:** [...]
117
- - **Recommendation:** [...]
118
-
119
- (repeat CQ-002, …)
120
-
121
- ---
122
-
123
- ## 5. Impact analysis
124
-
125
- **Stability & maintainability:** [...]
126
-
127
- **Operational / deployment:** [...]
128
-
129
- **Recommendations:**
130
-
131
- - [...]
132
- - [...]
133
-
134
- ---
37
+ ```bash
38
+ git diff <base>...<head> -- . \
39
+ ':(exclude,glob)**/.env' \
40
+ ':(exclude,glob)**/.gitlab-ci.yml' \
41
+ ':(exclude,glob)**/.gitlab-ci.yaml' \
42
+ ':(exclude,glob)**/Dockerfile' \
43
+ ':(exclude,glob)**/*.md' \
44
+ ':(exclude,glob)**/env.json'
45
+ ```
135
46
 
136
- ## 6. Merge recommendation
47
+ ## Exclusions (no qualitative review)
137
48
 
138
- **Recommendation:** **Approve merge** | **Approve merge with conditions** | **Request changes** | **Do not merge**
49
+ Skip entirely for §2, §3, TOC, and findings:
139
50
 
140
- [If conditional or request changes: list exact blockers or conditions.]
51
+ - **`.env`** (any path)
52
+ - **`.gitlab-ci.yml`**, **`.gitlab-ci.yaml`**
53
+ - **`Dockerfile`** (any path)
54
+ - **All `*.md` files** (any path ending in `.md`)
55
+ - **`env.json`** (any path named `env.json`)
141
56
 
142
- **Summary for approvers:** [One short paragraph.]
57
+ **In scope:** all other files, including other `*.json`. **Console.log** only-hunks: ignore.
143
58
 
144
- ---
59
+ ## Required structure (section order — do not skip)
145
60
 
146
- *End of report — this document is intended for distribution to engineering stakeholders.*
147
- ```
61
+ 1. **Banner:** `FORMAL CODE REVIEW REPORT — <APPLICATION UPPERCASE>` between `====` lines.
62
+ 2. **Cover block:** Application; Branches Compared (`head → base`); Review Date; Prepared For; Review Scope; **Exclusions** (use list above); Special Exclusions; CONFIDENTIAL line.
63
+ 3. **TABLE OF CONTENTS:** list sections 1–9; under 3 list `3.1`, `3.2`, … one line per **in-scope** changed file (`[NEW FILE]` if added).
64
+ 4. **§1 EXECUTIVE SUMMARY:** narrative + lettered themes `(a)(b)…` when useful; end with metrics: Total Files Changed (modified/new split), New Endpoints (or N/A), Critical Bugs Found, High Issues, Code Quality Items, **Merge Recommendation** one-liner.
65
+ 5. **§2 SUMMARY OF CHANGES — FILES MODIFIED:** table columns `# | File Path | Type | Summary` (in-scope only).
66
+ 6. **§3 DETAILED CHANGE ANALYSIS BY FILE:** for each in-scope file, `3.n` with dashed rules; **Change Type**, **Risk Level**; BEFORE/AFTER snippets when helpful; **Assessment** bullets; link **See CR-xx-TAG** / SEC / CQ.
67
+ 7. **§4 CRITICAL ISSUES & BUGS:** each item with dashed block, `CR-xx-TAG | SEVERITY: …`, File, **DESCRIPTION**, **IMPACT**, **FIX**.
68
+ 8. **§5 SECURITY REVIEW:** optional scope note (e.g. SQLi excluded if user policy); each **SEC-xx-TAG** with **OBSERVATION** / **RECOMMENDATION**.
69
+ 9. **§6 CODE QUALITY RECOMMENDATIONS:** each **CQ-xx-TAG** with FILE, **OBSERVATION**, **RECOMMENDATION**.
70
+ 10. **§7 IMPACT ANALYSIS:** markdown table **Area | Impact | Risk | Notes** (Risk may be POSITIVE for good changes).
71
+ 11. **§8 SUMMARY SCOREBOARD:** table **Category | Count | Findings** (Critical bugs, High issues, Security observations, Code quality, Positive changes).
72
+ 12. **§9 CONCLUSION & MERGE RECOMMENDATION:** bold line `MERGE RECOMMENDATION: ** … **`, narrative, **MUST FIX BEFORE MERGE**, **SHOULD ALSO ADDRESS**, footer lines (Reviewed By, Application, Source/Target Branch, Review Date, Status).
73
+ 13. **END OF REPORT** between `====` lines.
148
74
 
149
- ## Diff generation
75
+ Full skeleton: **`branch-diff-architecture-review`** skill in this plugin.
150
76
 
151
- PR-style: `git diff <base>...<head>`. Optional pathspec exclusions for `.md`, `.json`, `.env`, `Dockerfile`, README variants, `.gitlab-ci.yml` as in the branch-diff skill.
77
+ ## Persist
152
78
 
153
- ## Persist report (mandatory)
79
+ Write the complete report to:
154
80
 
155
- After the full report is written:
81
+ `<git-root>/code-reviews/code-review_<sanitized-base>_vs_<sanitized-head>_<YYYYMMDD-HHMMSS>.md`
156
82
 
157
- - Path: `<git-repo-root>/code-reviews/code-review_<sanitized-base>_vs_<sanitized-head>_<YYYYMMDD-HHMMSS>.md`
158
- - Create `code-reviews/` if needed; write **entire** document; tell the user the **absolute path**.
159
- - Optional: pipe to `scripts/save-code-review-report.sh '<base>' '<head>'` or plugin-installed copy.
83
+ Tell the user the absolute path. Optional: pipe to `scripts/save-code-review-report.sh '<base>' '<head>'`.
160
84
 
161
85
  ## Constraints
162
86
 
163
- Evidence from in-scope diff; label **Outside diff** if you used extra repo reads. Empty in-scope diff: state clearly. Do not omit section 6 or the closing distribution line.
87
+ Evidence from in-scope diff; label **Outside diff** if you used extra files. If no in-scope files after exclusions, say so in §1 and still complete the shell sections with N/A / none.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "git-code-review-agent",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "description": "Cursor IDE plugin: Technical Architect and Dev Lead skills for branch-to-branch git diff code review, merge-base PR-style analysis, and delivery risk assessment",
5
5
  "author": "",
6
6
  "license": "MIT",
package/skills/branch-diff-architecture-review/SKILL.md CHANGED
@@ -1,191 +1,312 @@
1
1
  ---
2
2
  name: branch-diff-architecture-review
3
3
  description: >-
4
- Formal branch delta code review for sharing with developers: executive summary,
5
- file counts, risk assessment, severities, actionable recommendations, merge
6
- approval section. Ignores .env, Dockerfile, README, .gitlab-ci.yml, *.md, *.json,
7
- and console.log-only churn. Saves final report to code-reviews/ with branch
8
- names and timestamp. Use with architect-dev-lead-reviewer subagent.
4
+ Formal shareable code review matching enterprise report layout: banner header,
5
+ metadata, table of contents, executive summary with metrics, file summary table,
6
+ per-file deep dive, critical issues, security review, code quality, impact
7
+ table, scoreboard, conclusion and merge recommendation. Excludes .env,
8
+ .gitlab-ci files, Dockerfile, all *.md files, env.json, and console.log churn.
9
+ Saves to code-reviews/.
9
10
  ---
10
11
 
11
- # Branch delta → formal code review (shareable)
12
+ # Branch delta → formal code review (enterprise layout)
12
13
 
13
- ## What to deliver
14
+ ## Goal
14
15
 
15
- Perform a **comprehensive delta analysis** between **base** (e.g. `main`) and **head** (development branch). Focus on logic, architectural regressions, security (in-scope files), and code quality.
16
+ Produce **one** report in the **same structural style** as a professional formal code review document: ASCII banner title, cover metadata, **Table of Contents**, sections **1–9**, stable finding IDs (**CR-**, **SEC-**, **CQ-**), markdown **tables** where shown below, and **END OF REPORT**.
16
17
 
17
- Produce one **final, professional document** suitable to share with the development team: complete, self-contained, and ending with an explicit **merge / approval recommendation**.
18
+ ## Finding IDs
18
19
 
19
- ## Metadata (fill before writing the body)
20
+ Use a short **application tag** (2–4 letters, uppercase) derived from the application name (e.g. ExecutionManagement → **EM**). Format:
20
21
 
21
- - **Application / product name:** From `package.json` `name`, root `pom.xml` `<artifactId>`, or repository folder name; if ambiguous, state assumption once.
22
- - **Base branch (target):** e.g. `main`
23
- - **Head branch (source):** e.g. `feature/xyz`
24
- - **Report date:** ISO local date (e.g. `2026-04-10`) or full timestamp.
25
- - **Scope note:** State that review excludes listed path types (below) so counts may differ from raw `git diff --stat`.
22
+ - **CR-##-TAG** — critical bugs / logic / architecture blockers (section 4), e.g. `CR-01-EM`
23
+ - **SEC-##-TAG** — security observations (section 5), e.g. `SEC-01-EM`
24
+ - **CQ-##-TAG** — code quality (section 6), e.g. `CQ-01-EM`
26
25
 
27
- ## File counts (required)
26
+ Number sequentially (01, 02, …). Reference these IDs in section 3 when introducing an issue.
28
27
 
29
- After generating the diff, collect **quantitative scope** (run from repo root):
28
+ ## Cover metadata (after banner)
29
+
30
+ Fill from project context; use `N/A` if unknown:
31
+
32
+ - **Application** — human-readable product/service name + stack if relevant (e.g. Node.js)
33
+ - **Branches Compared** — `` `head` → `base` `` (source vs integration target)
34
+ - **Review Date** — e.g. `09 April 2026`
35
+ - **Prepared For** — org/team (e.g. company — product line) or `N/A`
36
+ - **Review Scope** — e.g. “`.js` and `.ts` files only” or languages seen in the in-scope diff
37
+ - **Exclusions** — fixed list: `.env`, `.gitlab-ci.yml` / `.gitlab-ci.yaml` (GitLab CI), `Dockerfile`, **all `*.md` files**, `env.json` (any path ending with `/env.json` or repo-root `env.json`)
38
+ - **Special Exclusions** — e.g. “`console.log` additions/removals”; optional note such as “SQL injection checks excluded per scope (pre-validated at UI)” only if the user/project states that
39
+ - **Confidentiality line** — e.g. `CONFIDENTIAL — For internal engineering and QA review only.`
40
+
41
+ ## Quantitative inputs
42
+
43
+ From repo root:
30
44
 
31
45
  ```bash
32
46
  git diff --shortstat <base>...<head>
33
47
  git diff --stat <base>...<head>
48
+ git diff --name-status <base>...<head>
34
49
  ```
35
50
 
36
- In the report, include:
51
+ Use **name-status** to build the file list and TOC. **Exclude** ignored path types from qualitative review (still may appear in raw git stats — note that in scope).
37
52
 
38
- - **Files changed** (total per `git diff`; optionally note **in-review scope** after excluding ignored paths).
39
- - **Insertions / deletions** from `--shortstat` when available.
40
- - If useful, **top areas** by directory or module (brief, not a full file list unless small).
53
+ ## Severity (for CR / SEC)
41
54
 
42
- ## Severity scale (use consistently)
55
+ Use **CRITICAL**, **HIGH**, **MEDIUM**, **LOW** in uppercase in section headers as in the sample.
43
56
 
44
- | Level | Meaning |
45
- |-------|--------|
46
- | **Critical** | Must fix before merge; security breach, data loss, broken invariant, production outage risk |
47
- | **High** | Should fix before merge; serious bug, major regression, significant security gap |
48
- | **Medium** | Fix before or shortly after merge; correctness edge cases, maintainability risk |
49
- | **Low** | Follow-up acceptable; minor issues, polish |
57
+ ---
50
58
 
51
- ## Formal report template (required — use this exact section order)
59
+ ## Required report template (follow section order and visual style)
52
60
 
53
- Use professional tone throughout. Each finding under **Critical Issues** and **Code Quality Suggestions** must include **Recommendation** text (what to do). **Impact analysis** must end with **Recommendations** (bulleted).
61
+ Use lines of `=` (about 80 chars) for major section breaks and `-` for sub-blocks. Mirror this skeleton; replace placeholders with real content.
54
62
 
55
- ```markdown
56
- # Formal code review report
63
+ ```
64
+ ================================================================================
65
+ FORMAL CODE REVIEW REPORT — <APPLICATION NAME UPPERCASE>
66
+ ================================================================================
67
+
68
+ Application : <name> (<stack if relevant>)
69
+ Branches Compared : <head> → <base>
70
+ Review Date : <dd Month yyyy>
71
+ Prepared For : <org or N/A>
72
+ Review Scope : <e.g. .js and .ts files only; align with diff>
73
+ Exclusions : .env, .gitlab-ci.yml/.gitlab-ci.yaml, Dockerfile, all *.md, env.json
74
+ Special Exclusions: console.log additions/removals; <other scoped exclusions>
57
75
 
58
- | Field | Value |
59
- |-------|--------|
60
- | **Application** | <name> |
61
- | **Repository / package** | <if distinct from app name> |
62
- | **Base branch (integration target)** | `<base>` |
63
- | **Head branch (reviewed changes)** | `<head>` |
64
- | **Report date** | <YYYY-MM-DD or full timestamp> |
65
- | **Review type** | Delta review (PR-style `base...head`) |
66
- | **Reviewer capacity** | Technical Architect & Engineering Lead (automated-assisted) |
76
+ CONFIDENTIAL — For internal engineering and QA review only.
67
77
 
68
- ---
78
+ ================================================================================
79
+ TABLE OF CONTENTS
80
+ ================================================================================
69
81
 
70
- ## Executive summary
82
+ 1. Executive Summary
83
+ 2. Summary of Changes — Files Modified
84
+ 3. Detailed Change Analysis by File
85
+ 3.1 <path/to/file1.ext>
86
+ 3.2 <path/to/file2.ext>
87
+ ... (one 3.n entry per in-scope changed file; mark [NEW FILE] if added)
88
+ 4. Critical Issues & Bugs
89
+ 5. Security Review
90
+ 6. Code Quality Recommendations
91
+ 7. Impact Analysis
92
+ 8. Summary Scoreboard
93
+ 9. Conclusion & Merge Recommendation
71
94
 
72
- [3–6 sentences: purpose of the change, material outcomes, top risks, and whether the change is broadly acceptable with or without conditions. No new sections here — preview only.]
95
+ ================================================================================
96
+ 1. EXECUTIVE SUMMARY
97
+ ================================================================================
73
98
 
74
- ---
99
+ <narrative paragraphs>
75
100
 
76
- ## 1. Counts of files and change size
101
+ Use lettered major themes when helpful:
102
+ (a) <theme title>
103
+ <description>
104
+ (b) ...
77
105
 
78
- - **Files changed (git):** <n>
79
- - **Lines added / removed (approx.):** <from shortstat, or “N/A”>
80
- - **In-review scope:** [Summarize how many files were materially reviewed after excluding .env, Dockerfile, README variants, `.gitlab-ci.yml`, `*.md`, `*.json`, and console-only noise; if same as git, say so.]
106
+ Closing metrics block (adapt numbers from git + findings):
81
107
 
82
- [Optional: short table or bullets of dominant directories/modules touched.]
108
+ Total Files Changed : <n> (<modified>, <new>)
109
+ New Endpoints : <n or N/A>
110
+ Critical Bugs Found : <n>
111
+ High Issues : <n>
112
+ Code Quality Items : <n>
113
+ Merge Recommendation : <ONE LINE e.g. CONDITIONAL — Fix critical issues before merging>
83
114
 
84
- ---
115
+ ================================================================================
116
+ 2. SUMMARY OF CHANGES — FILES MODIFIED
117
+ ================================================================================
85
118
 
86
- ## 2. Overall risk assessment
119
+ Table with aligned columns:
87
120
 
88
- **Risk level:** **Low** | **Medium** | **High** | **Critical**
121
+ # File Path Type Summary
122
+ ---- -------------------------------------------------- ---------- ---------------------------------------------------
123
+ 1 <path> Modified <one-line summary>
124
+ 2 <path> NEW FILE <one-line summary>
125
+ ...
89
126
 
90
- **Rationale:** [2–5 sentences tying risk to logic change, architecture, security, and test posture.]
127
+ ================================================================================
128
+ 3. DETAILED CHANGE ANALYSIS BY FILE
129
+ ================================================================================
91
130
 
92
- **Mitigations already observed (if any):** [tests, feature flags, backward compatibility — or “None evident in diff.”]
131
+ For EACH file in the TOC (subsection 3.n):
93
132
 
94
- ---
133
+ ------------------------------------------------------------------------
134
+ 3.n <relative/path/to/file> [optional: NEW FILE — line count hint]
135
+ ------------------------------------------------------------------------
95
136
 
96
- ## 3. Critical issues
137
+ Change Type : <e.g. Refactor / Bug Fix / Feature Addition>
138
+ Risk Level : <LOW | LOW-MEDIUM | MEDIUM | MEDIUM-HIGH | HIGH | CRITICAL>
97
139
 
98
- [If none: **No critical issues identified** under the stated scope, and one sentence on what was checked.]
140
+ Optional deeper numbering (3.n.1, 3.n.2) for large files.
99
141
 
100
- For **each** issue, use this sub-structure:
142
+ Include where useful:
143
+ - Imports added/removed
144
+ - BEFORE / AFTER snippets (concise, from diff)
145
+ - Assessment: bullets
146
+ - Cross-references: "See CR-XX-TAG"
101
147
 
102
- ### CR-001 — <short title>
148
+ ================================================================================
149
+ 4. CRITICAL ISSUES & BUGS
150
+ ================================================================================
103
151
 
104
- - **Severity:** Critical | High | Medium | Low
105
- - **Category:** [Bug / Security / Architecture / Logic / Other]
106
- - **Location:** `path` (and symbol or line if clear from diff)
107
- - **Description:** [What is wrong and why it matters]
108
- - **Recommendation:** [Specific, actionable fix or validation step]
152
+ Per issue:
109
153
 
110
- (Continue CR-002, … as needed.)
154
+ ------------------------------------------------------------------------
155
+ CR-##-TAG | SEVERITY: CRITICAL|HIGH|MEDIUM|LOW
156
+ File : <path> — <function or area>
157
+ ------------------------------------------------------------------------
111
158
 
112
- ---
159
+ DESCRIPTION:
160
+ <multi-line>
113
161
 
114
- ## 4. Code quality suggestions
162
+ IMPACT:
163
+ <multi-line>
115
164
 
116
- [Actionable improvements — not excluded-file or console.log noise.]
165
+ FIX:
166
+ <concrete steps; Option A / Option B if helpful>
117
167
 
118
- For **each** suggestion:
168
+ ================================================================================
169
+ 5. SECURITY REVIEW
170
+ ================================================================================
119
171
 
120
- ### CQ-001 — <short title>
172
+ If scope excludes a class of checks (e.g. SQLi), state a one-line note after the section title.
121
173
 
122
- - **Severity:** Low | Medium (quality items are rarely Critical/High unless they imply risk)
123
- - **Location:** `path`
124
- - **Observation:** [e.g. naming, duplication, complexity]
125
- - **Recommendation:** [Concrete refactor or pattern]
174
+ Per item:
126
175
 
127
- (Continue CQ-002, … as needed.)
176
+ ------------------------------------------------------------------------
177
+ SEC-##-TAG | SEVERITY: MEDIUM|LOW|...
178
+ <title short>
179
+ ------------------------------------------------------------------------
128
180
 
129
- ---
181
+ OBSERVATION:
182
+ ...
130
183
 
131
- ## 5. Impact analysis
184
+ RECOMMENDATION:
185
+ ...
132
186
 
133
- **Stability & maintainability:** [Paragraph on how the change affects the codebase long-term.]
187
+ ================================================================================
188
+ 6. CODE QUALITY RECOMMENDATIONS
189
+ ================================================================================
134
190
 
135
- **Operational / deployment:** [If relevant: rollout, config, migrations, observability.]
191
+ Per item:
136
192
 
137
- **Recommendations:**
193
+ ------------------------------------------------------------------------
194
+ CQ-##-TAG | <short title>
195
+ ------------------------------------------------------------------------
138
196
 
139
- - [Prioritized follow-up 1]
140
- - [Prioritized follow-up 2]
141
- - …
197
+ FILE: <path>
142
198
 
143
- ---
199
+ OBSERVATION:
200
+ ...
144
201
 
145
- ## 6. Merge recommendation
202
+ RECOMMENDATION:
203
+ ...
146
204
 
147
- **Recommendation:** [Choose one and bold it]
205
+ ================================================================================
206
+ 7. IMPACT ANALYSIS
207
+ ================================================================================
148
208
 
149
- - **Approve merge** — No blocking issues; optional follow-ups may be tracked.
150
- - **Approve merge with conditions** — Merge acceptable only after: [list specific CR items or tasks].
151
- - **Request changes** — Do not merge until: [list blockers].
152
- - **Do not merge** — [Rare; fundamental blocker or unacceptable risk.]
209
+ Markdown table:
153
210
 
154
- **Summary for approvers:** [One short paragraph restating the decision drivers.]
211
+ | Area | Impact | Risk | Notes |
212
+ |------|--------|------|-------|
213
+ | <area> | <text> | LOW / MEDIUM / HIGH / CRITICAL / POSITIVE | <text> |
214
+ | ... | ... | ... | ... |
155
215
 
156
- ---
216
+ Cover major themes: refactors, feature areas, security, ops, positive changes.
217
+
218
+ ================================================================================
219
+ 8. SUMMARY SCOREBOARD
220
+ ================================================================================
157
221
 
158
- *End of report — this document is intended for distribution to engineering stakeholders.*
222
+ Category table with Count and Findings (multi-line cell content allowed):
159
223
 
224
+ | Category | Count | Findings |
225
+ |----------|-------|----------|
226
+ | CRITICAL Bugs | n | CR-..-TAG: ... |
227
+ | HIGH Issues | n | ... |
228
+ | Security Observations | n | SEC-... |
229
+ | Code Quality Items | n | CQ-... |
230
+ | Positive Changes | n+ | bullet themes |
231
+
232
+ ================================================================================
233
+ 9. CONCLUSION & MERGE RECOMMENDATION
234
+ ================================================================================
235
+
236
+ MERGE RECOMMENDATION: ** <APPROVE | CONDITIONAL APPROVAL | REQUEST CHANGES | DO NOT MERGE> **
237
+ <one-line elaboration>
238
+
239
+ Narrative: strengths, then blockers.
240
+
241
+ MUST FIX BEFORE MERGE:
242
+ [CRITICAL] CR-..-TAG
243
+ <one-line + detail>
244
+ [HIGH] CR-..-TAG or SEC-..-TAG
245
+ ...
246
+
247
+ SHOULD ALSO ADDRESS:
248
+ [MEDIUM] CQ-..-TAG: ...
249
+ ...
250
+
251
+ Closing footer block:
252
+
253
+ ------------------------------------------------------------------------
254
+ Reviewed By : <e.g. Automated Code Review System / Technical Architect & Dev Lead>
255
+ Application : <name>
256
+ Source Branch : <head>
257
+ Target Branch : <base>
258
+ Review Date : <same as cover>
259
+ Status : <mirror merge recommendation>
260
+ ------------------------------------------------------------------------
261
+
262
+ ================================================================================
263
+ END OF REPORT
264
+ ================================================================================
160
265
  ```
161
266
 
162
- ## Paths excluded from review (unchanged)
267
+ ## Paths excluded from qualitative review
268
+
269
+ Do **not** review, quote as findings, or include in §2 / §3 / TOC for these paths (match by **basename** unless noted):
270
+
271
+ | Path / pattern | Notes |
272
+ |----------------|--------|
273
+ | **`.env`** | Any file named `.env` (e.g. repo root or subfolders). |
274
+ | **`.gitlab-ci.yml`**, **`.gitlab-ci.yaml`** | GitLab CI config (covers the usual `.gitlab-ci` files). |
275
+ | **`Dockerfile`** | Any `Dockerfile` in the tree. |
276
+ | **`*.md`** | All Markdown files (includes `README.md`, `CHANGELOG.md`, etc.). |
277
+ | **`env.json`** | Any path ending with `/env.json` or `env.json` at repo root. |
278
+
279
+ **Other `*.json` files are in scope** for review unless the user asks to exclude them.
163
280
 
164
- | Pattern | Notes |
165
- |---------|--------|
166
- | `.env`, `**/.env` | |
167
- | `Dockerfile` | |
168
- | `README.md`, `Readme.md` | |
169
- | `.gitlab-ci.yml` | |
170
- | `*.md`, `*.json` | |
281
+ When building TOC, §2 table, and §3, **skip** excluded paths. Raw `git diff --stat` may still count them — note that under **Review Scope** if needed.
171
282
 
172
- Skip these in analysis and recommendations. Do not count excluded-only churn as findings.
283
+ **Optional — narrow `git diff` output** (same rules):
284
+
285
+ ```bash
286
+ git diff <base>...<head> -- . \
287
+ ':(exclude,glob)**/.env' \
288
+ ':(exclude,glob)**/.gitlab-ci.yml' \
289
+ ':(exclude,glob)**/.gitlab-ci.yaml' \
290
+ ':(exclude,glob)**/Dockerfile' \
291
+ ':(exclude,glob)**/*.md' \
292
+ ':(exclude,glob)**/env.json'
293
+ ```
173
294
 
174
295
  ## `console.log` rule
175
296
 
176
- Ignore hunks that only add/remove/reformat `console.log` / `console.debug` / `console.info` for debugging. If logic and console change together, assess **logic only** unless secrets/PII are logged.
297
+ Ignore hunks that only add/remove/reformat `console.log` / `console.debug` / `console.info` for debugging. Mixed hunks: assess **logic only** unless secrets/PII are logged.
177
298
 
178
299
  ## Workflow
179
300
 
180
- 1. Confirm **base** and **head**; resolve **application name** from project metadata.
181
- 2. `git fetch` if needed; `git diff <base>...<head>` (optional pathspec exclusions as before).
182
- 3. Run `git diff --shortstat` and `git diff --stat` for **Counts** section.
183
- 4. Filter excluded paths and console-only noise from qualitative review.
184
- 5. Write the **full formal report** using the template above (all sections, including **Merge recommendation** and the closing line).
185
- 6. **Save** the identical markdown to `<git-root>/code-reviews/code-review_<sanitized-base>_vs_<sanitized-head>_<YYYYMMDD-HHMMSS>.md` and state the absolute path to the user.
186
- 7. Delegate to **architect-dev-lead-reviewer** for an isolated pass if needed — same template and save step.
301
+ 1. Resolve **application name**, **tag** for IDs, **base** / **head**, **Prepared For** if user supplied.
302
+ 2. `git fetch` if needed; `git diff <base>...<head>` (optional pathspec exclusions).
303
+ 3. Run `--shortstat`, `--stat`, `--name-status` for metrics and file list.
304
+ 4. Build **TOC** and **section 2** from in-scope files only.
305
+ 5. Write **section 3** per file (depth proportional to change size).
306
+ 6. Consolidate into **sections 4–6** with stable IDs; **section 7** table; **section 8** scoreboard; **section 9** conclusion.
307
+ 7. **Save** full report to `<git-root>/code-reviews/code-review_<sanitized-base>_vs_<sanitized-head>_<YYYYMMDD-HHMMSS>.md` and give the absolute path.
308
+ 8. Delegate to **architect-dev-lead-reviewer** when needed — same layout.
187
309
 
188
310
  ## Helper scripts
189
311
 
190
- - `scripts/git-diff-branches.sh <base> <head> [outfile]`
191
- - `scripts/save-code-review-report.sh '<base>' '<head>'` (stdin = full report markdown)
312
+ - `scripts/git-diff-branches.sh`, `scripts/save-code-review-report.sh`