Fix Issue Skill for Claude

Fix YouTrack Issue — Autonomous Workflow

Complete lifecycle of fixing a KRPC YouTrack issue: pickup → analysis → code →

tests → PR → CI → reviewer assignment. Full autonomy is a hard requirement — no user approval between

phases. Communicate progress at natural milestones.

Authentication — CRITICAL

This workflow uses dedicated agent credentials, not the user's personal tokens.

These overrides take precedence over defaults in use-youtrack and use-teamcity skills.

• YouTrack: Use the youtrack-agent MCP server (not youtrack). For REST

fallback, use $YOUTRACK_AGENT_TOKEN (not $YOUTRACK_TOKEN).

• TeamCity: Never run teamcity auth status/login. Prefix every command

with TEAMCITY_TOKEN=$TEAMCITY_AGENT_TOKEN.

• GitHub: Always go through the gh-bot wrapper — see next section.

Using gh — always through the gh-bot wrapper

Every gh invocation in this skill MUST go through:

.claude/skills/fix-issue/scripts/gh-bot.sh <gh args...>

gh-bot generates a fresh App installation token on every call and execs gh

with that token set inline. It is a drop-in replacement for gh.

You MUST NEVER call gh directly.

Examples:

.claude/skills/fix-issue/scripts/gh-bot.sh pr create --draft ...
.claude/skills/fix-issue/scripts/gh-bot.sh pr ready 123
.claude/skills/fix-issue/scripts/gh-bot.sh api /repos/Kotlin/kotlinx-rpc/issues/42/comments ...

Pre-flight Access Check — MANDATORY

Before any work — including reading the issue — run the pre-flight script. It

checks connectivity AND identity for all three services, verifying tokens belong

to the AI Agent accounts, not the user's personal credentials. If any check fails

→ stop and report. Do not proceed.

.claude/skills/fix-issue/scripts/preflight-check.sh

Exit code 0 = all passed. Non-zero = at least one check failed; read output for

which service and why, never proceed with a failed check.

No silent fallback policy

If a service becomes unreachable mid-workflow:

• YouTrack MCP → REST via $YOUTRACK_AGENT_TOKEN is the only permitted fallback
• TC CLI or gh-bot fails → stop and report (no fallback)

Never silently skip a step. Never invent data. Stop, report what failed and at

which phase, wait for instructions.

Skills used in this workflow

When this skill says "invoke superpowers:X", **use the Skill tool — don't just

think through the ideas yourself**. Autonomous mode tends to skip skill

invocations, which defeats the discipline (TDD red-green, structured debugging,

code-review formatting) those skills encode.

References

Detailed guidance for specific situations and phases:

• references/investigation-tips.md — Phase A.3 analysis patterns: prior-issue search (mandatory) and the search_dependency_sources FULL_TEXT workaround.
• references/develocity-tips.md — READ BEFORE any mcp__develocity__* call. Default truncation (100 items, 500-char strings) will bite you; the tips file has the parameter shapes that actually work.
• references/audit-style-scoping.md — Scope discipline for "Audit X" / "Review Y" tickets.
• references/reproducer-verification.md — Before/after verification protocol when the issue includes an external reproducer.
• references/verification-special-cases.md — Mandatory extra verifications for conformance known_failures.txt and compiler-plugin changes (Phase C.2).
• references/code-review-agents.md — Reviewer menu and prompting guide for Phase C.3.
• references/ship-workflow.md — Phase D steps: commits, PR creation, CI polling, finalization, YouTrack update.
• references/ci-polling.md — How to run the TC + GitHub Actions poll scripts as background bash in Phase D.3.
• references/addressing-pr-comments.md — Multi-turn workflow for handling PR feedback after the PR is up.
• references/filing-follow-up-issues.md — Drop-in replacement for file-youtrack-issue when creating YT issues mid-workflow.
• references/youtrack-attachments.md — REST recipe for attaching files to YT issues when the MCP server can't.

Input

Required: A YouTrack issue ID (e.g., KRPC-540).

Alternative: User asks to scan for issues. Search UFG Claude-tagged issues:

project: KRPC tag: {UFG Claude} State: Open sort by: Priority asc, created asc
project: KRPC tag: {UFG Claude} State: Submitted sort by: Priority asc, created asc

Prioritize Open over Submitted, higher priority first. Take the top one.

Workflow Phases

Four phases (A–D), each with exit conditions. If the approach changes

significantly mid-phase, loop back — reset the branch cleanly (see Error

Recovery), re-run verifications, update PR/comment descriptions with new approach.

Phase A: Claim & Analyze

A.1: Claim the Issue

Read the issue via youtrack-agent MCP. Then do all four — none are optional:

• Assign to AI Agent [Kxrpc] (look up the login once, cache it).
• Set state to In progress.
• Set sprint to the current active planning period if none is set. Find it

via get_issue_fields_schema for the KRPC project — the sprint/planning

period field enumerates all periods. The last non-checkmarked

[Kxrpc] Planning Period is typically active. Planning periods are custom

