메뉴
Use when creating a pull request, writing a PR description, or preparing changes for code review. Ensures PR descriptions include structured summary, background context, test plan, and rollback plan.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | pull-request-description |
| description | Use when creating a pull request, writing a PR description, or preparing changes for code review. Ensures PR descriptions include structured summary, background context, test plan, and rollback plan. |
| author | Gerald Onyango <gerald.onyango@gmail.com> |
Write PR descriptions that give reviewers everything they need to understand what changed, why it changed, how it was tested, and how to roll back if something goes wrong. A good PR description is a decision document, not a changelog.
## Summary
<1-3 bullet points: what changed and why, at a high level>
Refs [JIRA-KEY](https://zombie.atlassian.net/browse/JIRA-KEY)
<!-- or: Closes JIRA-KEY / Fixes JIRA-KEY -->
## Background
### Context
<What does the reader need to know to understand this change? Domain concepts, how the system works today, relevant data model relationships. Assume the reviewer is smart but unfamiliar with this specific area.>
### The problem
<What is broken, missing, or suboptimal? Be specific - include symptoms, affected users/flows, and severity. Reference logs, errors, or screenshots if available.>
### The fix
<What approach did you take and WHY this approach over alternatives? If there were trade-offs, state them. If you considered and rejected other approaches, briefly explain why.>
### Pre-existing fixes (if any)
<Document any opportunistic fixes to existing code found during this work - e.g., N+1 queries, dead code, minor bugs in adjacent code. Explain why the fix is safe.>
## Test plan
- [ ] <Automated tests: what was added/modified, count of new specs>
- [ ] <Key scenarios covered: happy path, edge cases, error cases>
- [ ] <Manual verification steps if applicable>
## Rollback plan
<How to undo this change if it causes problems in production.>
<!-- For most changes: -->
Revert this PR.
<!-- For changes with side effects, be specific: -->
<!-- Examples of when a simple revert is NOT sufficient: -->
<!-- - DB migrations: "Revert PR, then run `rails db:rollback STEP=1` to undo the migration" -->
<!-- - Data backfills: "Revert PR. Run `rake data:undo_backfill_xyz` to restore previous values" -->
<!-- - External integrations: "Revert PR. Disable webhook in [service] dashboard" -->
<!-- - Feature flags: "Disable flag `xyz` in LaunchDarkly before reverting" -->
<!-- - Cache/queue changes: "Flush cache key `xyz` after reverting" -->
Summary is not a diff. Summarize the intent, not the file list. "Fixes carried-over finding review status not restoring on re-validation" beats "Adds RestoreCarriedOver interactor and specs."
Background teaches. A reviewer who has never seen this code should understand the domain after reading Background. Define terms. Explain relationships. Use short code snippets or diagrams if they clarify.
Explain the "why" of your approach. Don't just describe what you did - explain why you chose this solution. If you rejected alternatives, say so briefly.
Link the issue. Always include a reference to the Jira ticket (or GitHub issue) driving the work. Use Refs JIRA-KEY for related work, Closes JIRA-KEY for direct fixes.
Test plan is a checklist. Use - [ ] checkboxes. Separate automated tests (specs) from manual verification. Include count of new/modified specs.
Rollback plan is mandatory. Default is "Revert this PR." But if the change includes DB migrations, data backfills, external service changes, feature flags, or cache/queue modifications, document the full rollback procedure.
Pre-existing fixes get their own section. If you fixed something unrelated while working (N+1 query, dead code, minor bug), call it out explicitly so reviewers know it's intentional and can review it separately.
Keep it scannable. Use headers, bullets, code blocks, and tables. Avoid walls of text. A reviewer should be able to skim headers and understand the PR in 30 seconds, then dive deep where needed.
| Change type | Rollback | Notes |
|---|---|---|
| Code-only (no side effects) | Revert PR | Default case |
| Additive DB migration (add column/table) | Revert PR + rollback migration | New column/table is unused after revert |
| Destructive DB migration (remove/rename column) | Cannot simply revert | Must write forward migration to restore; plan carefully before merging |
| Data backfill / data mutation | Revert PR + run undo script | Document the undo script or SQL in the rollback plan |
| External webhook / integration | Revert PR + disable in external service | Note the service and dashboard URL |
| Feature flag gated | Disable flag first, then revert | Flag must be disabled before code revert |
| Cache schema change | Revert PR + flush affected keys | Note specific cache keys or patterns |
| Queue/job format change | Drain queue first, then revert | Old code can't process new-format jobs |
Changelog-style summary: "Updated file X, added method Y, modified test Z." Instead: explain the user-facing or system-level impact.
Missing domain context: Jumping straight into the fix without explaining how the system works. Reviewers shouldn't need to read 5 files to understand your PR.
"Tests pass" as a test plan: List what is tested, not just that tests exist. "33 new specs covering happy path, edge cases, and no-op scenarios" is useful. "Tests pass" is not.
No rollback plan: Every PR should state how to undo it. "Revert this PR" is fine for most changes, but say it explicitly.
Burying the approach rationale: If you chose approach A over B, say why up front. Don't make reviewers guess or ask in comments.
Use when writing or modifying any Ruby code in cobalt repos. Enforces structured logging via SemanticLogger + Datadog so logs are queryable, dashboardable, and debuggable. Triggers on new interactors, jobs, services, controllers, error handling, and any business logic that should be observable.
Create, edit, and review Datadog dashboard JSON so every widget actually renders the data the user wants — not merely valid JSON. Enforces three gates: (1) valid JSON structure, (2) every query verified against LIVE data, (3) each section verified to answer its intended question. Use when building a Datadog dashboard, reviewing or importing/exporting dashboard JSON, writing dashboard queries (query_value, timeseries, toplist, query_table, list_stream), adding rates or denominators, or debugging why a tile shows "No data", a blank cell, or a wrong number. Triggers include "datadog dashboard", "dashboard JSON", "review this dashboard", "build/create a dashboard", "widget shows no data", "why is this tile empty", "does this query return data".
Deep strategic analysis of meetings from Krisp transcripts. Acts as a second brain — surfaces insights, subtext, commitments, risks, and recommendations the user might miss. Use when: user asks to debrief a meeting, analyze a call, review a conversation, pull insights from a meeting, wants meeting notes or analysis, says 'debrief', 'second brain', 'what did I miss', 'meeting insights', or references a recent call they want analyzed. Works with any meeting type: 1:1s, group syncs, strategy sessions, standups, skip-levels.
Generate a concise team status report for an engineering manager before calls or check-ins. Covers progress, blockers, risks, individual workloads, PRs in flight, meeting context, and project health assessments. Default scope is the Delivery Domain (DL) team over the last 1.2 weeks. Use when the user says "team pulse", "team status", "what's my team working on", "prep me for standup", "what happened this week", "sprint update", "team report", "how is [project] going", "how is [person] doing", "prep me for 1:1", or any request for a team/project/person activity summary.
Use when encountering any bug, test failure, performance regression, or unexpected behavior, before proposing fixes
A relentless interview to sharpen a plan or design.