MindfulPR

MindfulPR is a GitHub Action that estimates pull request cognitive load and posts a review-ready summary comment.

Why This Exists

MindfulPR maps pull request structure to cognitive science concepts:

• Working memory limits: too many active variables increase review burden.
• Cognitive load theory: deep nesting and high branch count add extraneous load.
• Metacognition: feedback helps authors understand how code may feel to first-time readers.

Current MVP Scope

• Python file analysis in pull requests.
• Function-level metrics:
  • Variables in scope
  • Nesting depth
  • Cyclomatic complexity
  • Function length (LOC)
• Pull request summary comment with per-function risk flags.

Repository Structure

mindfulpr/
├── action.yml
├── requirements.txt
├── src/
│   ├── action.py
│   ├── github_client.py
│   ├── metrics.py
│   ├── parser.py
│   └── suggestions.py
├── tests/
└── docs/

Usage

Add the workflow below in .github/workflows/mindfulpr.yml:

name: MindfulPR

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write
  issues: write

jobs:
  mindfulpr:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run MindfulPR
        uses: ./
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}

Local Development

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python -m unittest discover -s tests -p "test_*.py"

Notes

• The LLM refactoring path is scaffolded in src/suggestions.py and can be activated in Phase 2.
• docs/metrics-explanation.md contains the cognitive science rationale used in comments.