| name | issue-pr-revision-authoring |
| description | Write implementation-ready GitHub issues, engineering-report PR bodies, and current-head revision comments without importing repo-specific policy. |
| version | 1.0.0 |
| license | MIT |
| metadata | {"tags":["github","issue-authoring","pull-requests","revision-comments","engineering-reports"]} |
Issue / PR / Revision Authoring
Use this skill when drafting or revising GitHub issues, pull request bodies, or review-response comments. The goal is execution-design authoring: enough concrete contract, evidence, and verification detail for an implementer or reviewer to proceed without a separate meeting.
This skill standardizes writing quality only; it does not define branch protection, reviewer bots, merge gates, deployment policy, webhook behavior, or profile authority semantics.
Choose the smallest useful structure
Use the smallest section set that makes the work executable and reviewable. Add paths, commands, examples, acceptance criteria, and evidence whenever they prevent ambiguity.
Issue authoring modes
1. Execution-design issue
Use when implementation should be possible directly from the issue. Include: summary/motivation, observed problem, proposed solution, CLI/API/UX examples, likely files or surfaces, dependencies/configuration, security/performance/compatibility considerations, non-goals, acceptance criteria, and verification plan.
2. Current-state tracker issue
Use when work is partially implemented and the issue tracks remaining gaps. Include: current status summary, feature/surface table, completed vs remaining work, architecture or surface map, acceptance criteria with status, and available evidence.
3. Evidence-driven investigation issue
Use for performance, correctness, production behavior, or uncertain root cause work where implementation should not start from guesses. Include: environment, measurements/reproduction evidence, observations separated from hypotheses, suggested investigations, reproduction commands, and related issues/PRs/docs.
PR body authoring
A PR body is an engineering report, not a changelog. Explain final behavior, linked issue/close intent, problem and defect split, changes by file/surface, design decisions and rejected alternatives, tests, exact verification commands, acceptance status, and remaining risks or follow-up. Use templates/pr-body.md; use Refs #N instead of Closes #N for partial work.
Revision comment authoring
A revision comment should be current-head, feedback-addressing, and evidence-bearing. Do not merely say “fixed.” Include current head SHA, intent, findings addressed, changed files/surfaces, tests/verification, docs/release-note impact, remaining items, and ready-for-review statement. If a repository requires a review trigger phrase, follow that repository's workflow; do not bake a specific bot name or trigger phrase into this generic template.
Genericity boundaries
Keep these layers out unless a downstream repo adds them in its own workflow docs:
- reviewer bot names or trigger phrases;
- branch protection, rulesets, merge gates, or deployment rules;
- GitHub App internals, webhook behavior, or CI rerun mechanics;
- organization-specific authority or chat-lane policy;
- product-specific reusable code identifiers.
Bundled templates
templates/issue.md — execution-design, current-state tracker, and evidence-driven investigation issue sections.templates/pr-body.md — engineering-report PR body sections.templates/revision-comment.md — current-head review-response/finalization comment.
