gh-issue-start

name: gh-issue-start description: >- Start pracy nad issue: branch z domyślnej gałęzi repo, status In progress, assignee. shared_files: - _shared/references/runtime-collaboration-guidelines.md - _shared/scripts/env-load.sh - _shared/scripts/issue-branch.sh

$gh-issue-start

Reguły rozwiązywania ścieżek

• Stosuj globalny kontrakt ścieżek z root AGENTS.md.

Priorytet zasad (globalny kontrakt)

1. Instrukcje systemowe/developerskie środowiska
2. ./AGENTS.md i dokumenty z docs_map
3. Bieżący SKILL.md
4. Pliki wskazane w shared_files

Cel

Zautomatyzować start pracy nad issue: ustalenie numeru issue, utworzenie/checkout brancha z domyślnej gałęzi repo (lub z --base), ustawienie statusu w Projects v2 na In progress oraz przypisanie aktualnego użytkownika.

Kroki

1. Sprawdź autoryzację i scope:
   • gh auth status
   • Jeśli używasz GH_TOKEN: upewnij się, że token ma scope project i read:org (Projects v2 w org); gh auth refresh nie zadziała przy ustawionym GH_TOKEN.
   • Jeśli nie używasz GH_TOKEN i brakuje project lub read:org: gh auth refresh -h github.com -s project,read:org
2. Uruchom skrypt startowy (automatyzuje wykrycie issue, tworzenie/checkout brancha oraz przypisanie aktualnego użytkownika do issue):
   • <skill_dir>/scripts/start.sh
   • Opcje:
     • --issue-number <NUMER>
     • --title "<Tytuł>" (używane, gdy trzeba utworzyć nowe issue)
     • --desc "<Opis>" (krótki opis do utworzenia issue i nazwy brancha)
     • --base <remote/branch|branch> (opcjonalnie; domyślnie domyślna gałąź repo)
   • Nazwa brancha jest wyprowadzana przez wspólny helper <skills_root>/_shared/scripts/issue-branch.sh i ma postać issue/<ID>-<slug>.
   • Skrypt przed utworzeniem nowego brancha wykonuje git fetch dla base ref, aby mieć aktualną bazę.
   • Skrypt zawsze tworzy lub checkoutuje branch dla wskazanego issue (jeśli branch nie istnieje, zostanie utworzony).
3. Po powodzeniu skryptu uruchom osobno $gh-issue-status-set, aby ustawić status In progress:
   • Preferuj przekazanie numeru issue:
     • jeśli użyto --issue-number, przekaż ten numer,
     • w przeciwnym razie użyj numeru z outputu skryptu (Issue #<ID> ready on branch ...).
   • Jeśli nie da się jednoznacznie ustalić numeru issue, pozwól $gh-issue-status-set użyć własnych heurystyk i ewentualnie dopytać.
   • Jeśli ustawienie statusu się nie powiedzie: nie ukrywaj błędu, zwróć użytkownikowi jawny komunikat (status nieustawiony + przyczyna), ale pozostaw informację, że branch/issue start zostały wykonane.

Źródła parametrów

• --issue-number: gdy użytkownik poda numer issue wprost (np. „start issue 46”, „zaczynamy pracę nad 46”).
• --desc: krótki opis zadania podany przez użytkownika (np. „rozpocznij zadanie: dodać skille start/finish”).
• --title: tytuł issue wyprowadzony z opisu użytkownika, gdy chcesz utworzyć issue i nie ma istniejącego ID. Preferuj --desc; --title jest fallbackiem, jeśli użytkownik podał tylko tytuł bez opisu.
• Priorytet: --issue-number > --desc/--title.

Heurystyka ustalania issue (w skrypcie)

1. Jeśli podano --issue-number, używamy go bez dalszych heurystyk.
2. Jeśli podano --desc lub --title, wyszukujemy po tytule (słowa kluczowe z opisu/tytułu).
3. Szukamy wyłącznie w otwartych issue.
4. Jeśli issue nie istnieje: tworzy je (tytuł z --title lub --desc).
5. Nie używamy numerów issue z commitów ani ID z nazwy brancha.

Gdy brakuje danych

Jeśli nie da się ustalić numeru issue ani tytułu/opisu do utworzenia nowego issue, zatrzymaj się i dopytaj użytkownika, opisując czego brakuje (np. „nie mam numeru issue ani opisu/tytułu do utworzenia nowego”).

Jeśli użytkownik podał --issue-number, a issue nie istnieje lub jest zamknięte, nie twórz nowego — poproś o poprawny numer.

Branch naming

• Schemat: issue/<ID>-<slug>.
• Slug: lowercase, spacje → myślniki, usuwa znaki spoza ASCII.
• Źródłem prawdy dla generowania nazwy brancha jest <skills_root>/_shared/scripts/issue-branch.sh.

Kody wyjścia skryptu

• 10 brak tytułu do utworzenia issue → dopytaj użytkownika o tytuł i uruchom ponownie z --title.
• 11 nie udało się utworzyć issue → sprawdź komunikat i spróbuj ponownie po korekcie danych.
• 13 issue o podanym numerze nie istnieje lub jest zamknięte → poinformuj użytkownika i poproś o poprawny --issue-number (sprawdź, czy issue nie zostało zamknięte).
• 21 wiele pasujących issue → poproś użytkownika o numer i uruchom ponownie z --issue-number.
• 12 brak base ref (origin/<default> albo wartość z --base) → sprawdź zdalne branche lub wskaż poprawne --base.
• Inne błędy → odczytaj komunikat skryptu i popraw dane wejściowe.

Format odpowiedzi

• Wynik: issue + branch utworzone/przełączone, status ustawiony.
• Uwagi: brakujące dane, konflikty oraz ewentualny błąd ustawienia statusu (jeśli dotyczy).

Przykłady wejścia

• "$gh-issue-start"
• "start issue 46"
• "rozpocznij zadanie"
• "zaczynamy pracę nad 46"
• "startujemy z zadaniem numer 46"
• "start: krótkim opisem zadania"
• "uruchom gh-issue-start z tytułem"

Przykłady wyjścia

• Wynik: issue #46 aktywowane, branch issue/46-skill-start utworzony i checkout.
  Uwagi: brak.