123 lines
5.5 KiB
Markdown
123 lines
5.5 KiB
Markdown
---
|
|
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 #X" or "implement 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
|
|
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`. |