@mrciphersmith/keryx 0.2.72 → 0.2.74

package/src/gdskills/bundled/skills/quality/pr-issue-documenter/SKILL.cursor.md

@@ -1,14 +1,14 @@
 ---
 name: pr-issue-documenter
-description: "Анализирует коммиты/diff PR и генерирует структурированные описания для PR и связанных GitHub issues. Создаёт sub-issues, проверяет противоречия с существующими описаниями, обновляет parent issues."
+description: "Use when documenting PR changes, adding a PR description, creating a linked issue for a PR, or updating an existing issue body."
 triggers:
-  - "Добавь описание к PR"
-  - "Задокументируй PR"
-  - "Опиши что сделано в PR"
-  - "Создай тикет для PR"
-  - "Обнови PR и тикет"
   - "Add PR description"
   - "Document PR changes"
+  - "Describe what was done in PR"
+  - "Create issue for PR"
+  - "Update PR and issue"
+  - "Add description to PR"
+  - "Write PR summary"
 metadata:
   author: "MrCipherSmith"
   version: "1.0.0"
@@ -19,219 +19,258 @@ license: "MIT"
 
 # PR & Issue Documenter
 
-## Назначение
+## Purpose
 
-Анализирует коммиты и diff PR для генерации структурированных, точных описаний GitHub PR и связанных issues. Полный цикл: описание PR, создание sub-issues, обновление parent issues, проверка противоречий с существующими описаниями.
+Analyzes PR commits and diffs to generate structured, accurate descriptions for GitHub PRs and linked issues. Handles the full lifecycle: PR description, sub-issue creation, parent issue updates, and contradiction detection with existing descriptions.
 
-**Вход**: URL PR, URL issue, и/или SHA коммитов
-**Выход**: Обновлённое тело PR, созданный/обновлённый issue, ссылка в parent issue
+**Input**: PR URL, issue URL, and/or commit SHAs
+**Output**: Updated PR body, created/updated issue body, parent issue link
 
-## Когда использовать
+## When to Use
 
-- Пользователь даёт ссылку на PR и просит описание
-- Пользователь хочет задокументировать изменения в PR
-- Пользователь хочет создать issue для PR
-- Пользователь хочет обновить существующий issue данными PR
-- Пользователь даёт SHA коммитов и хочет документацию
+- User provides PR link and asks for a description
+- User asks to document changes in a PR
+- User wants to create an issue for a PR
+- User wants to update an existing issue with PR changes
+- User provides commit SHAs and wants documentation
+
+## Architecture
+
+```
+Step 1: Parse Input
+    |
+Step 2: Collect Context (commits, diff, existing descriptions)
+    |
+Step 3: Analyze Changes (categorize, group, identify patterns)
+    |
+Step 4: Generate PR Description
+    |
+Step 5: Handle Issue (create / update / skip)
+    |
+Step 6: Apply Changes (gh pr edit, gh issue edit/create)
+    |
+Step 7: Verify & Report
+```
 
 ## Workflow
 
-Скопируй чеклист и отслеживай прогресс:
+Copy this checklist and track progress:
 
 ```
-Прогресс:
-- [ ] Шаг 1: Разобрать входные данные — PR URL, issue URL, SHA коммитов
-- [ ] Шаг 2: Собрать контекст — коммиты, diff, существующие описания
-- [ ] Шаг 3: Анализ изменений — категоризация, группировка, таблица файлов
-- [ ] Шаг 4: Генерация описания PR
-- [ ] Шаг 5: Обработка issue — создать, обновить, или пропустить
-- [ ] Шаг 6: Применить изменения через gh CLI
-- [ ] Шаг 7: Верификация и отчёт
+Task Progress:
+- [ ] Step 1: Parse input — extract PR URL, issue URL, commit SHAs
+- [ ] Step 2: Collect context — fetch commits, diff, existing descriptions
+- [ ] Step 3: Analyze changes — categorize, group, build key files table
+- [ ] Step 4: Generate PR description
+- [ ] Step 5: Handle issue — create, update, or skip
+- [ ] Step 6: Apply changes via gh CLI
+- [ ] Step 7: Verify and report results to user
 ```
 
-### Шаг 1: Разбор входных данных
+### Step 1: Parse Input
 
