Resolve Issue

Constraints

• Apply @rules/php/core-standards.mdc
• Apply @rules/php/dependency-selection.mdc — whenever the resolution flow needs to add a new Composer dependency (Packagist or a GitHub-hosted VCS repository), run the Activity gate + Compatibility gate from that rule before recommending a package, and embed the selection note in the PR description. When no candidate passes the gates, stop and surface the disqualification table to the user instead of adopting an inactive library.
• Apply @rules/git/general.mdc
• Apply @rules/reports/general.mdc. The final technical report this skill posts on the GitHub PR (code-review and security-review summary block) stays in canonical English per the rule's Exception — technical CR findings on the GitHub PR. The non-technical report posted on the original issue / JIRA ticket / Bugsnag-linked GitHub issue follows the language of the source assignment. Code identifiers, file paths, severity labels, and CLI commands stay verbatim regardless of the surrounding prose language; never mix two natural languages inside a single comment.
• If the current project uses Laravel, also apply @rules/laravel/laravel.mdc, @rules/laravel/architecture.mdc, @rules/laravel/filament.mdc, and @rules/laravel/livewire.mdc
• Follow project architecture and testing rules
• Do not expose sensitive/internal details in user-facing messages
• Preserve existing behavior unless explicitly required otherwise

Use when

• You are given an issue link, URL, or ID from any supported tracker
• You need to implement a bugfix or feature based on the issue

Source detection

See references/source-detection.md for the detection table and rules.

Preparation

Before starting the resolution flow:

• Switch to the main branch and pull the latest changes so the working tree reflects the current state of the repository before creating the feature branch.

Required approach

• Fully analyze the issue (description, comments, attachments)
• Clearly define scope before writing code
• Classify the task:
• Bug — incorrect existing behavior or runtime error
• Feature — new behavior
• Prefer minimal, safe, and readable changes
• Keep scope limited unless related fixes are trivial and safe
• When implementing DB work, prefer batch operations over per-row queries inside loops per @rules/sql/optimalize.mdc "Batch over per-row operations" — ModelManager batchUpdate / batchInsert, whereIn(...)->delete(), or a single bulk read keyed in memory. Per-row queries are allowed only when iterations have an unavoidable side-effect dependency that is justified in a code comment.

Execution

1. Verify the issue belongs to the current project before proceeding:

