Bugfix Workflow

MPS Bugfix Workflow

You are guiding a structured bugfix process for the JetBrains MPS project. Follow each phase in order. Never skip phases or start implementation before the user gives an explicit command to do so.

The issue to fix is the YouTrack ID supplied with this request ($ARGUMENTS when the host substitutes it).

Always-on project rules apply throughout: AGENTS.md and .agents/git.md, conventions.md, tools.md, workflow.md, quality-gates.md. This skill is only the bugfix process and a few stricter overlays — it deliberately does not restate what other skills own.

Required companion skills — load both in Phase 0, before any analysis:

Route from mps-mcp-workflow into the specific mps-aspect-* / mps-language-* skill for whatever the fix turns out to touch.

Critical Directives

• Never start implementing code before the user gives explicit approval. Wait for "implement", "go ahead", "start coding", "do it", etc.
• Never skip Phase 0 preflight. Missing YouTrack MCP, IDEA MCP, or the platform project changes how you should proceed; surface the gap before touching code.
• A fix is not done until TeamCity is green. Local builds and tests are necessary but not sufficient. The definitive confirmation is the TeamCity feature-branch chain for the pushed branch: all tests must pass, or every remaining failure must be proven pre-existing on the base branch. Never report the task complete on local evidence alone, and never predict the outcome of a build that is still running. See Phase 7 and references/teamcity-validation.md.
• The only other legal ending is an explicit not validated — <reason> verdict (the user declined the push, TeamCity is unreachable, …), naming what was and was not run. Silence, or local-only evidence presented as success, is never acceptable.

Phase 0 — Pre-flight Checks

Verify all required tools and inputs before doing any work.

0.1 — Issue ID

If no valid-looking issue ID was supplied (empty $ARGUMENTS, or the host left $ARGUMENTS unsubstituted), stop immediately and ask:

Which YouTrack issue should I work on? Please provide the issue ID (e.g. MPS-12345).

Do not continue until a valid-looking issue ID is supplied.

0.2 — YouTrack MCP

Check that the YouTrack MCP tools are available in this session (the tool list includes get_issue). Do not fetch the issue yet.

If they are not available, say so:

YouTrack MCP is not connected. Please start the YouTrack MCP server and retry.

Do not stop the whole run over it: read the issue through the sanctioned read-only REST fallback in .agents/tools.md (§YouTrack), state that you used it, and remember that every later YouTrack write offered by this skill is off the table until the MCP tools are back.

0.3 — Fetch the issue

Call get_issue with the provided issue ID. If the issue does not exist, report the error and stop. If it exists, extract and display the fields listed in references/issue-fields.md. Keep the raw issue data available for later phases.

0.4 — IDEA MCP (MPS project)

Check that the IDEA MCP tools are available (get_file_problems, search_symbol, build_project, …). Hosts differ: some expose them as top-level tools, others only behind a generic execute_tool (.agents/tools.md §IDEA). Try both before declaring them missing — a reduced surface is not an absent one.

If not available:

IDEA MCP is not connected. Please open the MPS project in IntelliJ IDEA with the MCP plugin running and retry.

Do not continue without the IDEA MCP tools. This is stricter than .agents/tools.md, which allows docs-only work to proceed without IDEA.

0.4b — MPS MCP (models, languages, generators)

Load mps-mcp-workflow now if you have not already — it is required, not optional. Heed in particular its Tool name note: your client wraps the tools with its own prefix, so match them by the stable mps_mcp_* suffix. Never conclude the toolset is missing because a name you guessed for it is absent; the full inventory is mps-mcp-workflow/references/mcp-tools-index.md.

The preflight itself is one read-only call: mps_mcp_list_open_projects. Pass the returned mpsProjectBaseDirectory as projectPath in later calls. Do not probe with mps_mcp_initialize_project_for_agents — it writes the skill catalog and agent guides into the repository.

If mps_mcp_list_open_projects is absent or fails:

MPS MCP is not available. I cannot inspect or edit MPS models, and editing .mps / .mpl as text is forbidden (.agents/conventions.md). Please start or enable the MPS MCP server in the MPS instance that has this project open.

If the issue's subsystem suggests the fix will touch models, languages or generators, that is a hard stop. If the fix is plainly in hand-written Java/Kotlin, record the gap and continue.

0.5 — IDEA MCP (platform project)