-Извлечь из сообщения пользователя:
-- **PR URL**: `https://github.com/owner/repo/pull/123` или `#123`
-- **Issue URL**: `https://github.com/owner/repo/issues/456` или `#456`
-- **Commit SHA**: полные или короткие хэши
+Extract from user message:
+- **PR URL**: `https://github.com/owner/repo/pull/123` or `#123`
+- **Issue URL**: `https://github.com/owner/repo/issues/456` or `#456`
+- **Commit SHAs**: full or short SHA hashes
 
-**Дерево решений:**
+**Decision tree:**
 
 ```
-ЕСЛИ PR URL указан:
-  → Продолжить к Шагу 2
+IF PR URL provided:
+  → Continue to Step 2
 
-ЕСЛИ только SHA коммитов (без PR):
-  → СПРОСИТЬ: "Нужно ли также создать/обновить issue, или только проанализировать коммиты?"
+IF only commit SHAs provided (no PR):
+  → ASK user: "Should I also create/update an issue, or just analyze the commits?"
+  → If user provides issue link → continue with both
+  → If user says skip → analyze commits only and present summary
 
-ЕСЛИ только issue URL (без PR):
-  → СПРОСИТЬ: "Укажите URL PR или SHA коммитов для анализа изменений"
+IF only issue URL provided (no PR):
+  → ASK user: "Please provide a PR URL or commit SHAs to analyze changes"
 
-ЕСЛИ ничего не указано:
-  → СПРОСИТЬ: "Укажите URL PR, URL issue, или SHA коммитов"
+IF nothing provided:
+  → ASK user: "Please provide a PR URL, issue URL, or commit SHAs"
 ```
 
-### Шаг 2: Сбор контекста
+### Step 2: Collect Context
 
-**Для PR:**
+Gather all necessary data:
+
+**For PR:**
 ```bash
 gh pr view {number} --json title,body,state,baseRefName,headRefName,commits
 gh pr diff {number}
 ```
 
-**Для конкретных коммитов:**
+**For specific commits:**
 ```bash
-git show {sha} --stat
-git show {sha} --format=""
-git log {sha} -1 --format="%H %s%n%b"
+git show {sha} --stat          # files changed
+git show {sha} --format=""     # full diff
+git log {sha} -1 --format="%H %s%n%b"  # commit message
 ```
 
-**Для существующего issue:**
+**For existing issue (if provided):**
 ```bash
 gh issue view {number} --json title,body,state
 ```
 
-**Поиск parent issue:**
-- Проверить тело PR на `Closes #N`, `Fixes #N`, `Parent issue: #N`
-- Проверить тело issue на `Parent issue: #N`
-- Если найден parent → загрузить его тело тоже
+**For parent issue detection:**
+- Check PR body for `Closes #N`, `Fixes #N`, `Parent issue: #N`
+- Check issue body for `Parent issue: #N`
+- If parent issue found, fetch its body too:
+```bash
+gh issue view {parent_number} --json title,body
+```
+
+### Step 3: Analyze Changes
 
-### Шаг 3: Анализ изменений
+Systematically analyze the collected diffs:
 
-**3.1. Категоризация:**
-- `refactor` — реструктуризация без изменения поведения
-- `feature` — новая функциональность
-- `bugfix` — исправление бага
-- `cleanup` — удаление мёртвого кода, неиспользуемых импортов
-- `i18n` — переводы, локализация
-- `test` — тесты
-- `style` — форматирование, именование, порядок импортов
+**3.1. Categorize each change:**
+- `refactor` — restructuring without behavior change
+- `feature` — new functionality
+- `bugfix` — fixing broken behavior
+- `cleanup` — removing dead code, unused imports
+- `i18n` — translations, localization
+- `test` — test additions/modifications
+- `docs` — documentation changes
+- `style` — formatting, naming, import ordering
 
-**3.2. Группировка по логическим областям:**
-- Объединить связанные изменения из разных файлов
-- Каждая секция должна иметь ясную цель
+**3.2. Group by logical area:**
+- Identify related changes across files
+- Group into named sections (e.g., "StepStore — Input/Output Consolidation")
+- Each section should have a clear purpose statement
 
-**3.3. Ключевые паттерны:**
-- Удалённые файлы (выделить жирным)
-- Переименованные поля/методы (before → after)
-- Новые API/интерфейсы
-- Временные/захардкоженные значения (отметить для follow-up)
+**3.3. Identify key patterns:**
+- Deleted files (important to highlight)
+- Renamed fields/methods (before → after)
+- New APIs/interfaces
+- Breaking changes
+- Temporary/hardcoded values (mark for follow-up)
 
