--- name: subtitleedit-ai-contributor-guidelines description: "Use when: using AI coding agents or LLM assistance for Subtitle Edit code changes, reviews, refactors, tests, or documentation updates. Provides project-specific safeguards against broad, overcomplicated, or unverified changes." license: MIT --- # Subtitle Edit AI Contributor Guidelines AI-assisted contributions are becoming a normal part of open source development. This guidance gives AI tools, and contributors who use them, a shared quality bar for Subtitle Edit. The goal is not to ban AI use, but to reduce the avoidable damage that default LLM behavior can cause: wrong assumptions, broad edits, overbuilt abstractions, and unverified pull requests. These instructions apply to code changes, reviews, refactors, tests, documentation, build scripts, packaging files, and translation-related work in this repository. ## 1. Clarify Before Changing Before editing, identify the requested outcome, affected area, and verification path. - If the issue can mean more than one thing, state the interpretations and ask for clarification before implementing. - If a requested change conflicts with existing behavior, project conventions, privacy expectations, or platform support, call that out. - Prefer the smallest change that fully solves the stated problem. - Do not infer new product behavior, UI redesigns, settings, or compatibility promises from a vague request. ## 2. Keep Changes Surgical Every changed line should be traceable to the request. - Do not reformat unrelated files, reorder unrelated code, rename existing symbols, or modernize adjacent code unless it is required for the task. - Match the local style of the file being edited, even when another style would also be valid. - Preserve existing comments, translations, resource keys, subtitle format behavior, and platform-specific code unless the task directly requires changing them. - If you find unrelated dead code or a possible bug, mention it in the PR notes instead of fixing it in the same change. - Remove only the unused imports, variables, helpers, or files made unused by your own change. ## 3. Prefer Boring Code Subtitle Edit has a large feature surface and many file-format edge cases. Avoid cleverness that makes future maintenance harder. - Use existing helpers, patterns, forms, services, and test utilities before introducing new abstractions. - Do not add configurability, extension points, dependencies, caches, background tasks, or generic frameworks unless the issue clearly needs them. - Keep UI changes consistent with existing workflows. Do not redesign screens as part of a bug fix. - Keep parsing, conversion, timing, encoding, and localization changes narrow and explicit. - For subtitle format handling, protect backwards compatibility unless the issue is specifically about changing compatibility behavior. ## 4. Verify The Actual Risk Define verification before implementation, then run the most relevant check that is practical. - For bug fixes, prefer a focused regression test that fails before the fix and passes after it. - For shared parsing, conversion, timing, waveform, OCR, translation, or export behavior, run targeted tests and expand coverage when risk is broad. - For UI-only changes where automated tests are not practical, document the manual verification path. - If a command cannot be run locally, say so in the PR and explain the remaining risk. - Do not claim a change is verified unless the relevant command or manual check was actually performed. ## 5. Protect User Data And Offline Expectations Subtitle Edit is an offline editor by default. Keep that trust boundary intact. - Do not introduce telemetry, analytics, remote logging, model training, or network calls unless explicitly requested and reviewed. - Be careful with subtitle text, media paths, and user-provided content in logs, exceptions, screenshots, or test artifacts. - Keep optional third-party service integrations explicit and isolated. ## 6. Write Useful PR Notes AI-assisted PRs should make maintainer review easier, not harder. - Explain what changed and why. - List the verification performed. - Mention assumptions, tradeoffs, and known limitations. - Keep generated descriptions factual and concise. - Do not hide that AI assistance was used if the contribution was materially AI-assisted. ## 7. Follow The AI Pull Request Gate When an AI agent owns a change from implementation to merge, it must use the full branch, PR, review, and merge workflow instead of committing directly to `main`. - Create a dedicated branch for the change and open a pull request into `main`. - Request a GitHub Copilot review and wait for it to finish before treating the PR as merge-ready. - Read Copilot's comments critically. Fix findings that identify a real bug, regression risk, missing test, unclear behavior, or maintainability problem, then rerun the relevant verification. - If a Copilot comment is not applicable, explain that decision briefly in the PR discussion instead of silently ignoring it. - Resolve review threads after addressing them or after documenting why no code change is needed. - Request another Copilot review after meaningful follow-up changes, and repeat loop "request review --> fix --> request revie --> fix" until Copilot has no comments about possible code issues. - Merge to `main` only after the PR is verified, Copilot review is complete, all useful findings are handled, and review threads are resolved. - As AI you have to be patient. Copilot review takes sometimes 5 to 10 minutes. No possible code issues found by copilot have following comment: "Copilot reviewed x out of x changed files in this pull request and generated no new comments." This is a sign that merge to main might be done. ## Attribution This is an original, project-specific adaptation inspired by `forrestchang/andrej-karpathy-skills` and Andrej Karpathy's public observations about common LLM coding failure modes. Source inspiration: https://github.com/forrestchang/andrej-karpathy-skills The source repository declares MIT licensing in its README and skill metadata. This file is not a vendored copy of the source text; keep this attribution if the guidance is moved or expanded.