github contributor

Engineering Community

Skill notes

Phase 0 — When to use this skill

Use this skill when all of these are true: You are contributing to a repo you do not maintain (the maintainer can close your PR without explanation). The work touches one or more of: source code, tests, docs, build config. You want the PR merged, not just submitted. Do not use this for: your own repos, internal team PRs with shared context, hot-fix branches where a maintainer is waiting on you, or trivial single-line changes (one comment is enough).

Phase 1 — Pre-PR Discovery

The most common reason PRs get closed is a mismatch between what the contributor assumes is acceptable and what the maintainer has already written down. Solve this before writing code.

Step 1.1 — Read CONTRIBUTING.md as a hard contract

CONTRIBUTING.md is not style advice. Treat every numbered rule as a precondition for merge. Pay special attention to: AI-assisted contribution clauses. Many projects added these in 2024-2026 after the AI PR wave. Typical phrasing: "AI-generated PRs without prior discussion may be closed", "you must be able to explain every line", "one issue, one PR". If this clause exists, you owe the project explicit disclosure (see Phase 4) and you must keep the PR small.

Step 1.2 — Sanity-check your PR size against the project's baseline

A "small PR" is relative. Before opening a PR, run: This tells you the project's actual merged-PR size distribution. If your PR is 5–10× larger than the biggest recent merge, that is a red signal — split before submitting. See references/phase1_discovery.md for the baseline rubric and split heuristics.

Step 1.3 — Write a one-paragraph scope contract before coding

A scope contract is a single paragraph you write to yourself before opening your editor: Goal: <one sentence>. In scope: <bullet list, 3–5 items>. Explicitly out of scope: <bullet list — be specific about what you will resist adding when it's tempting>. Then, every time you make an edit, ask: "Is this in scope?" If you find yourself "while I'm in here…"-ing, stop and revisit the contract. Scope creep is the single biggest source of close-without-merge — see references/phase2_implementation.md for the scope-discipline section.

Fluxly profile Runtime and permissions are inferred by Fluxly static checks, not author declarations or runtime test results.
Domain
Engineering
Author-declared agents
No explicit declaration found; this is not inferred or tested compatibility
Static check
88 / 100 · heuristic scan, not runtime safety proof
Runtime evidence
Not run; no isolated runtime test evidence is currently recorded
Author / version / license
@daymade · no license declared
Token usage
Moderate
Setup complexity
Guided setup
External API key
Not required
Operating systems
macOS
Runtime requirements
No explicit requirements detected
Detected file/system behavior
  • Read-only
  • Write / modify
Network behavior
External requests
Install commands
None (reference only)

Heads up: Tool permissions are not declared; actual access depends on the runtime.

01
Phase 0 — When to use this skill

Use this skill when all of these are true: You are contributing to a repo you do not maintain (the maintainer can close your PR without explanation). The work touches one or more of: source code, tests, docs, build config. You want the PR merged, not just submitted. Do not use this for: your own repos, internal team PRs with shared context, hot-fix branches where a maintainer is waiting on you, or trivial single-line changes (one comment is enough).

02
Phase 1 — Pre-PR Discovery

The most common reason PRs get closed is a mismatch between what the contributor assumes is acceptable and what the maintainer has already written down. Solve this before writing code.

03
Step 1.1 — Read CONTRIBUTING.md as a hard contract

CONTRIBUTING.md is not style advice. Treat every numbered rule as a precondition for merge. Pay special attention to: AI-assisted contribution clauses. Many projects added these in 2024-2026 after the AI PR wave. Typical phrasing: "AI-generated PRs without prior discussion may be closed", "you must be able to explain every line", "one issue, one PR". If this clause exists, you owe the project explicit disclosure (see Phase 4) and you must keep the PR small.

04
Step 1.2 — Sanity-check your PR size against the project's baseline

A "small PR" is relative. Before opening a PR, run: This tells you the project's actual merged-PR size distribution. If your PR is 5–10× larger than the biggest recent merge, that is a red signal — split before submitting. See `references/phase1_discovery.md` for the baseline rubric and split heuristics.

05
Step 1.3 — Write a one-paragraph scope contract before coding

A scope contract is a single paragraph you write to yourself before opening your editor: Goal: <one sentence>. In scope: <bullet list, 3–5 items>. Explicitly out of scope: <bullet list — be specific about what you will resist adding when it's tempting>. Then, every time you make an edit, ask: "Is this in scope?" If you find yourself "while I'm in here…"-ing, stop and revisit the contract. Scope creep is the single biggest source of close-without-merge — see `references/phase2_implementation.md` for the scope-discipline section.

06
Phase 2 — Implementation

Phase 2 — Implementation

07
Step 2.1 — Branch off main immediately after fetching upstream

Always branch from upstream `main` (or the project's default branch), never from your fork's `main`, which may be stale.

08
Step 2.2 — Make the smallest diff that solves the problem

Resist any change that is not directly required by your scope contract. In particular: Do not "while I'm here" refactor surrounding code. Do not reformat lines you didn't touch (your formatter may differ from the project's, even if both say "Prettier"). Do not rename variables for clarity unless the renaming is the fix. If a follow-up improvement is genuinely valuable, file a separate issue or open a separate PR after this one is merged.

09
Step 2.3 — Conventional Commits, one logical change per commit