-**3.4. Таблица ключевых файлов:**
+**3.4. Build Key Files table:**
 
 | File | Change |
 |------|--------|
-| `path/to/file.ts` | Краткое описание |
+| `path/to/file.ts` | Brief description |
 | `path/to/deleted.ts` | **Deleted** |
 
-### Шаг 4: Генерация описания PR
+### Step 4: Generate PR Description
 
-Структура:
+Use this structure:
 
 ```markdown
 ## Summary
 
-[2-3 предложения: ЧТО сделано, ЗАЧЕМ. Фокус на цели, а не на отдельных изменениях.]
+[2-3 sentences: WHAT was done, WHY it was done. Focus on the purpose, not individual changes.]
 
 Closes #N
 
 ## Changes
 
-### [Название секции 1]
-- Пункт с конкретным изменением
-- Используй `форматирование кода` для идентификаторов
+### [Section Name 1]
+- Bullet point describing specific change
+- Another bullet point
+- Use `code formatting` for identifiers
 
-### [Название секции 2]
+### [Section Name 2]
 ...
 
+### Other
+- Minor changes that don't warrant their own section
+
 ## Key Files
 
 | File | Change |
 |------|--------|
-| `path/file.ts` | Краткое описание |
+| `path/file.ts` | Brief description |
 ```
 
-**Правила:**
-- Summary: кратко, 2-3 предложения максимум
-- Changes: группировка по логике, не по файлам
-- Бэктики для кодовых идентификаторов
-- **Deleted** жирным для удалённых файлов
-- `Closes #N` если issue привязан
-- Описание всегда на **английском** (код-документация)
+**PR description rules:**
+- Summary: concise, 2-3 sentences max
+- Changes: grouped by logical area, not by file
+- Use backticks for code identifiers (`ClassName`, `methodName`, `fileName.ts`)
+- Highlight deleted files with **Deleted** in bold
+- Include `Closes #N` if issue is linked
+- Key Files table: sorted by importance, not alphabetically
 
-### Шаг 5: Обработка issue
+### Step 5: Handle Issue
 
-**5.1. Если URL issue указан пользователем:**
+**5.1. If issue URL was provided by user:**
 
-Загрузить текущее тело и сравнить с diff:
+Fetch existing issue body and compare with PR changes:
 
 ```
-ЕСЛИ тело пустое:
-  → Сгенерировать полное описание
-
-ЕСЛИ тело содержит контент:
-  → Проверить противоречия:
-    - Описание утверждает одно, diff показывает другое?
-    - Есть секции о несуществующих изменениях?
-    - Есть изменения в diff, не описанные нигде?
+IF existing body is empty:
+  → Generate full issue body and apply
+
+IF existing body has content:
+  → Check for contradictions:
+    - Does the existing description claim something different from what the diff shows?
+    - Are there sections that describe changes not present in the diff?
+    - Are there changes in the diff not covered by existing sections?
   
-  ЕСЛИ противоречия найдены:
-    → Показать пользователю
-    → СПРОСИТЬ: "Обновить противоречащие секции и добавить недостающие / Заменить целиком / Только добавить новые секции"
-    → Применить выбор
-
-  ЕСЛИ нет противоречий (только пропуски):
-    → Добавить недостающие секции
-    → Сообщить что добавлено
+  IF contradictions found:
+    → Present contradictions to user
+    → ASK: "I found contradictions in the existing issue description. Should I:
+       1. Update the contradicting sections and add missing ones
+       2. Replace the entire description
+       3. Only append new sections"
+    → Apply user's choice
+
+  IF no contradictions (only missing sections):
+    → Add new sections to existing body
+    → Inform user what was added
 ```
 
