issue-executor

Issue Executor

Purpose

To kickstart the development workflow for a single GitHub issue by generating a comprehensive, context-aware implementation plan. This skill leverages the Gemini CLI to synthesize issue details, relevant specifications, and historical learnings from the project retrospective into a clear, actionable plan. It then creates an isolated feature branch, setting the stage for focused, spec-driven development.

When to Use

Use this skill in the following situations:

• Starting work on a planned GitHub issue from the current sprint.
• Beginning a work session and wanting a synthesized plan before coding.
• Needing to load and understand all context for an issue efficiently.

Prerequisites

• GitHub repository with issues created (via sprint-planner skill).
• Git working directory is clean (no uncommitted changes).
• Currently on the main branch.
• gh CLI tool installed and authenticated.
• jq tool installed for JSON parsing.
• gemini CLI tool installed and authenticated.
• Project has a docs/ structure with specs and a RETROSPECTIVE.md.

Core Principles

Context is King

Instead of just viewing files, the skill synthesizes all relevant context into a coherent plan:

• Issue details: Requirements and acceptance criteria.
• Spec files: All specifications referenced in the issue.
• Retrospective: Learnings from past work to avoid repeating mistakes.

Isolation

All work happens on a dedicated feature branch to:

• Protect the main branch from work-in-progress.
• Enable a clean Pull Request workflow.
• Allow abandoning work without impacting the main codebase.

Atomic Work

Each issue represents a single, well-defined task that can be completed and reviewed as a unit.

Workflow

Step 1: Identify the Issue

Determine which issue to work on. The user specifies the issue number (e.g., #45).

Step 2: Run the Helper Script

Execute the work-on-issue.sh script with the issue number:

bash scripts/work-on-issue.sh 45

Step 3: Understand What the Script Does

The helper script automates these critical setup steps:

1. Validates Prerequisites: Checks for jq, a clean git status, and being on the main branch.
2. Fetches Issue Details: Retrieves the issue title and body from GitHub.
3. Finds Context Files: Locates all referenced spec files (.md) in docs/specs/ or docs/changes/ and identifies RETROSPECTIVE.md.
4. Synthesizes Implementation Plan: Constructs a detailed prompt with the issue details and file context (@file syntax) and calls the gemini CLI. It asks Gemini to produce a step-by-step implementation plan based on all provided information.
5. Displays the Plan: Prints the generated plan from Gemini to the console.
6. Creates Feature Branch: Generates a conventional branch name (e.g., feat/45-restructure-doc-indexer) and checks it out.
7. Confirms Readiness: Displays a success message confirming that the branch is ready and the plan has been generated.

Step 4: Review the Implementation Plan

After the script completes, carefully review the implementation plan generated by Gemini. This plan is your starting guide for the implementation, synthesized from all available project context.

Step 5: Begin Implementation

With the plan and feature branch ready:

1. Follow the steps outlined in the generated plan.
2. Write code that meets the acceptance criteria.
3. Test your changes thoroughly.
4. Commit work incrementally.
5. Push to the remote branch when ready to create a Pull Request.

Error Handling

Working Directory Not Clean / Not on Main Branch

Symptom: Script reports uncommitted changes or that you are not on the main branch. Solution: Commit, stash, or discard your changes. Switch back to the main branch before re-running the script.

Missing jq or gemini Tool

Symptom: Script reports that jq or gemini is not installed. Solution: Install the required tool. For jq, use sudo apt install jq or brew install jq. For gemini, follow its official installation instructions.

Gemini CLI Issues

Symptom: The script fails while generating the implementation plan, showing an error from the gemini command. Solution:

• Ensure the gemini CLI is installed correctly and is in your system's PATH.
• Verify your authentication status with gemini auth.
• Check for Gemini API outages or connectivity issues.
• Examine the prompt being sent to Gemini for any syntax errors.

Spec File Not Found

Symptom: The script runs, but the plan doesn't seem to include context from a spec file you expected. Solution:

• Ensure the issue body explicitly references the spec file with its full path (e.g., docs/specs/my-spec.md). The script only includes files that are directly mentioned.
• Verify the referenced file path is correct and the file exists.

Notes

• The script's primary output is now an actionable implementation plan, not just a list of files.
• The quality of the plan depends on the quality of the input (issue description, specs, retrospective).
• The generated plan is a guide; use your own expertise to adapt and improve it as you work.
• Branch naming follows the convention: feat/ISSUE_NUMBER-kebab-case-title.