Initial commit
This commit is contained in:
Zhongwei Li
123
issue-executor/SKILL.md
Normal file
123
issue-executor/SKILL.md
Normal file
@@ -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`.
|
||||
609
issue-executor/references/work-on-issue.md
Normal file
609
issue-executor/references/work-on-issue.md
Normal file
@@ -0,0 +1,609 @@
|
||||
# Work on Issue Workflow
|
||||
|
||||
Select and start work on a specific issue from assigned GitHub issues.
|
||||
|
||||
## Purpose
|
||||
|
||||
Load full context for an issue and create a feature branch to begin implementation. Ensures clean workflow start with all necessary context loaded before any code is written.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this workflow when:
|
||||
- Starting work on a new issue
|
||||
- Switching between issues
|
||||
- After completing previous issue
|
||||
- Beginning work session
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Verify Clean Working State
|
||||
|
||||
```bash
|
||||
# Check current branch is clean
|
||||
CURRENT_BRANCH=$(git branch --show-current)
|
||||
if [ "$CURRENT_BRANCH" != "main" ]; then
|
||||
echo "⚠ Currently on branch: $CURRENT_BRANCH"
|
||||
echo "Finish current work or switch to main first."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check for uncommitted changes
|
||||
if [ -n "$(git status --porcelain)" ]; then
|
||||
echo "⚠ Uncommitted changes detected"
|
||||
git status
|
||||
echo "Commit or stash changes before starting new issue."
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
### 2. Get Current User's Assigned Issues
|
||||
|
||||
```bash
|
||||
# Get all open issues assigned to current user
|
||||
gh issue list \
|
||||
--assignee @me \
|
||||
--state open \
|
||||
--json number,title,labels,milestone,createdAt \
|
||||
--limit 50 | jq '.'
|
||||
```
|
||||
|
||||
### 3. Get Milestone Details for Context
|
||||
|
||||
```bash
|
||||
# Get current sprint milestones
|
||||
gh api repos/:owner/:repo/milestones \
|
||||
--jq '.[] | select(.state == "open") | {number, title, state, dueOn}' \
|
||||
| jq -s 'sort_by(.dueOn)'
|
||||
```
|
||||
|
||||
### 4. Check for Spec Conflicts
|
||||
|
||||
For each candidate issue, verify no conflicting work in progress:
|
||||
|
||||
```bash
|
||||
# Extract affected specs from issue body
|
||||
ISSUE_NUM=123
|
||||
AFFECTED_SPECS=$(gh issue view $ISSUE_NUM --json body --jq .body \
|
||||
| rg "Affected Specs.*" -A 5 \
|
||||
| rg "docs/specs/([^/]+)" -o -r '$1')
|
||||
|
||||
# Check if any other open issues affect same specs
|
||||
for SPEC in $AFFECTED_SPECS; do
|
||||
CONFLICTS=$(gh issue list \
|
||||
--assignee @me \
|
||||
--state open \
|
||||
--search "docs/specs/$SPEC in:body" \
|
||||
--json number,title)
|
||||
|
||||
if [ $(echo "$CONFLICTS" | jq 'length') -gt 1 ]; then
|
||||
echo "⚠ Conflict detected: Multiple issues affect $SPEC"
|
||||
echo "$CONFLICTS" | jq -r '.[] | "#\(.number) - \(.title)"'
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### 5. Analyze and Recommend Issues
|
||||
|
||||
Sort and prioritize issues by:
|
||||
|
||||
1. **Priority**: P0 > P1 > P2 > P3
|
||||
2. **Sprint alignment**: Current milestone first
|
||||
3. **Spec readiness**: Issues with existing specs
|
||||
4. **Dependencies**: Non-blocked issues first
|
||||
|
||||
```bash
|
||||
# Parse priorities from labels
|
||||
P0_ISSUES=$(gh issue list --assignee @me --state open --label "priority:P0" --json number,title,milestone)
|
||||
P1_ISSUES=$(gh issue list --assignee @me --state open --label "priority:P1" --json number,title,milestone)
|
||||
P2_ISSUES=$(gh issue list --assignee @me --state open --label "priority:P2" --json number,title,milestone)
|
||||
|
||||
# Show recommendations
|
||||
echo "=== Recommended Issues ==="
|
||||
echo ""
|
||||
echo "Priority P0 (Critical):"
|
||||
echo "$P0_ISSUES" | jq -r '.[] | " #\(.number) - \(.title) [\(.milestone.title)]"'
|
||||
echo ""
|
||||
echo "Priority P1 (High):"
|
||||
echo "$P1_ISSUES" | jq -r '.[] | " #\(.number) - \(.title) [\(.milestone.title)]"'
|
||||
echo ""
|
||||
echo "Priority P2 (Medium):"
|
||||
echo "$P2_ISSUES" | jq -r '.[] | " #\(.number) - \(.title) [\(.milestone.title)]"'
|
||||
```
|
||||
|
||||
Present top 3-5 recommendations:
|
||||
```
|
||||
Top recommendations:
|
||||
|
||||
1. #201 - Curriculum Framework (P1, S2) ✓ Specs ready
|
||||
2. #202 - Lesson Player (P1, S2) ✓ Specs ready
|
||||
3. #203 - Virtual Laboratory System (P2, S2) ⚠ Depends on #201
|
||||
|
||||
Which issue would you like to start? (Enter number)
|
||||
```
|
||||
|
||||
### 6. Read Full Issue Details
|
||||
|
||||
After user selects issue:
|
||||
|
||||
```bash
|
||||
ISSUE_NUMBER=201
|
||||
|
||||
# Read complete issue
|
||||
gh issue view $ISSUE_NUMBER
|
||||
|
||||
# Read ALL comments (including review suggestions)
|
||||
gh issue view $ISSUE_NUMBER --comments
|
||||
```
|
||||
|
||||
**IMPORTANT**: Pay special attention to review comments posted by `review-sprint`. These may include:
|
||||
- Architecture compliance suggestions
|
||||
- Wording and clarity improvements
|
||||
- Planning enhancements
|
||||
- Spec change recommendations
|
||||
|
||||
Consider these suggestions during implementation but use your judgment on how to apply them.
|
||||
|
||||
### 7. Extract and Validate Spec References
|
||||
|
||||
```bash
|
||||
# Get issue body
|
||||
ISSUE_BODY=$(gh issue view $ISSUE_NUMBER --json body --jq .body)
|
||||
|
||||
# Extract affected specs
|
||||
AFFECTED_SPECS=$(echo "$ISSUE_BODY" | rg "Affected Specs" -A 10 | rg "docs/specs/[^)]+")
|
||||
|
||||
# Verify each spec exists
|
||||
echo "Validating spec references..."
|
||||
for SPEC_PATH in $AFFECTED_SPECS; do
|
||||
if [ -f "$SPEC_PATH" ]; then
|
||||
echo "✓ Found: $SPEC_PATH"
|
||||
else
|
||||
echo "✗ Missing: $SPEC_PATH"
|
||||
echo ""
|
||||
echo "⚠ Spec not found. Run 'init-spec' to create it first."
|
||||
exit 1
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### 8. Check Related Issues and Dependencies
|
||||
|
||||
```bash
|
||||
# Look for "Related Issues" section in issue body
|
||||
RELATED_ISSUES=$(echo "$ISSUE_BODY" | rg "Related Issues" -A 5 | rg "#[0-9]+" -o)
|
||||
|
||||
if [ -n "$RELATED_ISSUES" ]; then
|
||||
echo "=== Related Issues ==="
|
||||
for RELATED in $RELATED_ISSUES; do
|
||||
RELATED_NUM=$(echo "$RELATED" | tr -d '#')
|
||||
RELATED_STATE=$(gh issue view $RELATED_NUM --json state --jq .state)
|
||||
RELATED_TITLE=$(gh issue view $RELATED_NUM --json title --jq .title)
|
||||
|
||||
if [ "$RELATED_STATE" = "OPEN" ]; then
|
||||
echo "⚠ $RELATED - $RELATED_TITLE (OPEN - may be dependency)"
|
||||
else
|
||||
echo "✓ $RELATED - $RELATED_TITLE (CLOSED)"
|
||||
fi
|
||||
done
|
||||
fi
|
||||
|
||||
# Check for blocking issues
|
||||
BLOCKING=$(echo "$ISSUE_BODY" | rg -i "blocked by|depends on" -A 2)
|
||||
if [ -n "$BLOCKING" ]; then
|
||||
echo ""
|
||||
echo "⚠ Warning: This issue may have dependencies:"
|
||||
echo "$BLOCKING"
|
||||
echo ""
|
||||
read -p "Continue anyway? (y/n) " -n 1 -r
|
||||
echo
|
||||
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
|
||||
echo "Aborted. Select a different issue."
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
```
|
||||
|
||||
### 9. Read Affected Specs
|
||||
|
||||
```bash
|
||||
echo "=== Reading Affected Specs ==="
|
||||
for SPEC_PATH in $AFFECTED_SPECS; do
|
||||
echo ""
|
||||
echo "--- $SPEC_PATH ---"
|
||||
cat "$SPEC_PATH"
|
||||
echo ""
|
||||
done
|
||||
|
||||
# If spec has design.md, read it too
|
||||
for SPEC_PATH in $AFFECTED_SPECS; do
|
||||
SPEC_DIR=$(dirname "$SPEC_PATH")
|
||||
DESIGN_PATH="$SPEC_DIR/design.md"
|
||||
|
||||
if [ -f "$DESIGN_PATH" ]; then
|
||||
echo "--- $DESIGN_PATH ---"
|
||||
cat "$DESIGN_PATH"
|
||||
echo ""
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
### 10. Read Development Retrospective
|
||||
|
||||
Read accumulated learnings to inform implementation:
|
||||
|
||||
```bash
|
||||
if [ -f "RETROSPECTIVE.md" ]; then
|
||||
echo ""
|
||||
echo "=== Development Retrospective ==="
|
||||
cat RETROSPECTIVE.md
|
||||
echo ""
|
||||
echo "Consider these learnings during implementation:"
|
||||
echo " - Apply success patterns from recent issues"
|
||||
echo " - Avoid known friction points"
|
||||
echo " - Reference well-specified capabilities"
|
||||
echo " - Follow active improvement initiatives"
|
||||
echo ""
|
||||
elif [ -f "docs/RETROSPECTIVE.md" ]; then
|
||||
echo ""
|
||||
echo "=== Development Retrospective ==="
|
||||
cat docs/RETROSPECTIVE.md
|
||||
echo ""
|
||||
echo "Consider these learnings during implementation."
|
||||
echo ""
|
||||
else
|
||||
echo ""
|
||||
echo "ℹ No RETROSPECTIVE.md found (this is normal for first few issues)"
|
||||
echo ""
|
||||
fi
|
||||
```
|
||||
|
||||
**Purpose**: The retrospective captures:
|
||||
- **Recent patterns**: What worked/didn't work in last 3-5 issues
|
||||
- **Historical wisdom**: Compressed learnings from earlier issues
|
||||
- **Spec quality**: Which specs are good references vs need improvement
|
||||
- **Active improvements**: Current process improvements being tracked
|
||||
|
||||
This context helps avoid repeating past mistakes and apply proven patterns.
|
||||
|
||||
### 11. Create Feature Branch
|
||||
|
||||
```bash
|
||||
# Extract title and create kebab-case branch name
|
||||
TITLE=$(gh issue view $ISSUE_NUMBER --json title --jq .title)
|
||||
KEBAB_TITLE=$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | sed -E 's/[^a-z0-9]+/-/g;s/^-|-$//g' | cut -c1-40)
|
||||
|
||||
# Determine branch prefix from change type
|
||||
CHANGE_TYPE=$(echo "$ISSUE_BODY" | rg "\[x\] (ADDED|MODIFIED|REMOVED)" -o -r '$1')
|
||||
|
||||
case "$CHANGE_TYPE" in
|
||||
"ADDED")
|
||||
PREFIX="feat"
|
||||
;;
|
||||
"MODIFIED")
|
||||
PREFIX="feat" # or "refactor" depending on scope
|
||||
;;
|
||||
"REMOVED")
|
||||
PREFIX="refactor"
|
||||
;;
|
||||
*)
|
||||
# Infer from labels
|
||||
if echo "$ISSUE_BODY" | rg -q "type:bug"; then
|
||||
PREFIX="fix"
|
||||
elif echo "$ISSUE_BODY" | rg -q "type:chore"; then
|
||||
PREFIX="chore"
|
||||
else
|
||||
PREFIX="feat"
|
||||
fi
|
||||
;;
|
||||
esac
|
||||
|
||||
BRANCH_NAME="${PREFIX}/${ISSUE_NUMBER}-${KEBAB_TITLE}"
|
||||
|
||||
# Create and switch to branch
|
||||
git switch -c "$BRANCH_NAME"
|
||||
|
||||
echo "✓ Created and switched to: $BRANCH_NAME"
|
||||
```
|
||||
|
||||
### 12. Initial Setup
|
||||
|
||||
Check if any setup is needed:
|
||||
|
||||
```bash
|
||||
# Check if package.json changed recently (might need npm install)
|
||||
MAIN_PACKAGE_DATE=$(git log -1 --format="%ai" main -- package.json 2>/dev/null)
|
||||
if [ -n "$MAIN_PACKAGE_DATE" ]; then
|
||||
echo "Note: package.json was updated recently ($MAIN_PACKAGE_DATE)"
|
||||
echo "Running npm install..."
|
||||
npm install
|
||||
fi
|
||||
|
||||
# Check if Prisma schema exists (might need generate)
|
||||
if [ -f "prisma/schema.prisma" ]; then
|
||||
echo "Note: Prisma schema detected"
|
||||
echo "Running npx prisma generate..."
|
||||
npx prisma generate
|
||||
fi
|
||||
|
||||
# Check for other setup scripts
|
||||
if [ -f "scripts/setup.sh" ]; then
|
||||
echo "Note: Found setup script"
|
||||
echo "Running scripts/setup.sh..."
|
||||
bash scripts/setup.sh
|
||||
fi
|
||||
```
|
||||
|
||||
### 13. Update TODO.md
|
||||
|
||||
Add issue to "In Progress" section:
|
||||
|
||||
```markdown
|
||||
## In Progress
|
||||
|
||||
- [ ] #201 - Curriculum Framework (feat/201-curriculum-framework)
|
||||
- **Started**: 2025-10-21
|
||||
- **Branch**: feat/201-curriculum-framework
|
||||
- **Specs**: docs/specs/curriculum-management/spec.md
|
||||
- **Priority**: P1
|
||||
- **Milestone**: S2
|
||||
```
|
||||
|
||||
If TODO.md doesn't have "In Progress" section, create it:
|
||||
|
||||
```bash
|
||||
# Check if section exists
|
||||
if ! grep -q "## In Progress" TODO.md; then
|
||||
# Add section after sprint section
|
||||
sed -i '/^## Phase/a \\n## In Progress\n' TODO.md
|
||||
fi
|
||||
|
||||
# Add issue entry
|
||||
cat >> TODO.md << EOF
|
||||
|
||||
- [ ] #${ISSUE_NUMBER} - ${TITLE} (${BRANCH_NAME})
|
||||
- **Started**: $(date +%Y-%m-%d)
|
||||
- **Branch**: ${BRANCH_NAME}
|
||||
- **Specs**: ${AFFECTED_SPECS}
|
||||
- **Priority**: ${PRIORITY}
|
||||
- **Milestone**: ${MILESTONE}
|
||||
EOF
|
||||
```
|
||||
|
||||
### 14. Update Sprint File
|
||||
|
||||
Find the relevant sprint file and update story status:
|
||||
|
||||
```bash
|
||||
# Find sprint file (match milestone to sprint file)
|
||||
MILESTONE=$(gh issue view $ISSUE_NUMBER --json milestone --jq .milestone.title)
|
||||
SPRINT_NUM=$(echo "$MILESTONE" | rg "S([0-9]+)" -o -r '$1')
|
||||
SPRINT_FILE="docs/sprint/S${SPRINT_NUM}.md"
|
||||
|
||||
if [ -f "$SPRINT_FILE" ]; then
|
||||
# Find the story section and update status
|
||||
# This is complex; in practice, manually update the file
|
||||
echo "Update $SPRINT_FILE:"
|
||||
echo " - Find story section for: $TITLE"
|
||||
echo " - Add: **Status**: In Progress"
|
||||
echo " - Add: **Branch**: $BRANCH_NAME"
|
||||
echo " - Add: **Started**: $(date +%Y-%m-%d)"
|
||||
fi
|
||||
```
|
||||
|
||||
Example sprint file update:
|
||||
|
||||
```markdown
|
||||
## Curriculum Framework
|
||||
|
||||
**User Story**: As an educator...
|
||||
|
||||
**Status**: In Progress
|
||||
**Branch**: feat/201-curriculum-framework
|
||||
**Started**: 2025-10-21
|
||||
**Issue**: #201
|
||||
```
|
||||
|
||||
### 15. Provide Summary
|
||||
|
||||
```
|
||||
✓ Started work on issue #201
|
||||
|
||||
Issue: Curriculum Framework
|
||||
Branch: feat/201-curriculum-framework
|
||||
Priority: P1
|
||||
Milestone: S2
|
||||
|
||||
Affected specs:
|
||||
- docs/specs/curriculum-management/spec.md
|
||||
|
||||
Review comments: 1 comment (review suggestions available)
|
||||
|
||||
Next steps:
|
||||
1. Review issue comments and review suggestions
|
||||
2. Review spec requirements and scenarios
|
||||
3. Implement according to acceptance criteria (considering review feedback)
|
||||
4. Write tests per test plan
|
||||
5. Run 'test-issue' before submitting
|
||||
6. Run 'submit-issue' when ready for PR
|
||||
|
||||
Dependencies to watch:
|
||||
- None identified
|
||||
|
||||
Happy coding! 🚀
|
||||
```
|
||||
|
||||
## Priority Order
|
||||
|
||||
Issues are recommended in this order:
|
||||
|
||||
1. **P0 - Critical**: Blocking bugs, production issues
|
||||
2. **P1 - High**: Important features, high-value work
|
||||
3. **P2 - Medium**: Standard features, improvements
|
||||
4. **P3 - Low**: Nice-to-have, technical debt
|
||||
|
||||
Within same priority:
|
||||
- Current sprint milestone before future sprints
|
||||
- Issues with ready specs before those needing spec work
|
||||
- Non-blocked issues before those with dependencies
|
||||
|
||||
## Dependency Checking
|
||||
|
||||
### Types of Dependencies
|
||||
|
||||
1. **Hard dependencies**: "Blocked by #123", "Depends on #123"
|
||||
- Must be completed first
|
||||
- Halt if not complete
|
||||
|
||||
2. **Soft dependencies**: "Related to #123", "See also #123"
|
||||
- Provide context but not blocking
|
||||
- Read for additional information
|
||||
|
||||
3. **Spec dependencies**: One spec depends on another
|
||||
- Check if dependency specs exist
|
||||
- Verify dependency requirements are clear
|
||||
|
||||
### Handling Blocked Issues
|
||||
|
||||
If selected issue is blocked:
|
||||
|
||||
```
|
||||
⚠ Issue #203 is blocked by #201 (Curriculum Framework)
|
||||
|
||||
#201 status: In Progress (50% complete)
|
||||
|
||||
Options:
|
||||
1. Wait for #201 to complete
|
||||
2. Select different issue
|
||||
3. Proceed with risk (may need rework)
|
||||
|
||||
Recommendation: Select different issue and return to #203 later.
|
||||
```
|
||||
|
||||
## Spec Readiness Validation
|
||||
|
||||
Before starting work, ensure:
|
||||
|
||||
- [ ] All referenced specs exist in `docs/specs/`
|
||||
- [ ] Specs have clear requirements
|
||||
- [ ] Each requirement has scenarios
|
||||
- [ ] Dependencies between specs are documented
|
||||
- [ ] Design docs exist for complex changes
|
||||
|
||||
If spec is incomplete:
|
||||
1. Consider running `init-spec` to complete it
|
||||
2. Or flag issue for spec refinement before starting
|
||||
|
||||
## File Update Patterns
|
||||
|
||||
### TODO.md Format
|
||||
|
||||
```markdown
|
||||
## In Progress
|
||||
|
||||
- [ ] #201 - Curriculum Framework (feat/201-curriculum-framework)
|
||||
- **Started**: 2025-10-21
|
||||
- **Branch**: feat/201-curriculum-framework
|
||||
- **Specs**: docs/specs/curriculum-management/spec.md
|
||||
- **Priority**: P1
|
||||
- **Milestone**: S2
|
||||
- **Dependencies**: None
|
||||
```
|
||||
|
||||
### Sprint File Format
|
||||
|
||||
```markdown
|
||||
## Curriculum Framework
|
||||
|
||||
**User Story**: As an educator, I want to define course structures...
|
||||
|
||||
**Acceptance Criteria**:
|
||||
- Course hierarchy supported
|
||||
- Learning objectives trackable
|
||||
|
||||
**Status**: In Progress
|
||||
**Branch**: feat/201-curriculum-framework
|
||||
**Started**: 2025-10-21
|
||||
**Issue**: #201
|
||||
**Assigned**: @username
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Dirty Working Directory
|
||||
|
||||
```
|
||||
⚠ Error: Uncommitted changes detected
|
||||
|
||||
Please commit or stash changes before starting new issue:
|
||||
git add .
|
||||
git commit -m "wip: save progress"
|
||||
# or
|
||||
git stash
|
||||
|
||||
Then run 'next-issue' again.
|
||||
```
|
||||
|
||||
### Not on Main Branch
|
||||
|
||||
```
|
||||
⚠ Error: Currently on branch: feat/123-old-issue
|
||||
|
||||
Please finish current work first:
|
||||
1. Complete implementation
|
||||
2. Run 'submit-issue' to create PR
|
||||
3. Or: git switch main (to abandon work)
|
||||
|
||||
Then run 'next-issue' again.
|
||||
```
|
||||
|
||||
### Missing Specs
|
||||
|
||||
```
|
||||
⚠ Error: Spec not found
|
||||
docs/specs/curriculum-management/spec.md
|
||||
|
||||
Issue #201 references specs that don't exist yet.
|
||||
|
||||
Action required:
|
||||
1. Run: init-spec curriculum-management
|
||||
2. Create spec.md with requirements
|
||||
3. Run 'next-issue' again
|
||||
```
|
||||
|
||||
### No Available Issues
|
||||
|
||||
```
|
||||
ℹ No issues assigned to you.
|
||||
|
||||
Possible actions:
|
||||
1. Check sprint backlog in GitHub
|
||||
2. Assign yourself an issue from current sprint
|
||||
3. Run 'seed-sprint' to create new issues
|
||||
4. Contact Scrum Master for assignment
|
||||
```
|
||||
|
||||
## Advanced: Context Caching
|
||||
|
||||
To optimize repeated API calls, consider caching:
|
||||
|
||||
```bash
|
||||
# Cache issue list for 5 minutes
|
||||
CACHE_FILE="/tmp/gh-issues-cache-$(date +%Y%m%d-%H%M).json"
|
||||
if [ ! -f "$CACHE_FILE" ]; then
|
||||
gh issue list --assignee @me --state open --json number,title,labels,milestone > "$CACHE_FILE"
|
||||
fi
|
||||
|
||||
# Use cached data
|
||||
ISSUES=$(cat "$CACHE_FILE")
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Always verify clean state before starting new work
|
||||
- Read all related issues for full context
|
||||
- Check spec completeness before implementation
|
||||
- Update tracking files immediately after branch creation
|
||||
- Consider dependencies when selecting issues
|
||||
- Prefer current sprint issues over future work
|
||||
- Validate specs exist and are complete
|
||||
- Note any setup requirements (npm install, prisma generate, etc.)
|
||||
108
issue-executor/scripts/work-on-issue.sh
Executable file
108
issue-executor/scripts/work-on-issue.sh
Executable file
@@ -0,0 +1,108 @@
|
||||
#!/bin/bash
|
||||
# This script manages the core development loop for a single issue.
|
||||
|
||||
set -e
|
||||
|
||||
usage() {
|
||||
echo "Usage: $0 <issue-number>"
|
||||
exit 1
|
||||
}
|
||||
|
||||
ISSUE_NUMBER=$1
|
||||
|
||||
if [ -z "$ISSUE_NUMBER" ]; then
|
||||
echo "Error: Issue number not provided." >&2
|
||||
usage
|
||||
fi
|
||||
|
||||
# --- VALIDATION ---
|
||||
if ! command -v jq &> /dev/null
|
||||
then
|
||||
echo "Error: jq is not installed. Please install it to continue." >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Starting work on Issue #$ISSUE_NUMBER..."
|
||||
|
||||
# 1. Verify clean git state
|
||||
echo "Verifying git status..."
|
||||
if [ -n "$(git status --porcelain)" ]; then
|
||||
echo "Error: Working directory is not clean. Please commit or stash changes." >&2
|
||||
exit 1
|
||||
fi
|
||||
echo "Git status is clean."
|
||||
|
||||
# 2. Synthesize Implementation Plan with Gemini
|
||||
echo "Synthesizing implementation plan for Issue #$ISSUE_NUMBER with Gemini..."
|
||||
|
||||
# 2a. Read issue details from GitHub
|
||||
echo "Fetching issue details..."
|
||||
ISSUE_JSON=$(gh issue view "$ISSUE_NUMBER" --json title,body)
|
||||
ISSUE_TITLE=$(echo "$ISSUE_JSON" | jq -r '.title')
|
||||
ISSUE_BODY=$(echo "$ISSUE_JSON" | jq -r '.body')
|
||||
|
||||
# 2b. Find all associated spec files
|
||||
echo "Finding associated spec files..."
|
||||
# This pattern finds all markdown files in docs/specs and docs/changes
|
||||
SPEC_FILES=$(echo "$ISSUE_BODY" | grep -o 'docs/\(specs\|changes\)/[^[:space:]`'"'"']*\.md' || true)
|
||||
|
||||
# 2c. Fetch issue comments
|
||||
echo "Fetching issue comments..."
|
||||
COMMENTS_JSON=$(gh issue view "$ISSUE_NUMBER" --json comments)
|
||||
COMMENTS=$(echo "$COMMENTS_JSON" | jq -r '.comments[] | "### Comment from @\(.author.login)\n\n\(.body)\n"')
|
||||
|
||||
# 2d. Construct the Gemini prompt
|
||||
GEMINI_PROMPT=""
|
||||
|
||||
if [ -n "$PARENT_EPIC_CONTEXT" ]; then
|
||||
GEMINI_PROMPT+="$PARENT_EPIC_CONTEXT\n\n"
|
||||
fi
|
||||
|
||||
GEMINI_PROMPT+="I am about to start work on GitHub issue #${ISSUE_NUMBER}. Here is all the context. Please provide a concise, step-by-step implementation plan.
|
||||
|
||||
**Issue Details:**
|
||||
Title: ${ISSUE_TITLE}
|
||||
Body:
|
||||
${ISSUE_BODY}
|
||||
"
|
||||
|
||||
# Add comments to prompt if they exist
|
||||
if [ -n "$COMMENTS" ]; then
|
||||
GEMINI_PROMPT+="\n**Issue Comments:**\n${COMMENTS}"
|
||||
fi
|
||||
|
||||
|
||||
# Add retrospective to prompt if it exists
|
||||
if [ -f "RETROSPECTIVE.md" ]; then
|
||||
GEMINI_PROMPT+="\n**Retrospective Learnings:**\n@RETROSPECTIVE.md"
|
||||
fi
|
||||
|
||||
# Add spec files to prompt
|
||||
if [ -n "$SPEC_FILES" ]; then
|
||||
GEMINI_PROMPT+="\n\n**Referenced Specifications:**"
|
||||
for spec in $SPEC_FILES; do
|
||||
if [ -f "$spec" ]; then
|
||||
GEMINI_PROMPT+="\n@$spec"
|
||||
fi
|
||||
done
|
||||
fi
|
||||
|
||||
# Add final instruction to prompt
|
||||
GEMINI_PROMPT+="\n\nBased on all this context, what are the key steps I should take to implement this feature correctly, keeping in mind past learnings and adhering to the specifications? Provide a clear, actionable plan."
|
||||
|
||||
# 2d. Call Gemini
|
||||
echo "------------------------- GEMINI IMPLEMENTATION PLAN -------------------------"
|
||||
gemini -p "$GEMINI_PROMPT"
|
||||
echo "----------------------------------------------------------------------------"
|
||||
echo "Context loaded and implementation plan generated."
|
||||
|
||||
# 3. Create a feature branch
|
||||
echo "Generating branch name..."
|
||||
# Sanitize title to create a branch name
|
||||
BRANCH_NAME=$(echo "$ISSUE_TITLE" | tr '[:upper:]' '[:lower:]' | sed -e 's/task: //g' -e 's/[^a-z0-9]/-/g' -e 's/--/-/g' -e 's/^-//' -e 's/-$//')
|
||||
BRANCH_NAME="feat/$ISSUE_NUMBER-$BRANCH_NAME"
|
||||
|
||||
echo "Creating new branch: $BRANCH_NAME..."
|
||||
git checkout -b "$BRANCH_NAME"
|
||||
|
||||
echo "Setup complete. You are now on branch '$BRANCH_NAME' and ready to implement Issue #$ISSUE_NUMBER."
|
||||
Reference in New Issue
Block a user