-**5.2. Если issue не указан, но PR привязан к parent issue:**
+**5.2. If no issue URL provided but PR is linked to a parent issue:**
 
 ```
-СПРОСИТЬ: "PR привязан к parent issue #N. Нужно ли:
-  1. Создать sub-issue под #N с подробным описанием
-  2. Привязать к существующему issue (укажите номер)
-  3. Пропустить документацию issue"
-
-ЕСЛИ создать sub-issue:
-  → Сгенерировать title и body
+ASK user: "PR is linked to parent issue #N. Should I:
+  1. Create a sub-issue under #N with detailed description
+  2. Link to an existing issue (provide number)
+  3. Skip issue documentation"
+
+IF user chooses to create sub-issue:
+  → Generate issue title from changes
+  → Generate detailed issue body (numbered sections, more detail than PR)
   → gh issue create
-  → Обновить parent issue (добавить ссылку)
-  → Обновить PR body (добавить Closes #NEW_ISSUE)
+  → Update parent issue body with new sub-issue link
+  → Update PR body with "Closes #NEW_ISSUE"
 ```
 
-**5.3. Если нет issue и нет parent:**
+**5.3. If no issue URL and no parent issue detected:**
 
 ```
-СПРОСИТЬ: "Связанный issue не найден. Нужно ли:
-  1. Создать новый issue для этого PR
-  2. Создать sub-issue под существующим parent (укажите номер)
-  3. Пропустить документацию issue"
+ASK user: "No linked issue found. Should I:
+  1. Create a new issue for this PR
+  2. Create a sub-issue under an existing parent (provide parent issue number)
+  3. Skip issue documentation"
 ```
 
-**Формат тела issue** (подробнее чем PR):
+**Issue body format** (more detailed than PR):
 
 ```markdown
 ## Summary
 
-[Расширенная версия PR summary с дополнительным контекстом]
+[Same as PR summary but expanded with more context]
 
 **PR**: #N
-Parent issue: #M (если есть)
+Parent issue: #M (if applicable)
 
 ---
 
 ## Changes
 
-### 1. [Название секции]
+### 1. [Section Name]
 
-[Подробный параграф что изменено и зачем]
+[Detailed paragraph explaining what was changed and why]
 
-- Конкретные пункты с техническими деталями
-- Before → after для переименований/рефакторингов
+- Specific bullet points with technical details
+- Before → after descriptions for renames/refactors
+- Code examples if helpful
 
-### 2. [Название секции]
+### 2. [Section Name]
 ...
 
 ---
@@ -240,56 +279,100 @@ Parent issue: #M (если есть)
 
 | File | Change |
 |------|--------|
-| `path/file.ts` | Описание |
+| `path/file.ts` | Description |
 ```
 
-### Шаг 6: Применение изменений
+### Step 6: Apply Changes
+
+Execute the changes via gh CLI:
 
 ```bash
+# Update PR description
 gh pr edit {number} --body "..."
+
+# Update existing issue
 gh issue edit {number} --body "..."
+
+# Create new issue
 gh issue create --title "..." --body "..."
+
+# Update parent issue (append sub-issue link)
+gh issue edit {parent_number} --body "..."
 ```
 
-Использовать heredoc (`cat <<'EOF'`) для тела. Верифицировать результат после каждой операции.
+**Important:**
+- Use heredoc (`cat <<'EOF'`) for body content to preserve formatting
+- Always verify the result after each operation
+
+### Step 7: Verify & Report
+
+After all operations, report to the user:
+
+```
+Done. Here's what was created/updated:
+
+- PR #N description updated: {url}
+- Issue #M created/updated: {url}
+- Parent issue #P updated with sub-issue link: {url}
+```
+
+## Contradiction Detection Rules
+
+When comparing existing issue description with PR diff:
+
+1. **Scope contradiction**: Description says change affects only X types, but diff shows it affects all types
+2. **Field name contradiction**: Description uses old field name, diff shows it was renamed
+3. **Missing sections**: Diff contains changes not described in any section
+4. **Stale sections**: Description contains sections about changes not in the diff
+5. **Required/optional contradiction**: Description says field is optional, diff shows it's required
+
+Always present contradictions to user before making changes.
+
+## Quality Standards
+
+- PR description: concise, scannable, well-structured
+- Issue description: detailed, comprehensive, with numbered sections
+- Always use English for code documentation
+- Never invent changes not present in the diff
+- Always verify diff content before writing descriptions
+- Group related changes logically, not by file
+- Highlight breaking changes and deleted files prominently
+- Mark temporary/hardcoded values for follow-up
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| PR not found | Ask user to verify PR number/URL |
+| Issue not found | Ask user to verify issue number/URL |
+| Commit SHA not found | Ask user to verify SHA |
+| `gh` CLI not authenticated | Instruct user to run `gh auth login` |
+| Empty diff | Inform user that PR has no file changes |
+| Permission denied | Inform user they may not have write access |
+
+## Rules of Engagement
+
+1. **DO** analyze ALL commits in the PR, not just the latest one
+2. **DO** check for contradictions before updating existing descriptions
+3. **DO** ask user before overwriting existing issue content
+4. **DO** update parent issue when creating sub-issues
+5. **DO** include `Closes #N` in PR body when issue is linked
+6. **DO NOT** invent or assume changes not visible in the diff
+7. **DO NOT** silently overwrite existing issue descriptions
+8. **DO NOT** create issues without user confirmation
+9. **DO NOT** modify PR title unless explicitly asked
+10. **DO NOT** write comments on GitHub PRs/issues (only edit body)
+
+## Job Context Awareness
 