fields, not tags.

• Check for linked GH issue — look for a github-issue tag. If present,

note the GH issue number now; you'll need it in Phase D for the commit

message and PR body (Fixes #NNN).

A.2: Set Up the Worktree

Create the worktree before exploring code so all analysis runs against the

latest origin/main, not whatever the original repo has checked out.

git fetch origin main
git worktree add -b <branch-name> /tmp/krpc-<issue-id> origin/main

Branch naming: fix/KRPC-<N> (bugs), feat/KRPC-<N> (features),

task/KRPC-<N> (tasks).

Create local.properties in the worktree — Gradle requires it:

sed "s|<User>|$(whoami)|g" .claude/skills/fix-issue/assets/local.properties.template \
  > /tmp/krpc-<issue-id>/local.properties

When using Gradle skills, always use the worktree root as projectRoot —

even for included builds (compiler-plugin/, gradle-plugin/, protoc-gen/,

dokka-plugin/). The Gradle MCP rejects included build subdirectories because

they have no Gradle wrapper. Address included build tasks from the root using

the composite prefix: :protoc-gen:common:test,

:compiler-plugin:compiler-plugin-backend:build, :dokka-plugin:build.

All subsequent operations — exploration, builds, tests — use the worktree path.

A.3: Analyze the Problem

Read the issue body, all comments, and all linked issues — they often

contain critical context, reproductions, or scope changes missing from the

description. Understand what's broken/missing, which modules are involved, the

type (bug/feature/task), and linked issues.

For situational guidance (similar-issues search, dependency-source gotcha,

Develocity usage, audit-style scope traps, bug-vs-usability-problem

classification), consult the References section above.

If the ticket's literal ## Task steps are disproportionate to the likely value

of the finding (e.g., "trigger N CI builds to bisect" when static analysis will

identify the answer in minutes), propose a scoped alternative in the triage

comment and issue-body update — those artifacts are your scope-change contract.

Don't grind through expensive prescribed steps when cheaper investigation

suffices; don't silently skip them either.

For bugs, you must invoke superpowers:systematic-debugging before posting the triage

comment: reproduce, trace data flow backward to where incorrect state

originates, form a specific hypothesis ("Field X is null because deserialize()

silently drops the payload when..."), and have your reproducer confirm it.

Post a triage comment — MANDATORY (every issue type)

The comment is proof analysis happened. One of:

• Bug with reproducer: use assets/yt-reproducer-comment.md.
• Bug without reproducer (obvious fix, already has one, trivially

reproducible): comment explicitly stating why ("Reproducer not needed —

the bug is visible in any generated KDoc block; the issue description itself

serves as the reproduction").

• Non-bug (feature, task): post analysis findings and planned approach.

Update the issue body

Append your analysis using assets/yt-issue-update.md. **Re-read the template

before writing — do not reconstruct from memory.** Fill in affected modules and

root cause. Problem analysis only — no fix or solution. Reproducers go in the

triage comment, not the body.

Exit condition: triage comment posted, issue body updated, related issues

linked.

Phase B: Implement

Entry: Phase A complete. git fetch origin main and rebase before pushing any

commits.

B.1: Write a Failing Test (if applicable)

Skip formal tests for: docs-only, trivial/obvious fixes, or when existing

tests already cover the scenario.

Demonstrate-it-works principle

Even when formal tests are skipped, **every new capability must be demonstrated

end-to-end before you can claim it works.** If you add a native binary, a

script, a code generator, a new build task, or any other executable artifact —

you must actually run it and show it produces the expected output. "It compiled"

or "the file exists" is not verification. The build/infra exemption from formal

tests does NOT exempt you from proving the thing works. If you can't demonstrate

it works, you can't move on.

Examples:

• New native binary → execute it with representative input, verify output
• New Gradle task → run the task, verify it produces the expected artifact
• New script → execute it, verify it does what it's supposed to do
• New code generator → run generation, verify the output compiles and is correct

When the issue includes an external reproducer (a separate project, repo, or

code sample), end-to-end verification against that reproducer is mandatory —

follow references/reproducer-verification.md. The before/after verification

matrix posted to YT is the primary evidence artifact for the fix.

Writing formal tests

When needed (new test or modification of existing):

• Identify the correct test module.
• Build smoke test first: verify the target test module compiles

(<module>:compileTestKotlin or equivalent). A broken build dependency or

missing task wiring blocks all test compilation — surface that before writing

tests.

• Write/modify a test that captures the buggy behavior or missing feature.
• Invoke superpowers:test-driven-development. Run via running_gradle_tests

and verify a valid RED state — the test must compile and run, then fail on

the assertion. A compilation error or setup crash is not a valid RED.

• Follow existing patterns in the same module.

After the fix is applied (B.2), re-run to confirm GREEN. **If it still fails,

the fix is incomplete — do not move on.**

B.2: Apply the Fix

Plan before coding

Features always use the Complex path regardless of size — they involve

design decisions (API surface, naming, extensibility, integration) that benefit

from brainstorming and a reviewed plan.

Standard (obvious approach, no design decisions, non-feature): brief inline

bullets, start coding.

Complex (all features, OR bugs/tasks that are architectural, multi-module,

public API, or have unclear tradeoffs):

• Invoke superpowers:brainstorming to surface approaches and tradeoffs.
• Plan agent → detailed plan (root cause, approach, alternatives, files,

risks, verification).

• Spawn a review agent to critique the plan before coding (edge cases,

simpler alternatives, binary-compat risks, architectural patterns).

• Incorporate feedback, then execute. No user approval — the review is for

correctness, not permission.

Follow project conventions. Keep changes minimal and focused — don't refactor

surrounding code. After fixing, run B.1 tests + related module tests.

Exit condition: all tests pass (new + existing module tests).

Phase C: Verify & Review

C.1: Check Documentation

Use update-doc skill conventions. Evaluate:

• Changed public API behavior → update KDoc / Writerside topics.
• New public API → add KDoc (required).
• Changed config/setup → update Writerside topics.
• Deprecations → update/create migration guide.

If no doc changes are needed, state why explicitly before moving on (e.g.,

"No docs changes — internal implementation only, no public API affected"). Do

not silently skip.

C.2: Run Local Verifications

Always use the run-local-verifications skill. Before running any check,

reason about whether your change actually falls within its scope — don't run

mechanically (JPMS is irrelevant for native-only code; ABI check is irrelevant

for internal-only logic). Never run Gradle builds in parallel against the same

worktree — builds share state and corrupt each other.

For special-case verifications (conformance known_failures.txt changes, any

compiler-plugin change), see references/verification-special-cases.md. These

are mandatory extras that cannot be skipped when they apply.

Generated code: if verifications produce updated generated files (ABI dumps,

WKT, conformance code, platform table), do not hand-edit them — commit the

regenerated output as-is. They go into a separate commit (Phase D).

All relevant checks must pass before proceeding to C.3.

C.3: Code Review

Spawn at least 2 independent review agents in parallel on the full diff.

See references/code-review-agents.md for the reviewer menu and prompting

guide.

Invoke superpowers:requesting-code-review to structure the request (capture

git range, give each reviewer structured context).

When reviews come back, invoke superpowers:receiving-code-review and handle

feedback in priority order:

• Errors/Critical — fix immediately. Do not proceed to Phase D with

unfixed errors.

• Warnings/Important — fix unless you have a concrete reason to skip

(document it).

• Nits/Minor — fix if trivial, skip if it would bloat the diff.

After applying error/warning fixes, re-run B.1 tests to confirm no regressions.

Exit condition: all local verifications pass, all review errors fixed,

tests re-confirmed.

Phase D: Ship

Follow references/ship-workflow.md for commit, PR, CI, finalization, and

YouTrack update steps.

Exit condition: PR is not draft, reviewer assigned, CI green, YT issue set

to "Fixed in Branch", completion verification passed.

Addressing PR Comments

When asked to address PR comments / feedback after the PR is up, follow

references/addressing-pr-comments.md. The reference covers reading comments,

implementing fixes, resolving conversations vs. reactions, updating checkbox

comments, and re-requesting review. "Address the feedback" means **all of

these**, not just the code fixes.

Filing Follow-Up Issues

If you discover related bugs, latent risks, or follow-up work during any phase,

file them immediately rather than losing context. **Read

references/filing-follow-up-issues.md first** — it replaces

file-youtrack-issue for this workflow and encodes the required field shapes.

Error Recovery

• Build fails locally: read the error, fix, re-run. Don't just retry.
• TC build fails: investigate with teamcity run log <id> --failed, fix

and push.

• TC build canceled (not failed): retry once. External cancellation (agent

or queue issues) is common and doesn't indicate a code problem. Only

investigate if it cancels again.

• Rebase conflicts: resolve. No user intervention expected.
• Approach pivot: git reset --soft to the last clean commit, recommit

with the new approach, run a clean build (clean task), update PR/comment

descriptions, re-run Phase C from scratch.

Service outages follow the No Silent Fallback policy above.

Escalate to User

Stop and report instead of grinding when:

• Ambiguous root cause — investigation yields multiple plausible

explanations and you can't confidently pick.

• CI fails 3+ times on the same pipeline after distinct fix attempts (not

retries — actual code changes that still fail).

• Scope exceeds the ticket — you found a bigger problem than the issue

describes; fix would span unrelated modules.

• Blocked on external input — needs library update, infra change, or

another team's decision.

When escalating, include: what you tried, what you learned, where the worktree

is, and a specific question/decision for the user to unblock you.

Progress Communication

Brief status at each milestone:

• "Claimed KRPC-540, set to In Progress"
• "Reproduced the bug — null pointer when streaming with empty payload"
• "Fix applied, test passing"
• "Code review done — 2 agents, 1 warning fixed"
• "PR #42 created as draft"
• "CI passing, marking PR ready, and adding reviewers"
• "Done — PR: <url>, YT status: Fixed in Branch"