Use Conventional Commits: `<type>(<scope>): <description>` where type is `feat | fix | docs | refactor | test | chore | ci | perf`. Each commit should be reviewable on its own. When a review prompts a fix, use `git commit --fixup=<sha>` and squash with `git -c sequence.editor=: rebase -i --autosquash origin/main` before pushing — see `references/phase2_implementation.md` for the full fixup workflow.

10
Phase 3 — Quality Gates

Maintainers' trust is built by evidence, not by claims. The point of this phase is to produce evidence you can paste into the PR.

11
Step 3.1 — Run the project's full lint + test suite locally

Read the exact commands from CONTRIBUTING.md. Typical examples (use what your project specifies): If any check fails, fix it before continuing. Do not push a PR with red local checks expecting CI to clarify — that wastes maintainer time.

12
Step 3.2 — For GUI / desktop apps: run real end-to-end with isolation

For Tauri/Electron/Cocoa apps you almost certainly cannot use `pnpm dev` directly without contaminating your real installation. The pattern is isolate the data directory first, then run the real binary: Find the project's test-isolation hook (often `XXX_TEST_HOME`, `XXX_DATA_DIR`, or a config flag in `config.rs` / `paths.go`). Point it at `/tmp/<app-name>-e2e/` before launching. Trigger the feature through whatever real surface the user would (URL scheme, CLI arg, deeplink).

13
Step 3.3 — Self-audit: did you actually do what you're about to claim?

Before writing the PR description, list every "I tested…" / "I verified…" / "I ran…" statement you intend to make. For each one, ask: "What's my evidence?" If the answer is "I think I did" or "it should work", you have not actually done it. Write only what you can defend. This rule prevents the most damaging trust failure: a maintainer running your "tested" command and finding it doesn't work.

14
Step 3.4 — Push-time verification

Local tests passing is not the finish line. Before you call the PR merge-ready, run the push-time checklist: Visibility check — confirm the target repo is actually public/private as you assume: Security hooks — if pre-push fails, fix the rule or the content; do not `--no-verify`. Push succeeds — if it fails with 503/auth errors, check `git config --global --get-regexp url` for stale URL rewrites. Mergeability check — `git push` succeeding does not mean GitHub can merge:

15
Phase 4 — PR Description Writing

A great PR description does three jobs: (1) lets the maintainer decide in 30 seconds whether to merge, (2) gives reviewers everything they need to verify without DM'ing you, (3) creates a written record that survives team turnover.

16
Step 4.1 — Structure

Use this skeleton. Detailed templates and a test-coverage-matrix example are in `references/phase4_pr_description.md` and `references/communication_templates.md`.

17
Step 4.2 — Test coverage matrix (for non-trivial changes)

When you've added more than 2 tests, present them as a table mapping each test to the behavior it locks in. This makes review much faster than reading test code:

18
Step 4.3 — Screenshots without polluting the repo

`gh` CLI does not support image attachments to PRs (the underlying upload API at `uploads.github.com` is browser-only and rejects PAT tokens). Three workable approaches: Preferred — let the user drag images in the GitHub web UI. Leave clearly marked placeholders in your PR body draft (e.g. `[SCREENSHOT_1_PLACEHOLDER]`). When the user edits the PR on github.com, they drag images into the markdown, GitHub uploads them to `user-images.githubusercontent.com`, and the placeholders are replaced. Zero pollution.

19
Step 4.4 — AI-Assisted Disclosure (when CONTRIBUTING.md or maintainer norms call for it)

If the project's CONTRIBUTING.md mentions AI-assisted PRs, or the maintainer has commented skeptically about AI output on past PRs, add a short disclosure at the bottom of the PR body. Be specific about what you did, not vague reassurances. The disclosure is not magic — it doesn't excuse a bad PR. But missing it on a project that asks for it is an instant trust hit.

20
Phase 5 — Post-Submission

Phase 5 — Post-Submission

21
Step 5.1 — Respond to automated bot reviews explicitly

Modern projects use Codex, Claude bot, CodeRabbit, etc. for first-pass review. Their comments appear as review comments on specific lines, not as PR-level comments. Reply to each finding directly (so maintainers see the resolution next to the finding), citing the commit hash and the function/test that resolves it: `<finding_comment_id>` is the numeric ID from the comment's URL (`#discussion_rXXXXXXXX`). Full bot-reply workflow in `references/phase5_post_submission.md`.

22
Step 5.2 — Rebase against upstream main without losing review history

When upstream `main` advances and your PR conflicts: Use `--force-with-lease`, never plain `--force`. The `lease` variant aborts if someone else (or a bot) pushed to your branch in between, which prevents you from silently destroying review threads. If you applied a small post-review cleanup (a `--fixup` commit), squash it into the relevant commit with autosquash so the merged history stays clean. See `references/phase2_implementation.md` for the full sequence.

23
Step 5.3 — When sub-agent / counter-review surfaces "findings", filter before responding

If you run a counter-review agent (or a maintainer's bot floods you with 20+ findings), don't paste them all into the PR. For each finding ask three questions: Filter · Discard if Probability · "Could this actually happen in this codebase?" → No Cost · "Would fixing it cost more than the risk?" → Yes Scenario · "Is this scenario already prevented upstream?" → Yes

Discussion

Powered by GitHub Discussions. Sign in with GitHub to comment, react, or subscribe.