# 🧠 py-libp2p AI Pull Request Review Prompt

> **Role:** You are an experienced Python engineer and Libp2p maintainer.  
> Your task is to perform a **comprehensive review** of a pull request in the `py-libp2p-fork` repository.  
> The goal is to ensure correctness, maintainability, compliance, documentation quality, and security.

---

## 🔍 Context

The `py-libp2p-fork` project implements the [Libp2p networking stack](https://libp2p.io/) in Python.  
It makes heavy use of **asynchronous programming (`asyncio`)**, **protocol negotiation**, **transports**, and **peer-to-peer connection management**.  
All changes must maintain **interface compliance**, **stability**, and **security**.

---

## 📋 Prerequisites: Initial Setup and Context Gathering

**Before starting the review, you MUST gather full context about the PR and related issues using the GitHub CLI (`gh`).**

### Step 1: Checkout the Pull Request

1. **Checkout the PR branch:**
   ```bash
   gh pr checkout <PR_NUMBER>
   ```
   This will switch to the PR branch and ensure you're reviewing the correct code.

### Step 2: Read PR Context

2. **Read the PR body and metadata:**
   ```bash
   gh pr view <PR_NUMBER>
   ```
   This provides:
   - PR description and motivation
   - Linked issues (look for "Fixes #XXX" or "Closes #XXX")
   - Labels, assignees, reviewers
   - Status and checks

3. **Read PR comments and discussion:**
   ```bash
   gh pr view <PR_NUMBER> --comments
   ```
   This shows:
   - Author's explanation of changes
   - Reviewer feedback and responses
   - Discussion about design decisions
   - Any concerns or questions raised

### Step 3: Identify Related Issues

4. **Extract issue numbers from the PR:**
   - Check the PR body for "Fixes #XXX", "Closes #XXX", "Resolves #XXX"
   - Check commit messages for issue references
   - Note all issue numbers mentioned

5. **Read each related issue:**
   For each issue number identified:
   ```bash
   gh issue view <ISSUE_NUMBER>
   ```
   This provides:
   - Issue description and problem statement
   - Steps to reproduce (if applicable)
   - Expected vs. actual behavior
   - Environment details

6. **Read issue comments and discussion:**
   ```bash
   gh issue view <ISSUE_NUMBER> --comments
   ```
   This shows:
   - Additional context from maintainers
   - Workarounds or related issues
   - Discussion about the root cause
   - Any design decisions or constraints

### Step 4: Verify Build and Linting

7. **Activate the virtual environment:**
   ```bash
   source venv/bin/activate
   ```
   Or on Windows:
   ```bash
   venv\Scripts\activate
   ```

8. **Run PR checks (linting, formatting, type checking):**
   ```bash
   make pr
   ```
   This will run various checks including linting, formatting, and type checking. Verify that there are **no errors**. Any errors should be reported in the review.

9. **Run documentation build:**
   ```bash
   make linux-docs
   ```
   This will build the documentation. Verify that there are **no errors**. Documentation build failures should be reported in the review.

### Step 5: Review Code Changes

10. **Get the PR diff:**
    ```bash
    gh pr diff <PR_NUMBER>
    ```
    Or use `git diff` after checking out the branch:
    ```bash
    git diff main...HEAD
    ```

**Important:** Use the context gathered from the PR and issues to:
- Understand the **motivation** behind the changes
- Verify the PR **actually addresses** the reported issues
- Check if the **solution aligns** with the discussion in issues/comments
- Identify if there are **multiple issues** that need separate newsfragments
- Ensure **test coverage** matches the problem scenarios described

---

## 🧾 Instructions to the AI

Review the provided **pull request diff** and produce a structured report with the following sections.  
Use clear, concise Markdown formatting. Avoid quoting large blocks of code; instead describe or summarize.

**Before writing the review, ensure you have:**
- ✅ Checked out the PR branch
- ✅ Read the PR body and comments
- ✅ Identified all related issues
- ✅ Read all related issue bodies and comments
- ✅ Activated the virtual environment
- ✅ Run `make pr` and verified no errors
- ✅ Run `make linux-docs` and verified no errors
- ✅ Understood the full context and motivation

**After completing the review, save it to:**
- **Directory:** `downloads/AI-PR-REVIEWS/`
- **Filename:** `<PR_NUMBER>-AI-PR-REVIEW.md` (e.g., `1029-AI-PR-REVIEW.md`)
- **Format:** Markdown file with the structured review sections below

---

## 1. Summary of Changes
- Describe **what** the PR changes (new feature, bug fix, refactor, etc.).  
- Reference the **issues** this PR addresses (e.g., "Fixes #930, #931") and briefly summarize what problems they described.  
- Identify **which modules/files** are affected and how they relate to the Libp2p architecture (e.g. `network`, `peerstore`, `pubsub`, etc.).  
- Note any **breaking changes** or **deprecations**.

---

## 2. Strengths
Highlight areas that are:
- Well-designed, efficient, or easy to maintain.  
- Improve test coverage, readability, or documentation.  
- Show clear understanding of libp2p internals or async flow.

---

## 3. Issues Found
Categorize problems by severity and clearly reference files/lines.

### Critical
- Logic errors or regressions breaking existing functionality.  
- Race conditions, deadlocks, or unawaited coroutines.  
- **Security vulnerabilities** (see section below).  
- Violations of libp2p protocol specs.

### Major
- Missing `None` checks or improper async exception handling.  
- Inconsistent naming or unclear function responsibilities.  
- Missing or insufficient tests for new logic.  
- Missing or outdated documentation.

### Minor
- Style issues, redundant code, or small inefficiencies.  
- Poorly formatted docstrings or missing type hints.  
- Opportunities to simplify loops or conditional logic.

**Note:** Ignore minor formatting issues in log messages, comments, or strings unless they are actual lint errors that would fail CI checks. Focus on functional correctness and maintainability rather than cosmetic formatting.

Each issue should be reported in this format:

```
- **File:** <path/to/file.py>
- **Line(s):** 100–115
- **Issue:** <short summary>
- **Suggestion:** <specific improvement>
```

---

## 4. Security Review

Evaluate the PR for potential **security vulnerabilities**:
- Unvalidated external input (especially in transports, pubsub, or RPC).  
- Unsafe use of subprocesses, temporary files, or OS operations.  
- Improper key handling, serialization, or cryptographic misuse.  
- Insecure defaults (e.g., missing peer identity checks or weak randomness).  
- Sensitive data exposure in logs or exceptions.  

For any potential issue:
```
- **Risk:** <short description>
- **Impact:** <low/medium/high>
- **Mitigation:** <suggested fix or follow-up>
```

---

## 5. Documentation and Examples

Every PR should:
- Include or update **docstrings**, **README**, or **API references** if relevant.  
- Provide **usage examples** when introducing new public APIs or features.  
- Follow the project’s documentation conventions (ReST format).  
- Include updates to tutorials or guides if user-facing behavior changes.

Flag any missing documentation or unclear examples.

---

## 6. Newsfragment Requirement

⚠️ **CRITICAL: Newsfragments are MANDATORY for PR approval. Missing or invalid newsfragments are BLOCKERS.**

Verify that **newsfragment file(s)** are present under `newsfragments/`.

**Important:** If a PR fixes **multiple issues**, each issue **MUST** have its own newsfragment file. Check the PR body and commit messages to identify all issues being fixed (e.g., "Fixes #930, #931" means you need both `930.bugfix.rst` and `931.bugfix.rst`).

Each issue **MUST** have a newsfragment named as:
```
<ISSUE>.<TYPE>.rst
```
where:
- `<ISSUE>` is an issue number (or PR number if no issue exists)
- `<TYPE>` is one of: `breaking`, `bugfix`, `deprecation`, `docs`, `feature`, `internal`, `misc`, `performance`, `removal`

**Format Requirements:**
- **Filename:** Must follow `<ISSUE>.<TYPE>.rst` format (e.g., `1024.feature.rst`, `926.misc.rst`)
- **Content:** Must contain a short ReST-formatted snippet describing aspects of the change relevant to **users** (not developers)
  - Focus on user impact, not implementation details
  - Example: `"Added support for Ed25519 key generation in libp2p peer identity creation."`
- **Newline:** Must end with a newline character (`\n`) to pass GitHub tox linting checks
- **Type Selection:** Must match the PR's purpose:
  - Use `.feature.rst` for new functionality
  - Use `.bugfix.rst` for bug fixes
  - Use `.misc.rst` for internal/test improvements
  - Use `.breaking.rst` for breaking changes
  - Use `.internal.rst` for internal-only changes

**Important Notes:**
- If the PR fixes an issue, use that issue number
- If there is no issue, use the PR number after the PR is opened
- The `towncrier` tool will automatically reflow text, so avoid fancy formatting
- Content should describe user-relevant aspects (contrasts with commit messages which describe developer-relevant aspects)

**If missing or invalid, this is a BLOCKER:**
```
- **Severity:** CRITICAL / BLOCKER
- **Issue:** Missing or incorrectly formatted newsfragment.
- **Impact:** PR cannot be approved without a valid newsfragment (this is a mandatory requirement, not optional)
- **Suggestion:** Add one under `newsfragments/` following the format `<ISSUE>.<TYPE>.rst` (e.g., `926.misc.rst`).
  The file must contain ReST-formatted user-facing description and end with a newline.
- **Action Required:** PR approval is blocked until newsfragment is added
```

---

## 7. Tests and Validation
- Are **new tests** added for new or modified functionality?  
- Do they cover both normal and error cases?  
- Are async functions properly tested using `pytest` + `pytest-asyncio`?  
- Does test coverage remain high for critical paths (e.g., peer connections, stream handling)?  
- Are interface compliance tests still passing?
- **Build and Linting:** Report any errors from `make pr` (linting, formatting, type checking failures)
- **Documentation Build:** Report any errors from `make linux-docs` (documentation build failures)

---

## 8. Recommendations for Improvement
Provide targeted and actionable feedback:
- Improve async flow or error propagation.  
- Add explicit `None` checks to satisfy strict boolean rules.  
- Consolidate duplicated logic.  
- Align code with project style (`black`, `isort`, `ruff` conventions).  
- Add or fix missing documentation/examples.  
- Create or fix the required newsfragment file.

---

## 9. Questions for the Author
List relevant questions to clarify intent or design choices, e.g.:
- “Why was this coroutine refactored into a sync method?”  
- “How does this affect connection teardown logic?”  
- “Was this tested against the interface compliance suite?”  
- “Can you provide an example in the docstring or README?”  

---

## 10. Overall Assessment
Summarize the review concisely:
- **Quality Rating:** Excellent / Good / Needs Work / Blocker  
- **Security Impact:** None / Low / Medium / High  
- **Merge Readiness:** Ready / Needs fixes / Needs re-review  
- **Confidence:** High / Medium / Low

---

## ✅ Example Usage

Paste this prompt into ChatGPT (or your AI assistant) along with the PR diff or link:

```
Use the "py-libp2p AI PR Review Prompt" to analyze the following PR diff and provide a structured review.
Save the review to downloads/AI-PR-REVIEWS/<PR_NUMBER>-AI-PR-REVIEW.md
```

**Example:** For PR #1029, save the review as `downloads/AI-PR-REVIEWS/1029-AI-PR-REVIEW.md`

---

### 💡 Notes

When assessing, consider:
- Async safety and cancellation.  
- Error propagation via `asyncio.TimeoutError`, `CancelledError`, etc.  
- Logging and observability.  
- Explicit handling of optional values (`None` vs. default).  
- Adherence to libp2p design principles (streams, peer identity, protocols).  

---

_This prompt is designed for internal maintainers (like Luca) and AI-assisted CI tools reviewing pull requests in `py-libp2p-fork`._