# Gh Issue

> Fetch a GitHub issue, create a branch, implement with TDD, and open a PR

- Skill: `phel-lang/gh-issue-2` (Agent Skill)
- Install (CLI): `npx get-skill add phel-lang/gh-issue-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/phel-lang/gh-issue-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: phel-lang (https://skillmd.com/u/phel-lang)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/phel-lang/gh-issue-2

---


<!-- Generated by agnostic-ai -->

# GitHub Issue Workflow

## Context

Read both the issue body **and every comment** as requirements input. Maintainer follow-ups frequently add scope, edge cases, or override the original description; when a later comment conflicts with the body, prefer the comment.

!`gh issue view ${ARGUMENTS#\#} --json number,url,title,body,labels,assignees,state,comments 2>/dev/null || echo "Provide an issue number"`

## Instructions

### Phase 1: Setup

1. **Parse the issue number** from `$ARGUMENTS` (strip `#` if present)

2. **Assign yourself if unassigned**:
   ```bash
   gh issue edit <number> --add-assignee @me
   ```

3. **Create a branch** from `main` based on the issue type:

   Determine the branch prefix from labels:
   - `bug` → `fix/`
   - `enhancement` → `feat/`
   - `documentation` → `docs/`
   - No label → `feat/` (default)

   Branch name format: `<prefix><issue-number>-<slug>`

   ```bash
   git checkout main && git pull
   git checkout -b <branch-name>
   ```

### Phase 2: Plan

4. **Enter Plan Mode** to design the implementation:
   - Explore the codebase to understand affected areas
   - Identify files that need changes
   - Consider the module rule from `.claude/rules/plugin-architecture.md`: a module's
     entry points live at its root, its internals in subfolders. Registered classes go at
     the root of the module that owns them.
   - Plan the TDD approach (what tests to write first): unit tests under
     `src/test/kotlin/org/phellang/unit/`, integration under `.../integration/`

5. **Create implementation plan** with:
   - Summary of what the issue requires
   - List of files to create/modify
   - Test strategy (unit, integration)
   - Step-by-step implementation order

### Phase 3: Implement

6. **After plan approval**, implement following TDD:
   - Write failing tests first
   - Implement minimum code to pass
   - Refactor while keeping tests green

7. **Run full test suite**:
   ```bash
   ./gradlew test
   ```
   Fix ALL errors before proceeding. If `.flex` / `.bnf` changed, run
   `./gradlew generatePhelLexer generatePhelParser` and commit the regenerated
   `src/main/gen/` sources. If `NamespaceConfig.kt` changed, run `./gradlew updatePhelRegistry`.

   Note: the integration suite is nondeterministically flaky. A failure that does not
   reproduce in an isolated targeted run is not a real failure — confirm before chasing it.

### Phase 4: Ship

8. **Update CHANGELOG.md** — add entry under `## Unreleased`, **only if the file exists**.
   It does not exist yet in this repo (that is issue #213); skip this step until it does.

9. **Commit changes**:
   ```bash
   git add <specific-files>
   git commit -m "<type>(<scope>): <description>

   Related to #<issue-number>"
   ```

10. **Final refactor commit (mandatory, last commit before PR)**:
    Re-review every file touched by this change. Look for:
    - duplication introduced by the new code (extract or reuse)
    - dead branches, unused params, leftover debug
    - naming drift vs. surrounding module conventions
    - violations of `.claude/rules/plugin-architecture.md` (module rule, package
      boundaries enforced by `ArchitectureBoundaryTest`), `lexer-parser.md`,
      `completion-registry.md`, `testing.md`
    - over-engineering: speculative abstractions, premature interfaces

    Apply fixes. Re-run `./gradlew test`. Commit as a separate `ref(...)` commit — must be the final commit on the branch before PR:
    ```bash
    git commit -m "ref(<scope>): polish <area> after #<issue-number>

    Related to #<issue-number>"
    ```
    If review surfaces zero changes, record that fact in the PR body instead of skipping silently.

11. **Create PR**. Push with tracking, then open it with a summary and test plan.
    Per `.claude/rules/git-workflow.md`: assign `JesusValeraDev`, add the label matching
    the issue, and use `Closes #<issue-number>` so the issue auto-closes on merge.
    ```bash
    git push -u origin <branch-name>
    gh pr create \
      --assignee JesusValeraDev \
      --label <label-from-issue> \
      --title "<type>: <description>" \
      --body "<summary>

    ## Test plan
    <verification steps>

    Closes #<issue-number>"
    ```
    Never reference an AI assistant in the PR title, body, or trailers.

### Phase 5: Verify & Merge

12. **Wait for CI green** on the PR:
    ```bash
    gh pr checks <pr-number-or-branch> --watch
    ```
    Fix red checks on the branch (push fixes; re-watch). Do not proceed while any required check is failing.

13. **Merge with mandatory approval bypass when possible**:
    Once every required check is green, merge via admin bypass to satisfy the mandatory-approval rule:
    ```bash
    gh pr merge <pr-number> --squash --admin --delete-branch
    ```
    If `--admin` is rejected (token lacks admin, branch protection blocks bypass), fall back to `--auto --squash --delete-branch` and surface that the PR is awaiting human approval. Never `--no-verify` past a failing required check.

14. **Sync local main** after merge:
    ```bash
    git checkout main && git fetch origin main && git reset --hard origin/main
    ```

## Checklist
- [ ] Issue fetched and understood
- [ ] Self-assigned
- [ ] Branch created from fresh `origin/main`
- [ ] Plan created and approved
- [ ] Tests written first (TDD)
- [ ] Implementation complete
- [ ] `./gradlew test` passes
- [ ] New/moved plugin features registered in `src/main/resources/META-INF/plugin.xml`
- [ ] `src/main/gen/` regenerated and committed if `.flex` / `.bnf` changed
- [ ] Changelog updated (skip while `CHANGELOG.md` does not exist)
- [ ] Feature commit with issue reference
- [ ] Final refactor commit (last commit on branch, separate `ref(...)`)
- [ ] PR created with assignee, label, and `Closes #X`
- [ ] CI green (`gh pr checks --watch`)
- [ ] PR merged via `--admin --squash` (or `--auto` fallback if admin blocked)
- [ ] Local `main` synced to `origin/main`

