OpenParable
Skip to content
← Back to skills

GH Implement Issue

Development
gh-implement-issue

GH Implement Issue is an Agent Skill for development published in the deviceinsight/kafkactl repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

End-to-end implementation workflow for a GitHub issue from planning through PR creation. Use when starting work on an issue from scratch.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/deviceinsight/kafkactl/blob/HEAD/.claude/skills/github-issue-workflow/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/gh-implement-issue, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Implement GitHub Issue

Strict Test-Driven Development (TDD) workflow for implementing a GitHub issue from start to finish.

IMPORTANT: This workflow is sequential. You MUST complete each step fully before moving to the next. You MUST NOT skip steps, reorder steps, or combine steps. Each step has a gate condition that must be satisfied before proceeding.

When to Use

  • Starting work on a new issue
  • Need structured workflow from branch to PR
  • Want to follow best practices end-to-end
  • Working on assigned GitHub issue

Workflow

Follow these steps in exact order. Do NOT proceed to the next step until the current step is complete.

Step 1: Read issue context

  • Run gh issue view <issue> --comments to understand requirements and prior context
  • Summarize the issue and your understanding to the user
  • Gate: You have a clear understanding of what needs to be done

Step 2: Explore the codebase

  • Search the codebase to understand the relevant code, patterns, and conventions
  • Identify all files that will need to change
  • Gate: You can explain the current behavior and what needs to change

Step 3: Create branch

  • git checkout -b feature/<issue>-<description>
  • Gate: You are on a new feature branch

Step 4: Write tests FIRST (TDD - Red phase)

This is the TDD "Red" phase. You MUST write tests before writing any implementation code.

  • Determine which tests are needed (unit tests, integration tests, or both)
  • If the issue involves Kafka interaction, write integration tests (test name must end with Integration)
  • Write the test code that validates the expected behavior described in the issue
  • Make sure the docker is set up (docker compose up -d) to run integration tests
  • Run the written tests using go test to confirm they fail (DO NOT skip integration tests) (Red phase).
  • Gate: Tests are written and it is confirmed that they fail. Do NOT write any implementation code yet.

Step 5: Human approval (MANDATORY STOP)

You MUST stop here and wait for explicit human approval before continuing.

  • Present a summary of all changes (files modified, what changed, why)
  • Ask: "Please review the changes. Should I proceed with implementation?"
  • Do NOT proceed until the user explicitly approves (e.g., "yes", "looks good", "proceed")
  • If the user requests changes, go back to the appropriate step, make the changes, and return to this step

Step 6: Implement code (TDD - Green phase)

This is the TDD "Green" phase. Now and only now do you write implementation code.

  • Write the minimum code necessary to make the tests pass
  • Run make test to verify unit tests pass
  • Gate: All unit tests pass

Step 7: Refactor (TDD - Refactor phase)

  • Review the implementation for code quality, duplication, and clarity
  • Refactor if needed while keeping tests green
  • Gate: Code is clean and all tests still pass

Step 8: Quality checks

  • Run make fmt to format code
  • Run make lint to run the linter
  • Fix any issues found
  • Gate: Both make fmt and make lint pass with no errors or warnings

Step 9: Human approval (MANDATORY STOP)

You MUST stop here and wait for explicit human approval before continuing.

  • Present a summary of all changes (files modified, what changed, why)
  • Show the diff summary
  • Ask: "Please review the changes. Should I proceed with committing and creating a PR?"
  • Do NOT proceed until the user explicitly approves (e.g., "yes", "looks good", "proceed")
  • If the user requests changes, go back to the appropriate step, make the changes, and return to this step

Step 10: Commit

  • Only after human approval
  • git add . && git commit -m "type(scope): description\n\nCloses #<issue>"
  • Follow conventional commit format
  • Gate: Commit is created successfully

Step 11: Push and create PR

  • git push -u origin <branch>
  • gh pr create --title "..." --body "..."
  • Link the PR to the issue
  • Return the PR URL to the user

Quick Reference

# 1. Fetch issue and create branch
gh issue view <issue>
git checkout -b feature/<issue>-<description>

# 2. TDD cycle
# - Write tests FIRST (Red)
# - Implement code (Green)
# - Refactor
# - Run tests: make test

# 3. Quality checks
make fmt
make lint

# 4. Wait for human approval

# 5. Commit and PR
git add . && git commit -m "feat: description

Closes #<issue>"
git push -u origin <branch>
gh pr create --issue <issue>

Branch Naming Convention

Format: feature/<issue-number>-<description>

Examples:

  • feature/42-add-tensor-ops
  • feature/73-fix-memory-leak
  • feature/105-update-docs

Commit Message Format

Follow conventional commits:

type(scope): Brief description

Detailed explanation of changes.

Closes #<issue-number>

Types: feat, fix, docs, refactor, test, chore

Code Quality Checklist

Before requesting human approval:

  • Tests written BEFORE implementation (TDD Red phase)
  • All tests pass (TDD Green phase)
  • Code refactored for clarity (TDD Refactor phase)
  • Issue requirements met
  • Code formatted (make fmt)
  • Linter passes (make lint)
  • No warnings
  • CHANGELOG.md updated if applicable

References

  • See CLAUDE.md for testing conventions