Issue Executor

Purpose

Execute the core development workflow for a single, atomic GitHub issue within the SynthesisFlow methodology. This skill ensures all necessary context is loaded before any code is written, work is isolated on a dedicated feature branch, and the implementation follows the spec-driven approach.

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 ready to implement a specific task
• Need to load full context for an issue before coding
• Want to follow the complete SynthesisFlow development workflow

Prerequisites

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

Core Principles

Context is King

Load all relevant context before writing any code:

• Issue details: Requirements and acceptance criteria
• Spec files: Related specifications from docs/specs or docs/changes
• Retrospective: Learnings from past issues to avoid repeating mistakes
• Doc index: Map of all available documentation

Isolation

All work happens on a dedicated feature branch to:

• Protect main branch from work-in-progress
• Enable clean PR workflow
• Allow abandoning work without impact

Atomic Work

Each issue represents a single, well-defined task that can be:

• Completed independently
• Reviewed as a unit
• Merged without dependencies

Workflow

Step 1: Identify the Issue

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

Check open issues if needed:

gh issue list --assignee @me --state open

Step 2: Run the Helper Script

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

bash scripts/work-on-issue.sh ISSUE_NUMBER

For example:

bash scripts/work-on-issue.sh 45

Step 3: Understand What the Script Does

The helper script automates these steps:

1. Validates prerequisites:

   • Checks jq is installed
   • Verifies git working directory is clean
   • Ensures no uncommitted changes exist

2. Loads issue context:

   • Fetches issue title and body from GitHub
   • Extracts associated spec file references
   • Reads spec files if they exist

3. Loads project context:

   • Reads RETROSPECTIVE.md for lessons learned
   • Runs doc-indexer to get documentation map

4. Creates feature branch:

   • Generates branch name from issue (e.g., feat/45-restructure-doc-indexer)
   • Checks out new branch

5. Confirms readiness:

   • Displays success message
   • Confirms branch created and context loaded

Step 4: Review Loaded Context

After the script completes, review the context it loaded:

• Issue details: Understand requirements and acceptance criteria
• Spec files: Review specifications for what needs to be built
• Retrospective: Note any relevant lessons from past work
• Doc index: Identify other relevant documentation to read

Step 5: Begin Implementation

With full context loaded and feature branch created:

1. Plan the implementation approach
2. Write code following the acceptance criteria
3. Test the changes
4. Commit work incrementally
5. Push to remote when ready for PR

Step 6: When to Use Script vs Manual Steps

Use the helper script when:

• Starting fresh work on a new issue
• Need to load all context automatically
• Want the standard workflow enforced

Use manual steps when:

• Already familiar with the issue context
• Continuing work on an existing branch
• Need to customize the workflow for special cases

Error Handling

Working Directory Not Clean

Symptom: Script reports uncommitted changes

Solution:

• Commit current work: git add . && git commit -m "..."
• Or stash changes: git stash
• Or discard changes: git restore . (careful!)
• Then run script again

Not on Main Branch

Symptom: Currently on a feature branch

Solution:

• Finish current work and create PR
• Or switch to main: git switch main
• Then run script again

Missing jq Tool

Symptom: Script reports jq not installed

Solution:

• Install jq: sudo apt install jq (Linux)
• Or: brew install jq (Mac)
• Or manually parse JSON without script

Spec File Not Found

Symptom: Script reports spec file doesn't exist

Solution:

• Verify the spec file path in the issue body
• Check if spec is in docs/changes/ (proposed) vs docs/specs/ (approved)
• Read the spec from docs/changes/ if it's a new feature
• Proceed without spec if issue doesn't require one

Branch Already Exists

Symptom: Git reports branch name already exists

Solution:

• Check if you're resuming work: git switch feat/45-...
• Or delete old branch: git branch -D feat/45-...
• Then run script again

Notes

• The script loads context but doesn't write code - that's the AI's job with full understanding
• Branch naming follows convention: feat/ISSUE_NUMBER-kebab-case-title
• Issue body should reference spec files as: docs/specs/... or docs/changes/...
• Retrospective provides valuable lessons - pay attention to recent learnings
• Doc indexer shows what documentation exists without loading full content
• For detailed workflow steps, see references/work-on-issue.md
• The script is a helper to reduce repetitive context loading - Claude still executes the development workflow