neo-pr

name	neo-pr
description	Use this skill when the user asks to create, draft, review, format, or generate a Pull Request (PR) title and description, specify target or source branches for a repository, or convert git branch diffs into concise, high-impact, non-AI-slop PR content.
license	MIT
compatibility	Requires Python 3.10+ (uv or python3) for git-pr-extractor.py, and Node.js for analyze-slop.js validation.
metadata	{"author":"Ben Knight Dark","version":"1.0.0","patterns":"generator, reviewer, inversion"}

Neo PR Generator & Refiner

neo-pr is an expert skill engineered to generate precise, concise, and non-AI-slop Pull Request (PR) titles and descriptions for Git repositories. It proactively guides the user to clarify repository and branch targets, extracts change histories, and outputs clear, highly structured PR content.

---

Gotchas

• Non-existent or Unaligned Branches: If the specified source or target branch does not exist locally or on remote, prompt the user to run git fetch or provide the correct branch name. Do not invent non-existent base branches.
• Overly Long Diffs and Token Overhead: If the branch diff spans dozens of files or thousands of lines, inspect git diff --stat and commit logs first to gain high-level context instead of loading full diffs at once.
• De-slop Does Not Mean Removing Technical Substance: When stripping AI fluff, eliminate throat-clearing openers (e.g., "It is worth noting that...", "This PR aims to..."), but strictly preserve essential context, key logic shifts, breaking changes, and test instructions.

---

Workflow Checklist

• Step 1 — Perceive (Gather Branch & Repository Context): Identify the repository path, source branch (source branch), and target branch (target branch). If unspecified, prompt the user or detect the current Git state.
• Step 2 — Reason & Load References (Load Templates & Guidelines): Read pr-template.md for structural standards and de-slop conventions.
• Step 3 — Act: Extract Diff (Fetch Change Record): Execute the helper script git-pr-extractor.py to retrieve commit logs, file statistics, and diff snippets.
• Step 4 — Act: Generate & De-slop (Produce Concise PR Content): Write a Conventional Commits title and bulleted PR description while eliminating all AI tells.
• Step 5 — Verify (Quality Check): Verify that the generated title and description adhere to de-slop standards (optionally run analyze-slop.js to score density).

---

Detailed Guidelines

Step 1 — Perceive (Gather Branch & Repository Context)

Determine the following core parameters:

1. Repository Context: Current working directory or specified GitHub/GitLab workspace.
2. Source Branch: Branch containing the new changes (e.g., feature/user-auth or current checked-out branch).
3. Target Branch: Base branch to merge into (e.g., main, master, or develop).

If the user has not specified branches, ask with a concise prompt:

"Please specify your source branch (e.g., feature/xxx) and target branch (e.g., main or develop). If omitted, I will default to PRing the current branch into main."

---

Step 2 — Reason & Load References

Load relevant design documents based on diff scope:

• PR Structure & Template: Read references/pr-template.md for standard markdown sections.
• De-slop Rules: Apply core neo-stop-slop principles (active voice, remove filler phrases, focus on objective facts).

---

Step 3 — Act: Extract Diff (Fetch Change Record)

Run git-pr-extractor.py non-interactively in the target repository directory:

python3 skills/neo-pr/scripts/git-pr-extractor.py --target-branch <target> --source-branch <source>

Alternatively, run native Git commands if script execution is unavailable:

git log <target>..<source> --oneline
git diff <target>..<source> --stat

---

Step 4 — Act: Generate & De-slop (Produce Concise PR Content)

Construct the PR Title and Description based on extracted commit and diff context.

1. PR Title Standard (Conventional Commits)

• Format: <type>(<scope>): <short summary>
• Example: feat(auth): 新增 JWT 驗證與 Token 自動刷新
• Rules:
  • Do not begin with filler phrases ("This PR implements...", "A commit to...").
  • Keep under 50 characters, imperative mood, direct and actionable.

2. PR Output Standard Structure

The PR output must strictly be wrapped in a Markdown code block (i.e. raw Markdown source code ```markdown ... ```) so that users can easily copy it directly into GitHub/GitLab PR description fields. The content inside the code block must consist exclusively of the following two sections:

```markdown
標題：
<Conventional Commits 格式標題>

內容：
- 列點並重點化的說明重要變更內容（包含主要模組/檔案調整、邏輯變更與重大影響）。
```

3. Strict De-slop Rules

• ❌ Never use: "It is worth noting that", "Needless to say", "This PR aims to", "In summary", "Clearly".
• ❌ Avoid hyperbolic fluff: "dramatically improves", "seamlessly integrates", "highly robust".
• ⭕ Use concrete facts & metrics: "reduces response latency by 30ms", "fixes NullReferenceException on null payload".

---

Step 5 — Verify (Quality Check)

1. Ensure no critical modifications are omitted from the generated title or description.
2. Run de-slop score check if skills/neo-stop-slop/scripts/analyze-slop.js is available:

   node skills/neo-stop-slop/scripts/analyze-slop.js --input "<generated PR description>" --format json
   

   Confirm slopDensityScore is under 0.5% (Grade A+).