• GitHub: the issue repository must match the current Git remote origin.
• JIRA: the issue project key must match the configured JIRA project for this repository.
• Bugsnag: the error's linked GitHub issue/PR repository (linkedIssues[] in the loaded JSON) must match the current Git remote origin. When the error has no linked GitHub issue, confirm the Bugsnag project corresponds to this repository before proceeding.
• If the issue does not belong to the current project, refuse to process it and inform the user.
• The issue must be open / active. Read the status field off the loaded JSON and refuse to resolve a task that is already closed / resolved / done:
• GitHub: the issue (or PR) state must be OPEN. Refuse when it is CLOSED.
• JIRA: the issue must not sit in a terminal status — anything in the Done status category (Done, Closed, Resolved, Cancelled, or the project's equivalent). Refuse when it is.
• Bugsnag: the error status must be open. Refuse when it is fixed, ignored, or snoozed.
• If the issue is not open / active, do not resolve it — stop and inform the user that the task is closed and must be reopened before it can be worked on.
• Claim the issue immediately (per @rules/compound-engineering/general.mdc Claim a tracker issue before working on it). Do this before any code change.
• GitHub: re-read the issue via skills/code-review-github/scripts/load-issue.sh . If the label Resolve_by_AI:in-progress is already present → another run owns it → abort with the message Issue # already claimed (Resolve_by_AI:in-progress) — another run is working on it. If absent → apply it: gh issue edit --add-label "Resolve_by_AI:in-progress". Then re-read and verify the label actually landed (external writes can be silently blocked in auto-mode; verify against the tracker, not just the command exit code). If it did not land → abort rather than proceed unclaimed. Note: the apply-then-verify is not perfectly atomic (GitHub has no CAS on labels), but it collapses the race window to the gap between two loader reads — adequate to stop two long-running agent pipelines from colliding.
• JIRA: run skills/code-review-jira/scripts/transition-to-in-progress.sh . Exit 0 = claimed (or idempotent no-op for this run). Exit 4 = issue is already past In Progress from another run → abort with the message Issue is already past In Progress — another run may be working on it. Exit 5 = target status name differs for this project — discover the real name via the JIRA MCP server's available-transitions and re-run with it as the STATUS argument, or ask a human. Any other non-zero exit → stop and report the failure. This is the second sanctioned status transition (the first is the Code Review transition on PR open); all others remain human-only.
• Bugsnag: no claim step. Bugsnag has no auto-claim mechanism; parallel-collision protection for Bugsnag is a known limitation — rely on the human/linked-issue workflow.
• Release on Blocked / abort (before PR): if this run stops Blocked or aborts before a PR is opened, it must release its own GitHub claim label: gh issue edit --remove-label "Resolve_by_AI:in-progress". JIRA does not auto-revert (transitions back are human-only); name the issue key in the Blocked handoff so a human can reset it. If the claim was never applied (e.g. abort happened before the claim step), skip the release.

1. Fetch and analyze the issue from the detected source by running the deterministic loader for that tracker — never call gh, acli, or REST endpoints directly. Read all required fields off the resulting JSON document.

• GitHub: skills/code-review-github/scripts/load-issue.sh for the structured JSON, or skills/code-review-github/scripts/gather-issue-context.sh for a full Markdown context brief in one pass (issue/PR + comments + changed files + commits + reviews + CI checks + recursively-loaded linked issues/PRs + an inventory of external URLs to follow). Read attachment content and the inventoried URLs with your own tools; follow useful links recursively to a sensible depth. If the script is unavailable (missing tool, exit code 2/3), fall back to the GitHub MCP server.
• JIRA: skills/code-review-jira/scripts/load-issue.sh for the structured JSON, or skills/code-review-jira/scripts/gather-issue-context.sh for a full Markdown context brief in one pass (issue + comments + attachments + recursively-loaded linked issues + an inventory of external URLs to follow). Read attachment content and the inventoried URLs with your own tools — acli cannot fetch them; follow useful links recursively to a sensible depth. If the script is unavailable (missing tool, exit code 2/3), fall back to the JIRA MCP server.
• Bugsnag: skills/code-review-bugsnag/scripts/load-issue.sh (requires BUGSNAG_TOKEN), or skills/code-review-bugsnag/scripts/gather-issue-context.sh for a full Markdown context brief in one pass (error header + latest event + in-project stacktrace + comments + linked issues + an inventory of external URLs). The JSON carries the error class, message, status, context, the in-project latestEvent.stacktrace frames (the entry point for the TDD reproduction), comments[], and linkedIssues[] (the mirrored GitHub issue/PR). If the script is unavailable (missing tool/token, exit code 2/3), fall back to a Bugsnag MCP server.

1. Define exact requirements and expected behavior.
2. Classify the task (bug or feature).

Comment analysis

1. Before analyzing the problem, fetch and read all comments and replies from the issue tracker (GitHub, JIRA, or Bugsnag). For GitHub, JIRA, and Bugsnag issues, read comments[] directly off the JSON loaded in step 2 — do not issue a second listing call:

• Group comments by conversation thread (e.g., review threads, reply chains).
• For each thread, determine:
• Current requirements — requests or conditions that are still valid and unfulfilled.
• Resolved items — requirements already addressed by merged PRs or subsequent comments.
• Outdated items — requests superseded by newer comments or decisions.
• Use only the current requirements (combined with the issue description) as input for the next step.

Context preparation (mandatory pre-flight)

Run @skills/prepare-issue-context/SKILL.md with MODE=resolve-issue and the same issue reference. It extracts every scenario from the assignment's Jak otestovat / acceptance criteria, maps each scenario to a concrete code path, seeds the development database with the records the scenarios depend on, and runs a one-shot reproduction. Stop immediately and surface the gap list to the user when the skill returns blocked: open gap(s) — do not continue into problem analysis with incomplete context, because an implementing agent forced to guess at missing data is the most common source of hallucinated fixes. The scenario table the skill produces is the canonical input for the next step.

Problem analysis

1. Gate — assignment specificity. The pre-flight in step 5 already guarantees every scenario is mapped to a concrete code path; this gate only decides how clear the requirements are. Pick specific or general based on the scenario table and the current requirements from comment analysis:

• Specific — expected behavior is unambiguous for every scenario, and the root cause (for bugs) or target behavior (for features) is explicitly stated in the assignment or current requirements. Skip @skills/analyze-problem/SKILL.md and use the scenario table together with the current requirements as the input for step 7.
• General — requirements are vague, acceptance criteria are missing or open-ended, or the root cause is not identified. When in doubt, treat the assignment as general. Run @skills/analyze-problem/SKILL.md using the issue description, the scenario table, current requirements, and any available context, and use its output as the input for step 7.

1. Review the input from step 6 and split the identified items into three groups:

• In scope — items that directly match the issue requirements. These will be implemented.
• Pre-existing issues — bugs, project-rule violations, or security vulnerabilities already present in the affected files before this task (see Pre-existing issue handling below). These will be fixed in separate commits inside the same PR.
• Out of scope (deferred) — valid findings that fall outside the current issue and do not qualify as pre-existing issues to fix now (e.g. enhancements, refactors, future features). These will be added to the PR summary as a ## TODO list for future tasks.

Read, Map & Verify before implementing (mandatory pre-flight)

Reading, mapping, and verifying come first; implementing comes last. This pre-flight is blocking — do not add or modify a single line of production code until all three steps pass, and never act on an assumption you have not confirmed by reading the code. (The context preparation above maps scenarios to code paths; this gate grounds the actual implementation in the real files you are about to change.)

1. Read — open and read the actual files you will change and the code they depend on (callers, called methods, related tests, configuration, migrations). Confirm what the code does by reading it, not by guessing from names or the issue description.
2. Map — map the change's blast radius: every call site, caller, data-flow path, and existing test that the in-scope change touches, plus the conventions, helpers, Services, and Actions already in the codebase to reuse instead of reinventing.
3. Verify — check your assumptions against the real code and its observed behavior (for bugs, reproduce the failure; for features, confirm the integration points exist as assumed). If reading and mapping contradict the issue framing or the scenario table, stop and surface the discrepancy instead of implementing on a wrong premise.

Only after Read, Map, and Verify are complete may phase planning and implementation begin.

Phase planning (commit plan)

Before writing any code, decide how the in-scope work will be split into commits within the PR, applying the one phase = one commit rule from @rules/git/general.mdc Git Rules.

1. Detect existing phases in the issue description and the kept comments. Phase markers include explicit headings such as Phase 1, numbered milestones, ordered acceptance-criteria blocks, or a step-by-step plan written by the reporter.
2. If phases exist: treat each phase as exactly one commit. Keep the original phase order as commit order. Do not merge, reorder, or re-scope phases.
3. If no phases exist but the assignment is long or covers multiple distinct concerns: propose a phased breakdown — each phase must be independently reviewable and yield a working state — then map one phase per commit.
4. If the assignment is small and atomic: keep it as a single commit. Do not invent artificial phases.
5. Record the planned phases as a numbered list (one line per commit, with the intended commit message in type(scope): description form per @rules/git/general.mdc) before starting implementation. This list is the commit plan for step 11.
6. During implementation, commit at the end of each phase. Run pre-push fixers and tests on the changes belonging to that phase before moving on.

Pre-existing issue handling

While reading and modifying the files required for the in-scope work, you may encounter problems that are unrelated to the current assignment but were already present in those files. The following categories qualify as pre-existing issues that must be fixed in this PR:

• Bugs — incorrect logic, broken edge cases, null-dereference risks, race conditions, or runtime errors that exist before this task.
• Project-rule violations — code that contradicts any rule listed in this skill's Constraints block (@rules/php/core-standards.mdc, @rules/laravel/*, @rules/sql/optimalize.mdc, etc.) or any other rule under .claude/rules/.
• Security vulnerabilities — anything @rules/security/backend.md, @rules/security/frontend.md, or @rules/security/mobile.md would flag (injection, missing authn/authz, unsafe deserialization, sensitive-data exposure, …).

Rules:

1. Do not silently ignore a pre-existing issue you encountered in a file you had to read for the in-scope work — fix it in this PR.
2. Do not expand scope by actively scanning unrelated files for additional pre-existing issues. Limit attention to files already touched by the in-scope changes (or their direct dependencies you must read to understand the change).
3. Land each pre-existing fix in its own separate commit inside the same PR:

• Use a Conventional Commits subject per @rules/git/general.mdc: fix(): pre-existing — for bugs and security, refactor(): pre-existing — for rule violations without behavior change.
• The pre-existing — prefix is mandatory so reviewers can identify these c

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pekral
• Source: pekral/cursor-rules
• License: MIT
• Homepage: https://pekral.cz

Install and usage instructions live in the source repository linked above.