1---
2name: file-pr
3description: File a concise pull request. Use when the user asks to file, open, or create a PR.
4---
5
6# File PR
7
8## Push permission
9
10A request to file a PR, including "full send file pr", authorizes committing,
11pushing this task's branch, and the branch updates described here without
12asking again. This grant replaces general ask-first rules for these actions;
13it does not bypass harness approvals or branch protection. `full-send` and
14`full-stop` use this same policy.
15
16Before rewriting a published PR branch, check the live draft status and its
17ready-for-review history. For a draft PR that has never been marked ready for
18review, rebase as needed and automatically push with `--force-with-lease`.
19Never use plain `--force` or overwrite someone else's unexpected changes.
20
21Once a PR has been marked ready for review, preserve its published history,
22even if it later returns to draft. Use follow-up commits for fixes and merge
23the target branch when an update is needed. Rewriting that history requires
24explicit user authorization. If review history cannot be established, preserve
25published history. This permission covers only this task's branch, never the
26default branch or unrelated branches.
27
28## Filing
29
30Before filing, check whether a PR for this branch already exists. Review the
31diff locally against the base branch (usually `origin/main`) to make sure its
32contents match the goal.
33
34Write like a developer leaving a short note for teammates who know the project:
35direct, conversational, and matter-of-fact. Name the change and keep useful
36specifics. Cut ceremony ("This PR introduces..."), sales language, and a tour
37of the diff. Keep technical terms when they are the clearest way to say it.
38
39PR titles usually become commit messages. Aim for 50 characters or fewer,
40including any prefix and scope. Follow required repository conventions; use
41a scope only when the project requires one. Learn the tone of user-endorsed
42writing; a merge alone does not make a PR a style reference.
43
44Each row below rewrites the same change. Use the examples to learn the voice,
45then write fresh wording from the actual diff. Preserve the facts; shortening
46a title must not broaden its claim or invent a benefit. The scoped pair
47assumes a project that requires scopes.
48
49| Before | After |
50| --- | --- |
51| `fix: improve retry handling to prevent duplicate sends` | `fix: stop retries from sending messages twice` |
52| `feat: persist and hydrate open-tab state across app launches` | `feat: restore open tabs on launch` |
53| `feat: unlock seamless note sharing with public links` | `feat: share notes with a public link` |
54| `refactor: extract a common parser module for the CLI and worker` | `refactor: share the CLI and worker parser` |
55| `perf: implement incremental file indexing using modification timestamps` | `perf: skip unchanged files when indexing` |
56| `fix(sync): preserve the pending upload queue when the application restarts` | `fix(sync): keep pending uploads after restart` |
57
58Descriptions usually need one or two sentences. For a bug, give the symptom
59and the changed behavior; for a feature, say what it lets someone do. For
60internal work, say what changes and why. Keep a technical detail, measured
61result, or validation when it helps the reviewer assess the change. No file
62lists, section headings, or routine test plans.
63
64| Before | After |
65| --- | --- |
66| This PR fixes out-of-order search responses by introducing a monotonically increasing request counter and dropping payloads whose counter no longer matches the hook state. | An older search could finish last and replace the results for your current query. Responses for older queries are now ignored. |
67| This PR introduces a powerful new capability that enables users to generate a public URL for a note and distribute it to external recipients without requiring them to authenticate. | You can share a note with a public link. Anyone with the link can read it without signing in. |
68| Extracted a shared parser package, replaced the separate parsing utilities in the CLI and worker, and updated both callers so a syntax fix no longer needs two implementations. | The CLI and worker now use the same parser, so syntax fixes only need to happen once. |
69
70End the description with one trailer line per model that wrote part of the
71change, in the form `Assisted-by: <model>` (`claude-opus-5.5`, `gpt-6.1-sol`).
72Use the model ID the harness reports, never `Co-authored-by`, and never guess:
73if the model is unavailable, name the harness. Put `Assisted-by: chatgpt-dot:lilac`
74last when the task came from a Lilac agent or mentions "ChatGPT Dot".
75
76Before submission, check the title, description, quotes, and attachments for
77secrets and private details.
78
79Open a real PR rather than a draft so review bots run. If `gh pr create` fails
80because the GraphQL rate limit is used up, open it through REST with
81`gh api repos/<owner>/<repo>/pulls -f title=... -f head=... -f base=... -F body=@<file>`.
82If the user also asked to babysit it, continue with the `babysit-pr` skill.
83
84Do not post a follow-up PR comment unless it serves the user's request. When a
85comment is needed, use the `leaving-pr-comments` skill.