issue-resolution

Applicability gate (check before any workflow step)

Apply this skill ONLY when BOTH conditions hold:

• The target code belongs to the Sytex repository, including its worktrees.
• The requested task involves changing that code to resolve a bug or issue.

Determine the target from the user's request and repository context. Working in another directory does not exclude an explicitly requested Sytex code fix, and being in a Sytex checkout does not activate this skill for unrelated work.

Do not apply this workflow to other repositories (including agent-skills, Impleload, Omarchy, or ovh_vps), desktop/system problems, support, read-only diagnosis or review, data repairs, or production operations that do not change Sytex code. Mentioning Sytex, Sentry, Linear, an error, or a bug is not sufficient. Editing this skill is not a Sytex code change.

If either condition is absent, stop applying this skill and continue the user's task without imposing its approval gates, Linear issues, worktrees, commits, or PRs. Do not expand an investigation into a code fix merely to activate this workflow. If the user later requests a Sytex code fix, reassess applicability then.

The workflow below applies only after this gate passes, subject to the user's explicit scope and existing authorization.

---

STEP 1: Intake (REQUIRED)

Determine what was provided:

• Sentry issue/event link?
• Linear issue ID/link?
• Free-form description?

Ask only minimum questions needed to understand the problem.

---

STEP 2: Investigation (REQUIRED)

Gather context WITHOUT making changes:

• If Sentry provided: fetch issue details, stacktrace, affected users
• Search codebase for relevant code
• Check recent commits/changes

YOU MUST produce:

• Investigation summary: What you found
• Hypothesis: Most likely root cause

Do NOT proceed to Step 3 until investigation is complete.

---

STEP 3: Propose Solution (REQUIRED)

Present your findings and proposed fix to the user.

If requester is NOT a developer:

• Explain in user terms (non-technical)
• Describe expected outcome

If requester IS a developer:

• Technical diagnosis
• Likely root cause
• Files/areas affected
• Implementation approach

---

STEP 4: Confirmation Gate (MANDATORY)

Ask explicitly:

"Do you approve proceeding with this fix?"

NEVER proceed without explicit user approval.

If user does NOT approve: stop and ask what's missing.

---

STEP 5: Ensure Linear Issue Exists (MANDATORY)

YOU MUST have a Linear issue before proceeding. This is NON-NEGOTIABLE.

• If Linear issue exists → use it
• If NOT → ask: "Should I create a Linear issue, or do you have one?"

If creating a Linear issue, include:

• Clear title
• Description with repro steps
• Investigation summary
• Proposed fix

Do NOT proceed to Step 6 until Linear issue ID is confirmed.

---

STEP 6: Sentry ↔ Linear Association

If Sentry issue exists:

1. Add Sentry link to Linear issue (comment or description)
2. Add Linear issue link to Sentry (comment/annotation)

---

STEP 7: Worktree Setup (MANDATORY)

YOU MUST work in a git worktree. Check if already in one: git worktree list

Once Linear issue ID is known:

1. Determine the default branch (main or master)
2. Update remote reference with full refspec:

   git fetch origin <default-branch>:refs/remotes/origin/<default-branch>
   

3. Create worktree with new branch:

   git worktree add ../<short-description> -b feature/SYT-{id}-{short-description} origin/<default-branch>
   

4. Work inside the worktree directory

If already in a worktree, create/switch to the feature branch from the updated remote.

Branch name format: feature/SYT-{id}-{short-description}

IMPORTANT: ALWAYS use the full refspec when fetching. NEVER use just git fetch origin <branch>.

Do NOT proceed to Step 8 until you are in the correct worktree with the correct branch.

---

STEP 8: Implementation (REQUIRED)

Implement according to approved plan.

• Write the fix
• Write/update tests
• Run tests to verify

---

STEP 9: Commit and PR (MANDATORY)

YOU MUST complete these steps. Do NOT stop before creating the PR.

1. Use /commit skill to commit
2. Use /pr skill to create PR

PR MUST include:

• Linear issue link (ALWAYS)
• Sentry issue link (if applicable)

NEVER report completion without a PR link.

---

STEP 10: Final Summary (REQUIRED)

After ALL steps are complete, provide a brief summary:

• What was fixed (1-2 sentences)
• PR link
• Linear issue link
• Sentry issue link (if applicable)

---

Verification Checklist

Before reporting success, verify:

• [ ] Linear issue exists
• [ ] Branch includes Linear ID
• [ ] Commit was created
• [ ] PR was created and link is provided
• [ ] Sentry↔Linear linked (if Sentry was involved)

If ANY item is missing, you have NOT completed the workflow.