From c544a840505867a56d64e51ea02f6fcab3b83c57 Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar Date: Mon, 23 Mar 2026 08:53:57 -0400 Subject: [PATCH] pr skill --- AI/commands/srid-do.md | 9 ++++- AI/commands/srid-plan.md | 5 +++ AI/skills/github-pr/SKILL.md | 78 ++++++++++++++++++++++++++++++++++++ 3 files changed, 90 insertions(+), 2 deletions(-) create mode 100644 AI/skills/github-pr/SKILL.md diff --git a/AI/commands/srid-do.md b/AI/commands/srid-do.md index 92fb36d..e59b115 100644 --- a/AI/commands/srid-do.md +++ b/AI/commands/srid-do.md @@ -35,7 +35,7 @@ Take a GitHub issue, prompt, or task description and execute it top-to-bottom: i ### 3. **Open Draft PR** - Push the branch and open a **draft** pull request using `gh pr create --draft`. - - PR title should be concise. Body should summarize what changed and why. + - **Use the `github-pr` skill** for the title and body — no bullet-list dumps. ### 4. **CI Loop** @@ -60,7 +60,12 @@ Take a GitHub issue, prompt, or task description and execute it top-to-bottom: i - Run `just ci` again. - If it fails, enter the CI fix loop from step 4 again. -### 7. **Done** +### 7. **Update PR Description** + + - After all changes (elegance, CI fixes), re-check the PR title/body. + - If scope changed, update via `gh pr edit` per the `github-pr` skill. + +### 8. **Done** - Report the PR URL and a brief summary of what was done. diff --git a/AI/commands/srid-plan.md b/AI/commands/srid-plan.md index 69523c8..9195412 100644 --- a/AI/commands/srid-plan.md +++ b/AI/commands/srid-plan.md @@ -58,6 +58,11 @@ Respond to the user's prompt using Plan mode, grounded in thorough research rath - Use the `ExitPlanMode` tool to present the plan and solicit user feedback. - Iterate based on feedback before exiting plan mode. +### 7. **Execute on Approval** + + - Once the user approves the plan, execute it using the `/srid-do` command. + - Pass the plan context as the prompt so `/srid-do` has full understanding of what to implement. + ## Principles - **Facts over assumptions**: Every claim in the plan should be backed by something you read or verified. diff --git a/AI/skills/github-pr/SKILL.md b/AI/skills/github-pr/SKILL.md new file mode 100644 index 0000000..dcecdf8 --- /dev/null +++ b/AI/skills/github-pr/SKILL.md @@ -0,0 +1,78 @@ +--- +name: github-pr +description: Write engaging GitHub PR titles and descriptions. Use when creating or updating PRs. Avoids boring bullet lists; uses narrative paragraphs with bold/italic for emphasis. +--- + +# GitHub PR Writing + +Write PR descriptions that fellow devs actually want to read. + +## Anti-patterns (what LLMs typically produce) + +- Flat bullet lists of every file changed +- Implementation-detail dumps ("added `foo` parameter to `bar` function") +- Generic titles like "Update configuration" or "Fix bug in module" +- "## Changes" / "## Testing" / "## Summary" boilerplate headers +- Restating the diff in English + +## What to write instead + +**Title**: Short, specific, interesting. Convey *what changed from a user/dev perspective*, not which files were touched. Use imperative mood. Under 70 chars. + +**Body**: Write in **paragraphs**, not bullet lists. Structure: + +1. **Opening paragraph** — What this PR does and *why*, in 2-3 sentences. Bold the key behavioral change. If there's a motivating problem, state it directly. + +2. **Details paragraph(s)** — Only if the approach is non-obvious or has trade-offs worth calling out. Use *italics* for subtle points. Keep it high-level; reviewers can read the diff for implementation details. + +3. **Anything notable** — Breaking changes, migration steps, or things reviewers should pay attention to. Only if applicable. Use `> blockquote` for callouts. + +## Style rules + +- Write for a dev skimming their PR feed — they should get the gist in 5 seconds +- **Bold** the most important phrase in each paragraph +- *Italics* for nuance, caveats, secondary points +- No bullet lists unless listing 3+ discrete items that genuinely aren't a narrative +- No "## Summary" or "## Changes" headers — just write +- No filler: "This PR...", "In this change...", "As part of..." — start with the substance +- Link to issues/discussions where relevant (`Closes #123`, `See #456`) +- If the PR is trivial (typo fix, version bump), a one-liner body is fine + +## Updating existing PRs + +When the user pushes further changes to an already-PR'd branch: + +1. Check if the PR title/description still accurately reflects the full scope +2. If new commits meaningfully change what the PR does, update the title and/or body via `gh pr edit` +3. Don't rewrite from scratch — amend the existing description to cover new ground +4. Add a brief note about what changed if the scope expanded significantly + +## Examples + +### Bad (typical LLM output) +``` +Title: Update NixOS configuration and add new service + +## Summary +- Added `kolu` service configuration +- Updated `flake.lock` +- Modified port from 8080 to 8090 +- Added health check endpoint +- Updated README + +## Testing +- Tested locally +``` + +### Good +``` +Title: Add kolu service with health monitoring + +**Kolu now runs as a standalone NixOS service** with its own systemd +unit and a dedicated health-check endpoint. Previously it was bolted +onto the main app process, which made restarts disruptive. + +The service binds to port 8090 to avoid clashing with the dev server. +*Health checks hit `/healthz` every 30s — systemd restarts the +service on three consecutive failures.* +```