القائمة
Generate pull-request descriptions from branch diffs when the task is to explain change scope, motivation, testing, risk, and reviewer guidance for a reviewable branch.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Run Microsoft SkillOpt experiments for agent skills, prompts, or instruction files with clean train/validation/held-out splits, adapter setup, bounded rollouts, artifact collection, and honest reporting. Use when the user wants to use SkillOpt, optimize a skill with SkillOpt, benchmark prompt variants, run multi-epoch skill optimization, check held-out quality, or diagnose SkillOpt runs.
Run pre-implementation AI consulting engagements—company research, discovery, maturity assessment, opportunity prioritization, and proposal/SOW/roadmap creation—and use only for advisory work, not implementation.
Guide annuity and life-insurance sales workflows—discovery, suitability, product selection, objections, closing, and servicing—when supporting licensed insurance sales conversations or deliverables.
Generate API reference documentation from source code—endpoints, schemas, auth, errors, and examples—when the task is to document an existing API rather than design or implement one.
Turns an approved build spec into a minimal technical implementation plan, including system components, human-in-the-loop boundaries, workflows, and delivery milestones. Use when an internal automation, concierge workflow, or lightweight product has already been chosen and now needs a concrete build plan.
Generate release notes and changelogs from git history with SemVer classification, grouped changes, and migration notes when documenting what changed between versions or refs.
| name | pr-description |
| description | Generate pull-request descriptions from branch diffs when the task is to explain change scope, motivation, testing, risk, and reviewer guidance for a reviewable branch. |
Generate pull request descriptions that tell reviewers WHY something changed, not just WHAT changed. Every PR description includes structured sections for motivation, changes, testing instructions, rollback plan, and reviewer guidance. The goal is a description that lets a reviewer understand, verify, and safely deploy the change without asking follow-up questions.
Do NOT use when:
Always structure the final response with these top-level sections, in this order:
None if nothing remains.Rules:
None when a section does not apply.Before writing anything, understand the complete scope of changes:
main). Use
git diff main...HEAD or equivalent.Output: A mental model of what changed and how the pieces fit together.
This is the most important step. Reviewers need to know WHY before WHAT.
If the motivation isn't obvious from the diff, ask the user. Never guess at motivation — a wrong "why" is worse than no "why."
Use the output template below. Fill every section. If a section genuinely doesn't apply (e.g., no rollback needed for a docs-only change), explicitly state why it's not applicable rather than omitting it.
Testing instructions must be copy-pasteable. A reviewer should be able to follow them step-by-step without interpretation.
Bad: "Test the login flow" Good: "1. Run npm run dev 2. Navigate to
/login 3. Click 'Sign in with Google' 4. Verify redirect to Google OAuth
consent screen 5. After consent, verify redirect back to /dashboard with user
avatar in top-right"
Every production-facing change needs a rollback plan. Include:
git revert <sha>)Help reviewers focus their attention:
Use inline comments in the PR diff for file-specific guidance, and the Reviewer Notes section for cross-cutting concerns.
Structure every PR description as follows:
## Summary
[1-3 sentence overview of what this PR does and why. Lead with the WHY.]
## Motivation
[What problem does this solve? Why is this change needed now? Link to issues or
bug reports. Mention alternatives considered and why they were rejected.]
## Changes
[Organized list of what changed, grouped logically. Not a file-by-file list —
group by concept or feature area.]
- **[Area 1]**: [What changed and why]
- **[Area 2]**: [What changed and why]
- **[Area 3]**: [What changed and why]
## Testing Instructions
[Step-by-step instructions a reviewer can follow to verify the change works.
Commands must be copy-pasteable.]
1. [Setup step if needed]
2. [Action to take]
3. [Expected result]
4. [Edge case to verify]
### Automated Tests
- [List of new or modified tests and what they cover]
## Rollback Plan
[How to revert this change safely. Include exact commands, migration reversal
steps, and data impact assessment.]
## Reviewer Notes
[Areas that need careful review. Security concerns, performance implications,
breaking changes, or areas of uncertainty. Help reviewers focus their
attention.]
- **[File or area]**: [What to look for and why]
Scenario: Branch adding rate limiting to the API gateway.
Input diff summary: 4 files changed — new middleware, config updates, tests, docs.
Output:
## Summary
Adds request rate limiting to the API gateway to prevent abuse and protect
downstream services from traffic spikes. Triggered by the outage on 2026-02-28
where a single client sent 50k requests/minute.
## Motivation
On Feb 28, a misconfigured client script hammered `/api/orders` at 50k req/min,
overwhelming the orders service and causing a 23-minute outage (INC-4521). We
need per-client rate limiting at the gateway level to prevent any single client
from degrading service for others.
Alternatives considered:
- **Application-level rate limiting**: Rejected because each service would need
its own implementation, and the gateway already sees all traffic.
- **CDN-level rate limiting**: Too coarse — we need per-API-key limits, not
per-IP.
## Changes
- **Rate limit middleware** (`src/middleware/rate-limiter.ts`): New sliding
window rate limiter using Redis. Configurable per-route limits with sensible
defaults (1000 req/min for reads, 100 req/min for writes).
- **Configuration** (`config/rate-limits.yaml`): Per-route limit definitions.
Defaults can be overridden per API key via the admin dashboard.
- **Gateway integration** (`src/gateway.ts`): Middleware registered before
routing. Returns 429 with `Retry-After` header when limit exceeded.
- **Tests** (`tests/rate-limiter.test.ts`): 12 new tests covering sliding window
accuracy, Redis failure fallback, and per-key override behavior.
## Testing Instructions
1. Start Redis locally: `docker run -d -p 6379:6379 redis:7-alpine`
2. Run the test suite: `npm test -- --grep "rate-limiter"`
3. Verify all 12 tests pass
4. Start the dev server: `REDIS_URL=redis://localhost:6379 npm run dev`
5. Send 5 rapid requests:
`for i in {1..5}; do curl -s -o /dev/null -w "%{http_code}\n" http://localhost:3000/api/orders; done`
6. Verify all return 200
7. Send 1001 requests rapidly:
`ab -n 1001 -c 10 http://localhost:3000/api/orders`
8. Verify the last requests return 429 with a `Retry-After` header
### Automated Tests
- `rate-limiter.test.ts`: Sliding window counting, Redis connection failure
fallback to in-memory, per-key limit overrides, 429 response format
## Rollback Plan
1. Revert this PR: `git revert <merge-sha>`
2. Deploy the revert — no database migrations to reverse
3. Redis rate limit keys will expire naturally (TTL = window size)
4. No data loss risk — rate limiting is stateless from the application's
perspective
5. If Redis is the issue (not this code), disable rate limiting via env var:
`RATE_LIMIT_ENABLED=false`
## Reviewer Notes
- **`src/middleware/rate-limiter.ts:45-62`**: The sliding window algorithm —
please verify the math on window boundary transitions. I'm using a weighted
overlap approach rather than fixed windows.
- **Redis failure mode** (`rate-limiter.ts:78`): When Redis is unreachable, we
fall back to in-memory limiting. This means limits aren't shared across
instances — acceptable for a degraded mode, but worth discussing.
- **Security**: Rate limit headers expose the client's current usage. Verify
this doesn't leak sensitive information for your use case.
| Mistake | Fix |
|---|---|
| File-by-file change list instead of conceptual grouping | Group changes by feature area or concept, not by filename |
| Missing motivation ("what" without "why") | Always explain the problem being solved and why this approach was chosen |
| Vague testing instructions ("test the feature") | Write copy-pasteable commands with expected outputs for each step |
| No rollback plan | Every production change needs revert steps, migration reversal, and data impact |
| Omitting reviewer guidance | Flag security-sensitive, performance-critical, and uncertain areas explicitly |
| Assuming reviewers have context | Link to issues, explain acronyms, provide background for domain-specific changes |
| Listing every file changed | Summarize conceptually — reviewers can see the file list in the diff |
| No edge case in testing instructions | Include at least one error path or boundary condition to verify |
| Rollback plan says "revert the PR" with no details | Specify exact commands, migration steps, data impact, and dependency considerations |
WHY before WHAT — The motivation section is the most important part of a PR description. A reviewer who understands why a change was made can evaluate whether the approach is correct. A reviewer who only knows what changed can only check for typos. Lead every description with the problem being solved.
Testing instructions must be copy-pasteable — If a reviewer has to interpret, adapt, or guess at your testing instructions, they won't test. Include exact commands, expected outputs, and setup steps. A reviewer should be able to verify the change by copying and pasting from the PR description.
Every change is revertible until proven otherwise — Include a rollback plan for every PR. If the change truly can't be reverted (destructive migration, data format change), say so explicitly and explain the mitigation strategy. "No rollback needed" is almost always wrong.
Guide the reviewer's attention — Reviewers have limited time and attention. Flag the 2-3 areas that matter most: security-sensitive logic, complex algorithms, performance-critical paths, or areas where you're uncertain. Don't make them discover the important parts on their own.
Describe concepts, not files — Group changes by what they accomplish, not which files they touch. "Added rate limiting middleware with Redis-backed sliding windows" is useful. "Changed rate-limiter.ts, gateway.ts, config.yaml" is not — the reviewer can see the file list in the diff.