| name | issue-executor |
| description | Use this skill to start work on a GitHub issue. It synthesizes all relevant context (specs, retrospective, issue details) using the Gemini CLI to generate a step-by-step implementation plan, then creates a feature branch to begin work. Triggers include "start work on issue |
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:
- Validates Prerequisites: Checks for
jq, a clean git status, and being on the main branch.
- Fetches Issue Details: Retrieves the issue title and body from GitHub.
- Finds Context Files: Locates all referenced spec files (
.md) in docs/specs/ or docs/changes/ and identifies RETROSPECTIVE.md.
- 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.
- Displays the Plan: Prints the generated plan from Gemini to the console.
- Creates Feature Branch: Generates a conventional branch name (e.g.,
feat/45-restructure-doc-indexer) and checks it out.
- 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:
- Follow the steps outlined in the generated plan.
- Write code that meets the acceptance criteria.
- Test your changes thoroughly.
- Commit work incrementally.
- 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.
