Review Git Branch

Review Git Branch

Scope

• Work only with the specified branch and local repository state.
• Do not run git fetch, git pull, or any remote/network operations.
• Do not run git checkout, or any operations which modify the current repository state.
• Do not run external checks (CI, linters, etc.) unless the user explicitly asks.

Workflow

1. Resolve the default branch

Use local refs only. Typical defaults are origin/main or origin/master.

• Prefer: git symbolic-ref refs/remotes/origin/HEAD (if it exists) and strip refs/remotes/ to get the default branch name.
• If that ref does not exist, try origin/main; if origin/main does not exist, try origin/master. Use whichever exists locally.

2. Find the fork point

Fork point = latest commit that is both on the current branch and on the default branch.

git merge-base <default_branch> <branch under review>

Use that commit as the fork point. If the user is not on a branch (detached HEAD), use HEAD as the tip.

3. List commits to review

Commits on the current branch that are not on the default branch (i.e. after the fork point):

git log <fork_point>..HEAD --oneline

For the review, get full details and patch for each commit, e.g.:

git log <fork_point>..HEAD --reverse

Then for each commit: git show <commit> to get message + diff.

4. Understand the project

• Look up the documentation and the README, if any. Understand the project.
• Is there any contribution guideline? If so, review the commits against it.
• AI agent instructions: Look for instruction files used by GitHub Copilot and other AI agents (e.g. .github/copilot-instructions.md, .github/copilot/, .cursorrules, .cursor/rules, or similar). If present, use that knowledge during the review (e.g. style, conventions, patterns). Do not mention the absence of such files in the final report.

5. Review the commits and the branch

Comment on the commits only if the commit history is not appropriate:

• title or body is unclear, doesn't reflect the change, or contains misspellings.
• the history makes no sense, e.g. a feature and a fixup of the same feature.

If the commit history is clear and well-structured, comment on the overall change only, not individual commits.

6. Additional review points to consider

• Are the comments relevant and helpful? Or just explaining what is already clear from the code?
• Are there any code style issues? (e.g. inconsistent formatting, naming, etc.)
• Are there any comments missing or everything is clear from the code?
• Are magic values explained?
• Breaking changes: Look for potential breaking changes (e.g. removed or renamed APIs, changed behaviour, config/schema changes, dependency bumps that drop support). If identified, highlight them in the final report. Do not mention the absence of breaking changes if none were found.

7. Documentation changes

When reviewing commits that touch documentation:

• Consistency over new rules: Documentation consistency is more important than enforcing new rules. If the changes are only updating part of the documentation, do not enforce new or stricter rules; prioritize consistency with the existing documentation page.
• When to apply full-doc standards: General rules and style guides (e.g. Espressif manual style) should be considered when the full documentation (or doc set) is under review. For partial or single-page updates, consistency with that page is what matters most.

Output shape

• State: current branch name, default branch, fork point (short hash), number of commits.
• Summarize the change.
• Breaking changes (if any): Call out potential breaking changes clearly.
• Issues which need to be addressed.
• Recommendations for improvement, if any.

Keep the review concise; focus on what matters for correctness, maintainability, and consistency with the rest of the project.