diff --git a/.agents/skills/fix-issue/SKILL.md b/.agents/skills/fix-issue/SKILL.md new file mode 100644 index 0000000..2fb4396 --- /dev/null +++ b/.agents/skills/fix-issue/SKILL.md @@ -0,0 +1,72 @@ +--- +name: fix-issue +description: Takes a GitHub issue number, fixes the issue in the codebase, creates a branch, opens a pull request that closes the issue, and switches back to main. Use this whenever the user wants an issue resolved end-to-end, e.g. "fix issue 42", "work on #42", or passes a bare issue number to be handled. +--- + +Use this skill when the user gives you a GitHub issue number (e.g. "fix issue 42", "#42", or just "42") and wants it resolved end-to-end: understand the issue, implement the fix, and publish it as a pull request. + +All user-facing output you create — branch name, commit message, PR title and body, code comments, and UI text — must be written in **English**, regardless of the language the user wrote in. + +## Workflow + +### 1. Read and understand the issue + +- Confirm the issue number from the user's request. If no number was given, stop and ask for one. +- Fetch the issue (use `gh issue view --json number,title,body,labels,state,comments` if the GitHub CLI is available; otherwise use the equivalent GitHub MCP tool, e.g. `issue_read`). +- Read the title, body, and comments to understand what is actually being asked. If the issue is already `closed`, stop and report that instead of starting work. +- If the issue is ambiguous, underspecified, or could be solved several materially different ways, ask the user a focused clarifying question before writing code. Do not guess on decisions that are expensive to reverse. + +### 2. Prepare a clean starting point + +- Verify the working tree is clean with `git status --short --branch`. If there are unrelated uncommitted changes, stop and report them — do not bundle them into this fix. +- Make sure you start from an up-to-date base branch (`main` unless the user says otherwise): switch to it and `git pull` so the branch and PR are based on current code. +- Confirm the `origin` remote exists. + +### 3. Create the branch + +- Derive the branch type from the issue labels and content: use `fix/` for bugs, `feat/` for new functionality, `chore/`/`docs/`/`build/` where appropriate. +- Name the branch `/-`, e.g. `fix/42-penalty-type-off-by-one`. If the user supplied a branch name, use theirs. +- Create and switch to the branch from the base branch. + +### 4. Implement the fix + +- Follow the conventions in `AGENTS.md` and `.github/copilot-instructions.md` (and `.github/instructions/csharp.instructions.md` for C# details). In particular: keep controllers thin, keep database access inside repositories, reuse `RepositoryFactory`/`RepositoryBase`, preserve multi-database support, and write all comments and UI text in English. +- Follow the layering in "Common change patterns": core/data/entity types → repositories → services/processors → Web API controllers/hubs (transport only) → observability → tests. For frontend changes: typed models → existing HTTP/SignalR services → feature component state → keep contract names synchronized with the backend `Data`/`ViewData` models. +- Read the surrounding code and match its existing style, naming, and region layout (`#region ... #endregion // ...`). + +### 5. Validate + +- Backend: `dotnet build F1Server.slnx`, then `reihitsu-format --check ` for every changed `.cs` file, then `dotnet test F1Server.Tests` (MSTest). A clean build must show 0 `RH####` warnings. +- Frontend (only if `F1ServerApp` changed): `cd F1ServerApp && npm run build`, and `npm test` if the change affects testable logic. +- If validation fails, fix the cause before continuing — do not push broken code. If you cannot make it pass, stop and report clearly. + +### 6. Commit + +- Stage only the files relevant to this fix. Do not include unrelated changes. +- Write a concise commit message that matches the repo history: subject line max 80 characters, no trailing period, not in the first person, body concise (3-5 sentences) when needed. +- Do not add any `Co-Authored-By` trailer, session link, or other note attributing the work to an AI/assistant. + +### 7. Push and open the pull request + +- Push the branch to `origin` with upstream tracking (`git push -u origin `). +- Open the pull request (use `gh pr create` if available, otherwise the equivalent GitHub MCP tool, e.g. `create_pull_request`): + - base branch: `main`, unless the user requested a different base + - title: concise English summary of the fix + - body: a short English summary of the problem and the fix, following the repository's PR template if one exists, plus a line `Closes #` so the issue auto-closes on merge + - Do not add any attribution, "Generated with" footer, session link, or other note referencing an AI/assistant in the PR title or body. This applies even if a default template, prior example, or tool prefill suggests adding one — this project's rule always wins. + - Before submitting, re-read the final title and body and scan them line by line for "Codex", "OpenAI", "ChatGPT", "Generated with", "Generated by", "Co-Authored-By", `chatgpt.com`, or any session URL. Strip any match before creating the PR. + - After the PR is created, fetch it back (`gh pr view --json body` or the MCP equivalent) and re-scan the *stored* body for the same terms. Some PR-creation tools append an attribution footer of their own regardless of the body you submitted — if that happened, immediately edit the PR to remove it (`gh pr edit` or the MCP equivalent). Do not assume the body you sent is the body that was saved. + +### 8. Finish + +- After the PR is created, switch back to the base branch (`main`). +- Report the issue number, branch name, and pull request URL clearly. + +## Rules + +- Prefer non-interactive commands only. +- If push or PR creation fails, stop and report the failure clearly — do not continue as if it succeeded. +- Do not amend existing commits unless the user explicitly asks. +- If switching back to `main` would discard or conflict with uncommitted work, stop and explain the blocker. +- Never close the issue manually; let `Closes #` in the PR body do it on merge. +- Never run `git commit`, `git push`, or create branches without the user having asked for this issue to be fixed end-to-end — invoking this skill with an issue number is the explicit approval for that specific workflow. diff --git a/.agents/skills/publish-pr/SKILL.md b/.agents/skills/publish-pr/SKILL.md new file mode 100644 index 0000000..e298990 --- /dev/null +++ b/.agents/skills/publish-pr/SKILL.md @@ -0,0 +1,43 @@ +--- +name: publish-pr +description: Creates a branch, commits the current changes, pushes the branch, opens a pull request, and switches back to main. Use this when asked to publish local changes as a pull request. +--- + +Use this skill when the user wants the current local changes published to GitHub as a pull request. + +All user-facing output you create — branch name, commit message, PR title and body — must be written in **English**, regardless of the language the user wrote in. Never mention Codex, OpenAI, ChatGPT, Copilot, or any other AI/assistant tooling in the PR title or body, and do not add any `Co-Authored-By` trailer, "Generated with" footer, session link, or other note attributing the work to an AI. + +## Workflow + +1. Inspect the repository state first with non-interactive Git commands: + - confirm the current branch + - review `git status --short --branch` and `git diff --stat` + - confirm the `origin` remote exists +2. If there are no relevant local changes to publish, stop and say so plainly. +3. Choose or confirm a branch name based on the change. If the user already provided one, use it. Otherwise derive a short kebab-case branch name from the work, prefixed by type where it fits (`fix/`, `feat/`, `chore/`, `docs/`, `build/`). +4. Create and switch to the branch from the current base branch (`main` unless the user says otherwise). +5. Stage only the files intended for this change. Do not include unrelated modifications. +6. Create a non-interactive Git commit with a concise message that matches the repo history: subject line max 80 characters, no trailing period, not in the first person, body concise (3-5 sentences) when needed. Do not add any `Co-Authored-By` trailer or session link. +7. Validate before pushing: + - Backend changes: `dotnet build F1Server.slnx`, `reihitsu-format --check ` for every changed `.cs` file, and `dotnet test F1Server.Tests`. + - Frontend changes (`F1ServerApp`): `cd F1ServerApp && npm run build`, and `npm test` if the change affects testable logic. + - If validation fails, fix the cause before pushing. +8. Push the branch to `origin` with upstream tracking (`git push -u origin `). +9. Open the pull request (use `gh pr create` if the GitHub CLI is available, otherwise the equivalent GitHub MCP tool, e.g. `create_pull_request`): + - base branch: `main`, unless the user explicitly requests a different base + - title: concise English summary of the change + - body: short English summary of what changed, following the repository's PR template if one exists + - Do not add any attribution, "Generated with" footer, session link, or other note referencing an AI/assistant in the PR title or body. This applies even if a default template, prior example, or tool prefill suggests adding one — this project's rule always wins. + - Before submitting, re-read the final title and body and scan them line by line for "Codex", "OpenAI", "ChatGPT", "Generated with", "Generated by", "Co-Authored-By", `chatgpt.com`, or any session URL. Strip any match before creating the PR. + - After the PR is created, fetch it back (`gh pr view --json body` or the MCP equivalent) and re-scan the *stored* body for the same terms. Some PR-creation tools append an attribution footer of their own regardless of the body you submitted — if that happened, immediately edit the PR to remove it (`gh pr edit` or the MCP equivalent). Do not assume the body you sent is the body that was saved. +10. After the pull request is created, switch back to the `main` branch. +11. Report the branch name and pull request URL clearly. + +## Rules + +- Prefer non-interactive commands only. +- Do not amend existing commits unless the user explicitly asks. +- Do not include unrelated modified files in the commit. +- If push or PR creation fails, stop and report the failure clearly instead of continuing as if it succeeded. +- If switching back to `main` would discard or conflict with uncommitted work, stop and explain the blocker. +- Invoking this skill is the explicit user approval for the commit, push, and PR-creation steps it performs — no further confirmation is needed for those specific actions. diff --git a/.agents/skills/rereview-pr/SKILL.md b/.agents/skills/rereview-pr/SKILL.md new file mode 100644 index 0000000..b08daa4 --- /dev/null +++ b/.agents/skills/rereview-pr/SKILL.md @@ -0,0 +1,101 @@ +--- +name: rereview-pr +description: Re-reviews a GitHub pull request after review feedback was addressed, focusing only on what changed since the previous review, without changing any code. Use this whenever the user wants a follow-up look at a PR after fixes were pushed, e.g. "rereview PR 42", "re-review #42 after the fixes", "check if the review comments on 42 were addressed". +--- + +Use this skill when the user gives you a GitHub pull request number and wants it re-reviewed after earlier review feedback (from this skill's `review-pr` sibling, a human reviewer, or GitHub review comments) was supposedly addressed. + +Repository: `LarsLaskowski/F1-Telemetry`. + +This skill is **read-only**, exactly like `review-pr`. Its job is to check whether the previous review's findings were actually resolved and whether the newest commits introduced anything new worth flagging. It must **not** modify any code, commit, push, change the PR, or check out the branch in a way that alters the working tree beyond what is needed to inspect the diff. + +Write all output in **English**: your summary to the user, your recommendations, and — only if the user asks for it — any review comment posted to GitHub. This holds regardless of the language the user wrote in. + +## Scope + +Keep the review narrow. Only evaluate: + +1. Whether each finding from the previous review was actually resolved by the new commits. +2. The code changes made since the previous review (not the whole PR from scratch, unless nothing was reviewed before). +3. Whether the PR description still matches what the diff now does. +4. The status of the CI check (`Build, Test & Analyze`) and the SonarQube Cloud quality gate — at most. + +Anything else about the PR (other checks such as CodeQL or release runs, labels, assignees, unrelated discussion) is out of scope and should not be reported on. + +## Workflow + +### 1. Find the previous review + +- Confirm the PR number from the user's request. If none was given, stop and ask for one. +- Fetch metadata (use `gh pr view --json number,title,body,author,state,baseRefName,headRefName,additions,deletions,changedFiles,comments,reviews` if the GitHub CLI is available; otherwise the equivalent GitHub MCP tool, e.g. `pull_request_read`). +- Find what was reviewed before: + - Look at prior review submissions and review comments (`gh api repos/LarsLaskowski/F1-Telemetry/pulls//reviews` and `.../comments`, or the MCP equivalents `get_reviews` / `get_review_comments`). + - If the user pasted or referenced a previous `review-pr` report in the conversation, use that as the list of findings instead of (or in addition to) GitHub review comments. +- If you cannot find any previous review or findings at all, say so and ask the user whether to proceed as a full `review-pr`-style review instead. + +### 2. Isolate what changed since that review + +- Identify the commit (or timestamp) the previous review was based on — the latest commit reviewed, or the time of the last review submission. +- Fetch the current diff (`gh pr diff `, or the MCP equivalent) and the changed files (`gh pr view --json files`, or the MCP equivalent). +- Where possible, scope your reading to the commits/files touched **since** the previous review point, rather than re-reading the entire PR diff from scratch. Use the full diff only for context when a finding can't be judged from the incremental change alone. +- Fetch the check runs (`gh pr checks `, or the MCP equivalent) and read only the conclusion of the CI check (`Build, Test & Analyze`, which also runs the SonarQube Cloud analysis) and the SonarQube Cloud quality gate. Ignore every other check. + +### 3. Check each previous finding + +For every finding from the previous review: + +- Mark it **Resolved**, **Not resolved**, or **Partially resolved**, with a one-line reason pointing at the relevant `file:line`. +- If a finding was a **Blocking** item and is not resolved, it stays blocking. +- If the fix introduces a new problem (regression, incomplete fix, new edge case), report that as a new finding. + +### 4. Check the description and new code + +- Compare the current PR description to the current diff; if it no longer matches (e.g. the fix changed scope but the description wasn't updated), raise it as a finding. +- Re-run the AI-attribution check from `review-pr` on the current PR title, body, and the commit messages added since the previous review: "Codex", "OpenAI", "ChatGPT", "Claude", "Anthropic", "Copilot", "Generated with", "Generated by", "Co-Authored-By", `chatgpt.com`, `claude.ai`, or a session URL. `AGENTS.md` forbids all of these — report any match as a **Blocking** finding with the exact text to remove. +- Review any newly added or changed code (since the previous review) against the same criteria `review-pr` uses: correctness (bugs, edge cases, null handling, concurrency, async/`.ConfigureAwait(false)`, packet parsing and `ReadOnlySpan` bounds, repository queries, EF Core navigation assumptions, SignalR hub/cache behavior), convention adherence (`AGENTS.md` and `.github/instructions/csharp.instructions.md`, including `RH####` analyzer rules, region/formatting conventions, XML documentation, EF Core migration naming, preserved multi-database support), scope/size, tests (`F1Server.Tests`, `{Class}{Scenario}{ExpectedResult}` naming, MSTest assertions with messages), and clarity. + +### 5. Report findings + +Present the re-review to the user in this structure: + +``` +## Re-review of PR # — + +**Verdict:** <Approve / Approve with comments / Request changes / Needs discussion> + +### Summary +<1–3 sentences on whether the previous feedback was addressed and the PR is now in better shape.> + +**Description match:** <Does the PR description accurately reflect the current diff? Yes/No and why.> +**CI (Build, Test & Analyze):** <Pass / Fail / Not run.> +**SonarQube Cloud:** <Pass / Fail / Warnings / Not run — no other checks.> + +### Previous findings +- **[Resolved|Not resolved|Partially resolved] <file:line>** — <what changed, or why it's still open.> +- ... + +### New findings +- **[Blocking|Suggestion|Nit] <file:line>** — <what and why, with a recommended action.> +- ... + +### Recommendations +<Concrete next steps the author should take.> +``` + +- Reference exact `file:line` locations so findings are easy to act on. +- If everything was resolved and nothing new came up, say so plainly rather than inventing issues. + +### 6. Optional: post a review comment + +- Only post anything to GitHub if the user explicitly asks for it. By default, just report back in the chat. +- If asked, post the review in **English** (use `gh pr review <number> --comment --body "<english text>"` if available, otherwise the equivalent GitHub MCP tool, e.g. `pull_request_review_write`). Use `--approve` or `--request-changes` (or the matching MCP review event) only when the user explicitly chooses that action. +- For line-specific comments, use a pending review and submit it in one go (`gh api` review endpoint with a `comments` array, or the MCP pending-review flow: create a pending review, add comments to it, then submit it). +- Do not add any attribution, "Generated with" footer, or other note referencing an AI/assistant. + +## Rules + +- Never modify code, commit, push, or change the PR contents — this skill only reviews. +- Prefer non-interactive commands only. +- Do not post any comment or review to GitHub unless the user explicitly requests it. +- Base your verdict on evidence from the diff and code; if something is uncertain, say so instead of guessing. +- Stay inside the scope defined above: previous-finding resolution, the changes since the last review, the description-vs-diff match, and the CI/SonarQube Cloud status. Do not comment on other checks, labels, or metadata. diff --git a/.agents/skills/review-pr/SKILL.md b/.agents/skills/review-pr/SKILL.md new file mode 100644 index 0000000..58472d7 --- /dev/null +++ b/.agents/skills/review-pr/SKILL.md @@ -0,0 +1,74 @@ +--- +name: review-pr +description: Reviews a GitHub pull request by number and reports findings and actionable recommendations, without changing any code. Use this whenever the user wants a pull request examined, e.g. "review PR 42", "check #42", or passes a bare PR number for review. Posting a review comment is optional and only happens on explicit request. +--- + +Use this skill when the user gives you a GitHub pull request number (e.g. "review PR 42", "#42", or just "42") and wants it reviewed. + +This skill is **read-only**. Its job is to understand the PR and give the user findings and actionable recommendations. It must **not** modify any code, commit, push, change the PR, or check out the branch in a way that alters the working tree beyond what is needed to inspect the diff. The output is a review, not a fix. + +Write all output in **English**: your summary to the user, your recommendations, and — only if the user asks for it — any review comment posted to GitHub. This holds regardless of the language the user wrote in. + +## Workflow + +### 1. Load the pull request + +- Confirm the PR number from the user's request. If none was given, stop and ask for one. +- Fetch metadata (use `gh pr view <number> --json number,title,body,author,state,baseRefName,headRefName,labels,additions,deletions,changedFiles,comments,reviews` if the GitHub CLI is available; otherwise the equivalent GitHub MCP tool, e.g. `pull_request_read`). +- Fetch the diff (`gh pr diff <number>`, or the MCP equivalent). +- If the PR is already merged or closed, say so and ask whether the user still wants a review before continuing. + +### 2. Understand the intent + +- Read the PR title and body to understand what the change is supposed to do. +- If the PR references an issue (e.g. `Closes #N`), read that issue (`gh issue view <N>` or the MCP equivalent) so you can judge whether the change actually solves the stated problem. + +### 3. Review the diff + +Evaluate the change against what matters for this project. Focus on: + +- **Correctness** — bugs, edge cases, error handling, race conditions, off-by-one and boundary issues. For this codebase pay particular attention to telemetry packet parsing/converters (byte layout, `ReadOnlySpan<byte>` bounds), repository queries, and SignalR hub/cache behavior. +- **Convention adherence** (`AGENTS.md`, `.github/copilot-instructions.md`, `.github/instructions/csharp.instructions.md`) — controllers stay thin, database access stays inside repositories, `RepositoryFactory`/`RepositoryBase` are reused, multi-database support is preserved, naming/region/formatting conventions are followed, `RH####` analyzer rules are not violated, XML documentation is present where required, EF Core migration naming/timestamp rules are respected, and frontend contract names stay synchronized with backend `Data`/`ViewData` models. +- **AI-attribution check** — scan the PR title, body, and commit messages for "Codex", "OpenAI", "ChatGPT", "Claude", "Anthropic", "Copilot", "Generated with", "Generated by", "Co-Authored-By", `chatgpt.com`, `claude.ai`, or a session URL. `AGENTS.md` forbids all of these in PR title/body. Report any match as a **Blocking** finding with the exact text to remove. +- **Scope and size** — unrelated changes bundled in, accidental file inclusions, debug leftovers. +- **Tests and validation** — whether the change is verifiable and whether `dotnet build`, `dotnet test F1Server.Tests`, and (for frontend changes) `npm run build`/`npm test` would plausibly pass. Check that MSTest naming (`{Class}{Scenario}{ExpectedResult}`, no underscores) and assert-message conventions are followed for new tests. +- **Clarity** — naming, dead code, needless complexity, missing or misleading comments. + +Do not run builds that modify files unnecessarily; reading the diff and the surrounding code is usually enough. You may read any file in the repo for context. + +### 4. Report findings + +Present the review to the user in this structure: + +``` +## PR #<number> — <title> + +**Verdict:** <Approve / Approve with comments / Request changes / Needs discussion> + +### Summary +<1-3 sentences on what the PR does and whether it achieves its goal.> + +### Findings +- **[Blocking|Suggestion|Nit] <file:line>** — <what and why, with a recommended action.> +- ... + +### Recommendations +<Concrete next steps the author should take.> +``` + +- Classify each finding as **Blocking** (must fix before merge), **Suggestion** (worth doing), or **Nit** (minor/optional). +- Reference exact `file:line` locations so findings are easy to act on. +- If you find nothing wrong, say so plainly rather than inventing issues. + +### 5. Optional: post a review comment + +- Only post anything to GitHub if the user explicitly asks for it. By default, just report back in the chat. +- If asked, post the review in **English** (use `gh pr review <number> --comment --body "<english text>"` if available, otherwise the equivalent GitHub MCP tool, e.g. `pull_request_review_write`). Use `--approve` or `--request-changes` (or the matching MCP review event) only when the user explicitly chooses that action. +- Do not add any attribution, "Generated with" footer, session link, or other note referencing an AI/assistant. + +## Rules + +- Never modify code, commit, push, or change the PR contents — this skill only reviews. +- Prefer non-interactive commands only. +- Do not post any comment or review to GitHub unless the user explicitly requests it. +- Base your verdict on evidence from the diff and code; if something is uncertain, say so instead of guessing. diff --git a/AGENTS.md b/AGENTS.md index 23dceb5..aa29cc8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,7 +32,8 @@ conventions from `.github/copilot-instructions.md` and `.github/instructions/csh - Do not add a "Validation", "Verification", "Testing", or similar section that lists `reihitsu-format`, `dotnet build`, `dotnet test`, or other build/test commands. Build and tests run automatically as PR checks, so restating them in the description is unnecessary. -- This applies to every PR created for this repository, regardless of how it was opened. +- This applies to every PR created for this repository, whether opened directly or through a + skill (see `fix-issue`, `publish-pr`, `review-pr`, `rereview-pr` in `.agents/skills`). ---