-### Шаг 7: Верификация и отчёт
+If called within an orchestrator job context, check for job context before starting:
 
 ```
-Готово:
-- PR #N описание обновлено: {url}
-- Issue #M создан/обновлён: {url}
-- Parent issue #P обновлён: {url}
+IF JOB_NAME is provided AND .metaproject/jobs/<JOB_NAME>/ai/context.md exists:
+  Read context.md — use it to understand the codebase, affected areas, and conventions
+  This enriches PR description generation with project-specific knowledge
+ELSE:
+  Proceed with standard workflow (analyze PR/commits directly)
 ```
 
-## Проверка противоречий
-
-1. **Scope**: описание говорит "только X типы", а diff показывает все типы
-2. **Названия полей**: описание использует старое имя, diff показывает переименование
-3. **Пропущенные секции**: изменения в diff не описаны нигде
-4. **Устаревшие секции**: описание содержит секции о несуществующих изменениях
-5. **Required/optional**: описание говорит optional, diff показывает required
-
-Всегда показывать противоречия пользователю перед внесением изменений.
-
-## Стандарты качества
-
-- PR описание: краткое, сканируемое, хорошо структурированное
-- Issue описание: подробное, исчерпывающее, с нумерованными секциями
-- Язык описаний: **всегда английский** (код-документация)
-- Никогда не придумывать изменения, которых нет в diff
-- Группировать по логике, не по файлам
-- Выделять breaking changes и удалённые файлы
-
-## Правила
-
-1. **Анализировать ВСЕ коммиты** PR, не только последний
-2. **Проверять противоречия** перед обновлением существующих описаний
-3. **Спрашивать** перед перезаписью содержимого issue
-4. **Обновлять parent issue** при создании sub-issues
-5. **Включать `Closes #N`** в тело PR
-6. **НЕ придумывать** изменения, которых нет в diff
-7. **НЕ перезаписывать** молча существующие описания
-8. **НЕ создавать** issues без подтверждения пользователя
-9. **НЕ менять** title PR если не просили явно
-10. **НЕ писать** комментарии в GitHub PR/issues (только edit body)
+The job context path is: `<JOBS_ROOT>/<JOB_NAME>/ai/context.md`

package/src/gdskills/bundled/skills/quality/pr-issue-documenter/SKILL.opencode.md

@@ -1,6 +1,6 @@
 ---
 name: pr-issue-documenter
-description: "Analyzes PR commits/diff and generates structured descriptions for PRs and linked GitHub issues. Creates sub-issues, checks for contradictions with existing descriptions, updates parent issues. Use when: documenting PR changes, adding PR description, creating issue for PR, updating issue body."
+description: "Use when documenting PR changes, adding a PR description, creating a linked issue for a PR, or updating an existing issue body."
 triggers:
   - "Add PR description"
   - "Document PR changes"
@@ -362,3 +362,17 @@ Always present contradictions to user before making changes.
 8. **DO NOT** create issues without user confirmation
 9. **DO NOT** modify PR title unless explicitly asked
 10. **DO NOT** write comments on GitHub PRs/issues (only edit body)
+
+## Job Context Awareness
+
+If called within an orchestrator job context, check for job context before starting:
+
+```
+IF JOB_NAME is provided AND .metaproject/jobs/<JOB_NAME>/ai/context.md exists:
+  Read context.md — use it to understand the codebase, affected areas, and conventions
+  This enriches PR description generation with project-specific knowledge
+ELSE:
+  Proceed with standard workflow (analyze PR/commits directly)
+```
+
+The job context path is: `<JOBS_ROOT>/<JOB_NAME>/ai/context.md`