issue-executor

What this skill does

# 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
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`.