NowChess/NowChessSystems
4
0
Fork 0
Code Issues Pull Requests 2 Packages Projects Releases Wiki Activity

docs: add automated workflows for defect fixing, user story creation, and issue estimation
Build & Test (NowChessSystems) TeamCity build finished
Details

Browse Source
This commit is contained in:
Janis
2026-06-02 21:42:11 +02:00
parent 9836e87392
commit 98b0bba398
5 changed files with 445 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/commands/create-story.md
+85
View File
@@ -0,0 +1,85 @@
# Create User Story in YouTrack
Automated user-story creation workflow. Topic/hint: `$ARGUMENTS`
## Step 1 — Gather Context
Use `AskUserQuestion` tool to ask the user (max 4 questions at once):
1. **Domain** — Is this frontend (UI/UX) or backend/coordinator/systems work?
2. **User type** — Who is the actor? (e.g. player, admin, bot, system)
3. **Action** — What should the user be able to do?
4. **Goal/value** — Why? What outcome does it enable?
If `$ARGUMENTS` already answers some of these, skip those questions.
## Step 2 — Research (if needed)
If the topic involves unfamiliar domain logic, game rules, or technical constraints:
- Search the repo for relevant code (use `Grep`/`Bash` to find related files).
- Use `WebSearch` if the topic involves external standards or protocols.
- Do NOT guess. Surface findings before drafting.
## Step 3 — Draft Story
Compose the full story using this template:
```
As a [type of user]
I want to [perform an action]
So that [achieve a goal or value]
Description
[Additional context or business logic for this story.]
Acceptance Criteria
[List the specific, measurable criteria that define when this story is done:]
- Criterion 1
- Criterion 2
- Criterion 3
Implementation Notes
[Technical notes, design references, or constraints.]
```
Rules:
- User story line: plain English, present tense, from user's perspective.
- Acceptance criteria: testable, unambiguous, one condition each.
- Implementation notes: optional — only include if there are known constraints, related tickets, or design refs.
## Step 4 — Clarify Acceptance Criteria
Show the draft to the user.
**Use `AskUserQuestion` tool to ask:**
- Are the acceptance criteria complete and correct?
- Any implementation constraints to add?
- Priority (if known)?
Incorporate feedback. Repeat until user approves.
## Step 5 — Determine Project
- Frontend / UI / UX → project: `NCWF`
- Backend / coordinator / systems / bot / engine → project: `NCS`
If ambiguous, ask the user.
## Step 6 — Create Issue
Call `mcp__youtrack__create_issue` with:
- `project`: determined in Step 5
- `summary`: concise title derived from the "I want to" clause (≤72 chars, sentence case)
- `description`: full formatted story from Step 3 (Markdown)
- `type`: `Feature` (or `Task` if purely technical with no user-facing value)
## Step 7 — Report
Display the created issue ID and URL.
Ask if a linked sub-task or implementation ticket is needed.
.claude/commands/estimate-issues.md
+90
View File
@@ -0,0 +1,90 @@
# Estimate Issue Time in YouTrack
Sprint planning time estimator. Issue ID or empty for full current sprint: `$ARGUMENTS`
## Step 1 — Determine Scope
**Single-issue mode** (`$ARGUMENTS` set):
- Call `mcp__youtrack__get_issue` on `$ARGUMENTS`.
- Proceed with that issue only.
**Sprint mode** (`$ARGUMENTS` empty):
- Call `mcp__youtrack__search_issues` with query `project: NCS Sprints: {current sprint} #Unresolved`.
- If query returns 0 results, use `AskUserQuestion` to ask for the sprint name, then retry with `project: NCS Sprints: {name}`.
- Collect all returned issues.
## Step 2 — Build Issue Tree
For each top-level issue from Step 1:
1. Fetch full details via `mcp__youtrack__get_issue`: summary, description, acceptance criteria, Type, existing `Zeitschätzung`, linked issues.
2. Identify subtasks from links with relation `subtask of` (i.e. issues where the fetched issue is the parent).
3. Recursively fetch subtasks until all leaves are known.
4. Group into tree: Epic → Story → Task/Subtask.
**Leaf node** = issue with no subtask children.
**Parent node** = issue that has at least one subtask child.
## Step 3 — Estimate Leaf Nodes
For each leaf node:
1. Read: summary, description, acceptance criteria, implementation notes.
2. If scope is unclear, search codebase (`Grep`/`Bash`) for related files to gauge complexity.
3. Assign estimate using this scale:
| Size | Criteria | Estimate |
|------|----------|----------|
| Trivial | Config change, rename, 1-file tweak | 30m |
| Small | 1–3 files, clear scope, no unknowns | 1h–2h |
| Medium | 3–6 files, some design needed | 3h–5h |
| Large | 6+ files, cross-module, non-trivial design | 1d–2d |
| XL | New subsystem, research spike, major refactor | 3d–5d |
4. Record: estimate + one-line reasoning.
5. Skip leaf if it already has `Zeitschätzung` set — note it as pre-estimated.
## Step 4 — Roll Up for Display
YouTrack auto-sums `Zeitschätzung` from subtasks up to parents — **do not write estimates to parent nodes**.
Compute display-only rolled-up totals:
- Parent total = sum of all descendant leaf estimates (including pre-estimated ones).
- Flag any branch where some leaves are missing estimates (partial roll-up).
## Step 5 — Show Summary + Confirm
Display full tree with estimates. Format:
```
Epic NCS-10: Castling overhaul [4h 30m] ← rolled up
Story NCS-11: Validate castling rights [2h 30m] ← rolled up
Task NCS-12: Fix RuleSet check 1h 30m ← leaf (new)
Task NCS-13: Add regression tests 1h ← leaf (new)
Story NCS-14: UI feedback for castling [2h] ← rolled up
Task NCS-15: Highlight invalid squares 2h ← leaf (pre-set, skipped)
```
Legend: `[X]` = display-only roll-up (not written). Plain = will be written to YouTrack.
If sprint mode, show grand total at bottom:
```
Sprint total: Xd Yh Zm (N issues, M leaves to update)
```
**Use `AskUserQuestion` tool:**
- Does the breakdown look right?
- Any estimates to adjust before writing to YouTrack?
Incorporate all feedback before proceeding.
## Step 6 — Write Estimates
On user approval, write estimates **only to leaf nodes** (bottom-up order):
- For each leaf with a new estimate, call `mcp__youtrack__update_issue` with field `Zeitschätzung` = approved estimate.
- YouTrack period format: `"30m"`, `"1h 30m"`, `"1d"`, `"2d 4h"`.
- Skip leaves already pre-estimated.
## Step 7 — Report
List all updated issues with set estimates.
Show final rolled-up totals per Epic/Story (read back from YouTrack via `mcp__youtrack__get_issue` if needed).
In sprint mode, show total sprint estimate.
.claude/commands/fix-defect.md
+104
View File
@@ -0,0 +1,104 @@
# 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`: same project as parent ticket
- `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. List created subtask IDs 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 `./lint` — must be green.
If any step fails, iterate until all pass.
## Step 5 — Review
Spawn `cavecrew-reviewer` on the full diff.
Display findings grouped by severity.
## 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 8 — Cleanup
Call `ExitWorktree` to delete the worktree.
Report: branch pushed, ticket commented, worktree deleted, done.
.claude/commands/implement-feature.md
+84
View File
@@ -0,0 +1,84 @@
# Implement Feature from YouTrack
Automated feature-implementation workflow. Ticket ID: `$ARGUMENTS`
## Step 1 — Fetch Ticket
Call `mcp__youtrack__get_issue` with ID `$ARGUMENTS`.
Extract and display: summary, description, acceptance criteria, Priority, Subsystem.
## Step 2 — Create Worktree
Derive branch name from ticket:
- `type` from YouTrack issue type: `feature`/`task` → `feat`, `refactor` → `refactor`, `bug` → `fix`, 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: `feat/NOW-456-add-bot-difficulty-slider`
Call `EnterWorktree` with that branch name.
All subsequent file work happens inside this worktree.
## Step 3 — Understand Requirements (read-only)
1. Run `./compile` — confirm baseline is green.
2. Run `./test` — confirm baseline is green.
3. Spawn `cavecrew-investigator` with: ticket description + acceptance criteria → locate affected files, relevant types/interfaces, entry points, integration touch-points.
4. **If anything is ambiguous (scope unclear, acceptance criteria missing, design decisions needed), use `AskUserQuestion` tool to ask — max 4 questions at once.**
5. **Report plan to user: what will be added/changed, which files, which modules. No file writes yet. Wait for acknowledgement before continuing.**
## Step 4 — Implement
1. Implement feature (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 (add new tests for new behaviour; do not modify existing tests unless requirements changed).
4. Run `./lint` — must be green.
If any step fails, iterate until all pass.
## Step 5 — Review
Spawn `cavecrew-reviewer` on the full diff.
Display findings grouped by severity.
## 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 (`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 added and why>
Files changed:
- <file1>
- <file2>
```
## Step 8 — Cleanup
Call `ExitWorktree` to delete the worktree.
Report: branch pushed, ticket commented, worktree deleted, done.
.claude/commands/split-story.md
+82
View File
@@ -0,0 +1,82 @@
# Split Story into Subtasks in YouTrack
Split a user story into smaller, implementable subtasks. Story ID: `$ARGUMENTS`
## Step 1 — Fetch Story
Call `mcp__youtrack__get_issue` with ID `$ARGUMENTS`.
Extract and display: summary, description, acceptance criteria, implementation notes.
## Step 2 — Research (if needed)
If the story involves unfamiliar domain logic or technical constraints:
- Search repo for relevant code (`Grep`/`Bash`).
- Use `WebSearch` for external standards or protocols.
- Do NOT guess. Surface findings before proposing splits.
## Step 3 — Propose Split
Analyse the story and propose a set of subtasks. Rules:
- Each subtask = one unit of work, completable independently or in sequence.
- No subtask should exceed ~2 days of work.
- Name subtasks in imperative mood (e.g. "Implement move validation endpoint").
- Cover the full scope of the parent story — no gaps.
Show proposed subtask list to user (titles only) and ask:
**Use `AskUserQuestion` tool:**
- Does the split look right?
- Any subtasks to add, remove, or merge?
- Should any subtask be assigned to a specific person?
Incorporate feedback. Repeat until user approves the list.
## Step 4 — Draft Each Subtask
For each approved subtask, compose description using this template:
```
[Brief description of what needs to be done for this subtask.]
Steps / Tasks
- Task 1
- Task 2
- Task 3
Definition of Done
What must be true for this subtask to be considered complete:
- Code implemented
- Tests passed
- Reviewed and merged
```
Rules:
- Steps/Tasks: concrete, ordered where order matters.
- Definition of Done: adjust per subtask — not all subtasks need the same criteria (e.g. a research spike has different DoD than an implementation task).
- Keep description short — one paragraph max.
## Step 5 — Determine Project
Inherit project from parent story (`$ARGUMENTS`):
- If parent is `NCWF-*` → subtasks go in `NCWF`
- If parent is `NCS-*` → subtasks go in `NCS`
## Step 6 — Create Subtasks
For each subtask call `mcp__youtrack__create_issue` with:
- `project`: from Step 5
- `summary`: subtask title (≤72 chars, sentence case)
- `description`: full formatted description from Step 4 (Markdown)
- `type`: `Task`
Then call `mcp__youtrack__link_issues` to link each created subtask to `$ARGUMENTS` with relation `subtask of`.
## Step 7 — Report
List all created subtask IDs and summaries.
Display parent story link.
Ask if any subtask needs further splitting.