NowChessSystems/.claude/commands/fix-defect.md

# Fix Defect from YouTrack

Automated defect-fix workflow. Ticket ID: `$ARGUMENTS`

## Step 1 — Fetch Ticket

Call `mcp__youtrack__get_issue` with ID `$ARGUMENTS`.
Extract and display: summary, description, steps to reproduce, Priority, Subsystem.

## Step 2 — Create Worktree

Derive branch name from ticket:
- `type` from YouTrack issue type: `bug` → `fix`, `feature`/`task` → `feat`, `refactor` → `refactor`, else `chore`
- `scope` from affected module/component (kebab-case, omit if unclear)
- `description` from ticket summary: lowercase, kebab-case, max 40 chars, drop articles

Branch format: `<type>/<ticket-id>-<description>`
Example: `fix/NOW-123-castling-validation-failure`

Call `EnterWorktree` with that branch name.
All subsequent file work happens inside this worktree.

## Step 3 — Identify Root Cause (read-only)

1. Run `./compile` — capture all errors and warnings.
2. Run `./test` — capture all failures.
3. Spawn `cavecrew-investigator` with: ticket description + compile/test output → locate root cause (files, line numbers, what's wrong).
4. **If anything is ambiguous (reproduction unclear, scope uncertain, conflicting signals), use `AskUserQuestion` tool to ask — max 4 questions at once.**
5. **Report findings to user. No file writes yet. Wait for acknowledgement before continuing.**

## Step 3b — Complexity Assessment + Subtasks

After root cause confirmed, assess scope:

**Simple** (1–2 files, single concern, < 1 hour estimated): proceed directly to Step 4.

**Complex** (3+ files, multiple concerns, or estimated > 1 hour): create subtasks before coding.

To create subtasks:
1. Break fix into discrete, independently-completable tasks (e.g. "Fix validation in RuleSet", "Add regression test for castling edge case", "Update FenParser to handle X").
2. For each subtask call `mcp__youtrack__create_issue` with:
   - `project`: based on subtask content — do **not** inherit from parent. Backend code → `NCS`; frontend/UI → `NCWF`; Kubernetes/pipelines/CI-CD/DB setup/infrastructure → `NCI`. If ambiguous, ask user.
   - `summary`: concise action-oriented title
   - `type`: `Task`
   - `description`: what to do and why
3. Call `mcp__youtrack__link_issues` to link each subtask to `$ARGUMENTS` with relation `subtask of`.
4. Check if the ticket description or comments mention other issue IDs. For each mentioned ID, suggest a link and confirm with user:
   - Fix depends on another fix finishing first → `is blocked by`
   - This fix blocks another ticket → `blocks`
   - Logically related but independent → `relates to`
5. List created subtask IDs and any additional links to user.

Then proceed to Step 4, implementing subtasks in order.

## Step 4 — Fix

1. Implement fix (use `scala-implementer` agent for non-trivial changes; inline edits for small ones).
2. Run `./compile` — must be green.
3. Run `./test` — must be green.
4. Run `./gradlew spotlessScalaApply` — **blocking, foreground only**. Wait for completion before continuing.
5. Run `./lint` — **blocking, foreground only** (never `run_in_background`). Wait for exit code 0. Must be green.
   - If lint fails, fix all issues and re-run until exit code 0.
   - **Do NOT proceed to Step 5 until `./lint` has completed and returned exit code 0.**
If any step fails, iterate until all pass.

## Step 5 — Review

Spawn `cavecrew-reviewer` on the full diff.
Display findings grouped by severity.

## Step 5b — Apply Review Findings

If the review produced any findings (any severity):
1. Implement all agreed fixes.
2. Run `./compile` — must be green.
3. Run `./test` — must be green.
4. Run `./gradlew spotlessScalaApply` — **blocking, foreground only**. Wait for completion.
5. Run `./lint` — **blocking, foreground only**. Wait for exit code 0.
   - If lint fails, fix all issues and re-run until exit code 0.
6. Re-spawn `cavecrew-reviewer` on the updated diff to confirm all findings are resolved.

Repeat until review is clean or user explicitly accepts remaining findings.

## Step 6 — Confirm + Push

Show summary: ticket, branch, files changed, review findings.
**Use `AskUserQuestion` tool to ask for explicit approval before pushing.** Include any open questions about commit message scope or body if unclear.

On approval, commit following Conventional Commits:

```
<type>(<scope>): <short description, imperative, ≤50 chars>

<optional body: what changed and why, wrap at 72 chars>

Closes $ARGUMENTS
https://knockoutwhist.youtrack.cloud/issue/$ARGUMENTS
```

- `type`: same as branch type (`fix`, `feat`, `refactor`, `chore`, etc.)
- `scope`: affected module (`core`, `rule`, `api`, `bot`, `io`)
- Subject: imperative mood, no period, lowercase
- Footer `Closes $ARGUMENTS` and ticket URL always present

Push branch to remote.

## Step 7 — Comment on Ticket

After successful push, call `mcp__youtrack__add_issue_comment` on `$ARGUMENTS` with:

```
Branch `<branch-name>` pushed.

<one-sentence summary of what was changed and why>

Files changed:
- <file1>
- <file2>
```

## Step 7b — Additional Links

After commenting, ask the user if `$ARGUMENTS` should be linked to any other issues not already linked:

| Situation | Relation |
|-----------|---------|
| This fix blocks another open ticket | `blocks` |
| Another ticket must ship first | `is blocked by` |
| Related defect or story | `relates to` |
| Duplicate of another defect | `duplicates` |

Scan the ticket description and comments for any issue IDs that were mentioned but not yet linked. Suggest those automatically.

Call `mcp__youtrack__link_issues` for each confirmed link.

## Step 8 — Cleanup

Call `ExitWorktree` with `discard_changes: true` to delete the worktree.
(Branch was pushed in step 6 — commits are safe on remote; `discard_changes: true` bypasses the local-ahead guard.)
Report: branch pushed, ticket commented, links created, worktree deleted, done.