Initial commit

issue-executor/SKILL.md

@@ -0,0 +1,123 @@
+---
+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`.