|
| 1 | +--- |
| 2 | +name: write-pr |
| 3 | +description: Use when creating a pull request in the pythinker-code repository — how to fill in each section of the PR template with concise, reviewer-friendly content. |
| 4 | +--- |
| 5 | + |
| 6 | +# Write PR Description |
| 7 | + |
| 8 | +Create or update the pull request for the current branch with a description that helps the reviewer understand why the change exists and the shape of the implementation. |
| 9 | + |
| 10 | +## Workflow |
| 11 | + |
| 12 | +1. Read the PR template: |
| 13 | + |
| 14 | + `Read(.github/pull_request_template.md)` |
| 15 | + |
| 16 | +2. Identify or create the pull request: |
| 17 | + - Check the current branch for an existing PR: `gh pr view --json url,number,title,state 2>/dev/null`. |
| 18 | + - If no PR exists, inspect `git status --short --branch` and the commits on the current branch. |
| 19 | + - Commit remaining changes, push the branch with an upstream, and create the PR with `gh pr create`. |
| 20 | + - Follow the repository's git safety protocol. |
| 21 | + |
| 22 | +3. Gather the context needed to explain the change: |
| 23 | + - Read the linked issue and any relevant task artifacts. |
| 24 | + - Read the complete diff (`git diff main...HEAD`) and enough surrounding code to understand behavior and ownership. |
| 25 | + - Use `gh pr view` to collect PR metadata and changed files if the PR already exists. |
| 26 | + |
| 27 | +4. Write the PR description following the template sections: |
| 28 | + - **Requirement or Bug** — one sentence or `Resolve #<number>`. Nothing more. |
| 29 | + - **Bug Reproduction Steps** — bug PRs only; `N/A` for features. Write `See linked issue` when steps are already there. |
| 30 | + - **Root Cause** — bug PRs only; `N/A` for features. State the cause and whether this is a fundamental fix or a workaround. |
| 31 | + - **Code Changes** — use visual outline views (see below) instead of prose whenever they explain the change better. |
| 32 | + - **Impact Scope** — list affected modules and test coverage. |
| 33 | + - **Checklist** — check every box that applies. |
| 34 | + |
| 35 | +5. Publish the description: |
| 36 | + - Save to a temp file, then `gh pr edit <number> --body-file <path>` or `gh pr create --body-file <path>`. |
| 37 | + - Confirm the update succeeded. |
| 38 | + |
| 39 | +## Visual Outline for Code Changes |
| 40 | + |
| 41 | +Prefer structural views over prose. Use the smallest combination that explains the implementation. Omit categories that did not change. |
| 42 | + |
| 43 | +Show logic or algorithm changes as pseudocode diff: |
| 44 | + |
| 45 | +```diff |
| 46 | + on(save) |
| 47 | +- write content |
| 48 | ++ if content is unchanged |
| 49 | ++ return cached result |
| 50 | ++ write new content |
| 51 | ++ invalidate cache |
| 52 | +``` |
| 53 | + |
| 54 | +Show runtime control flow as a call tree diff: |
| 55 | + |
| 56 | +```diff |
| 57 | + submitForm |
| 58 | + createSession |
| 59 | + persistPrompt |
| 60 | ++ expandSkillMention |
| 61 | + launchAgent |
| 62 | +- navigateToSession |
| 63 | ++ navigateToSession |
| 64 | ++ subscribeToEvents |
| 65 | +``` |
| 66 | + |
| 67 | +Show file responsibility changes as a shallow file tree diff: |
| 68 | + |
| 69 | +```diff |
| 70 | + src/ |
| 71 | + ├── commands/ |
| 72 | ++│ └── show-me.ts # expands the slash command |
| 73 | + ├── sessions/ |
| 74 | +-└── transport.ts |
| 75 | ++└── transport/ |
| 76 | ++ ├── client.ts |
| 77 | ++ └── stream.ts |
| 78 | +``` |
| 79 | + |
| 80 | +Show component or UI structure changes as a tree diff: |
| 81 | + |
| 82 | +```diff |
| 83 | + <SessionPage> |
| 84 | + useSessionEvents() |
| 85 | + <SessionToolbar> |
| 86 | ++ <RunSkillButton /> |
| 87 | + <SessionTimeline> |
| 88 | ++ <SkillResultCard /> |
| 89 | +``` |
| 90 | + |
| 91 | +Show component interaction, control flow, or data flow with Mermaid (especially useful for explaining bug mechanics): |
| 92 | + |
| 93 | +```mermaid |
| 94 | +sequenceDiagram |
| 95 | + participant User |
| 96 | + participant UI |
| 97 | + participant Daemon |
| 98 | + User->>UI: choose command |
| 99 | + UI->>Daemon: send expanded prompt |
| 100 | + Daemon-->>UI: stream result |
| 101 | +``` |
| 102 | + |
| 103 | +Show key data structure or type changes in a language-specific block: |
| 104 | + |
| 105 | +```ts |
| 106 | +interface SessionEvents { |
| 107 | + onTurnStart(cb: (turn: Turn) => void): void; |
| 108 | + onTurnEnd(cb: (turn: Turn) => void): void; |
| 109 | +} |
| 110 | +``` |
| 111 | + |
| 112 | +Rules for visual outlines: |
| 113 | +- Use `diff` blocks when the point is what changes and the surrounding shape already exists. |
| 114 | +- Show the complete target shape in a language-specific or `text` block when most of it is new or diff notation would obscure ownership or order. |
| 115 | +- Tell the story in the order that makes it easiest to understand — files first, or data structures first, whichever fits. |
| 116 | +- Write as one human talking to another: simple, coherent, concise language. |
0 commit comments