If analysis may need IntelliJ platform sources, follow AGENTS.md and .agents/tools.md. Look before you ask: check for a sibling checkout (../intellij-community and similar) and probe it with one IDEA call — the error message lists the projects that are actually open, which answers "is it open?" for free. Only then ask the user for the exact path and to open it in IDEA. If it stays inaccessible, ask whether to proceed with MPS-only sources or wait. See references/platform-prompt.md.

0.6 — TeamCity CLI

Run ~/.local/bin/teamcity auth status to confirm the teamcity CLI is installed and authenticated against https://teamcity.jetbrains.com. The binary is often not on PATH, and every shell invocation is a fresh shell — either use the absolute path or prepend export PATH="$HOME/.local/bin:$PATH"; to each call.

If it is missing or unauthenticated, do not stop — analysis and implementation can proceed. Warn the user now, so the gap is known before Phase 7:

TeamCity CLI is not available/authenticated (teamcity auth status failed). I can implement and locally validate the fix, but I will not be able to confirm it against CI. Please run teamcity auth login when convenient.

Load the teamcity-cli skill for CLI mechanics whenever you interact with TeamCity.

Phase 1 — Version Clarification

Determine which MPS version the fix targets and derive the correct branch and YouTrack fix version.

1. Identify available release branches: run git branch -r --list 'origin/20[0-9][0-9].[0-9]' — the looser origin/20* also matches ~150 legacy 201/…, 202/…, 203/… topic branches and buries the answer. For the in-development version on master, read git show origin/master:build.txt (e.g. 262.9437.SNAPSHOT → 2026.2, prefix 262) and cross-check it against the highest MPS_<ver> TeamCity project; never trust mps.version.
2. Ask the user which version to target — see references/version-prompt.md for the exact wording.
3. Derive git metadata from .agents/git.md (prefix, username, base branch). The topic segment for this ticket is MPS-NNNNN-short-description — see references/branch-naming.md.
4. Derive TeamCity coordinates from .agents/tools.md and record them for Phase 7. Verify with:

   teamcity project param list MPS_<ver> | grep -E "mps.git.branch|mps.idea.platform.number"

   so the prefix and base branch match. <ver> is the compact digits-only release (2026.1 → 20261), never 2026.1 itself.
5. Offer to set the YouTrack Fix versions field after the user confirms the target version — but first compare it with the value already on the issue and skip the offer when it matches. A fix for an already-released version normally gets a bugfix fix-version (2026.1.2) while the git prefix stays 261; state both explicitly so the user can correct you. YouTrack writes need that yes and a Co-Authored-By trailer (.agents/tools.md).

Phase 2 — Problem Analysis

Deeply understand the bug by reading relevant source code in both MPS and the platform.

0. Check for prior art first. Many issues are already diagnosed, already being fixed, or already fixed. Spending the analysis budget re-deriving a root cause that is sitting in the ticket is the most common way to waste this phase.
   • Read the issue's comments for a root cause or a "fixed in branch X" note; if commitsCount is non-zero, re-fetch with recentCommitsCount and read the linked commits.
   • git log --all --grep '<issue-id>' --oneline, git branch -a --list '*<issue-id>*', git worktree list.
   • If Fix versions / Fixed in builds are already set, ask the user whether this is a new fix, a verification, or a backport before starting an RCA. (A released-version fix normally shows Fix versions: 2026.1.2 while the git prefix stays 261 — that combination is consistent, not a contradiction.) If prior art already contains a complete fix — commits on another branch, or a comment stating the root cause and the change — stop and report it with branch and commit IDs, then ask which of these the user wants: cherry-pick onto a new branch, continue on the existing branch, re-implement independently, or only verify. Do not silently re-derive or duplicate an existing fix. Otherwise report what you found and build on it instead of starting from zero.
1. MPS source analysis: launch 2–3 parallel Explore agents (reproduction path, similar code/existing handling, test coverage). Prompts in references/explore-prompts.md. If your host cannot spawn subagents, run the same three investigations yourself, sequentially and time-boxed (roughly 5–8 tool calls each), and state in the RCA that the analysis was single-threaded and therefore narrower than intended.
2. Platform analysis (if accessible): a fourth Explore agent against the platform sources.
3. Root cause identification: present the structured RCA. Template in references/root-cause-template.md.