From c1ac8f72d6469f25947fd4de72abb350132f8077 Mon Sep 17 00:00:00 2001 From: Paul Holstein <44263169+holstein13@users.noreply.github.com> Date: Tue, 2 Dec 2025 10:21:37 -0500 Subject: [PATCH 1/2] feat: add resolving-github-issues skill MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Systematic workflow for analyzing and implementing fixes for GitHub issues: - Phase-based approach: Fetch → Analyze → Plan → Checkpoint → Implement - Feasibility assessment with complexity rating - Three determination paths: proceed, clarify, or beyond scope - User checkpoint before implementation (never auto-commit) - Safety measures and common mistakes documented 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- skills/resolving-github-issues/SKILL.md | 176 ++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 skills/resolving-github-issues/SKILL.md diff --git a/skills/resolving-github-issues/SKILL.md b/skills/resolving-github-issues/SKILL.md new file mode 100644 index 000000000..718345930 --- /dev/null +++ b/skills/resolving-github-issues/SKILL.md @@ -0,0 +1,176 @@ +--- +name: resolving-github-issues +description: Use when a GitHub issue URL or number is referenced and needs analysis, planning, or implementation - systematically fetches issue details, analyzes codebase impact, assesses feasibility, creates implementation plan, and executes fix with user approval at checkpoints +--- + +# Resolving GitHub Issues + +## Overview + +Systematic workflow for analyzing GitHub issues and implementing fixes. + +**Core principle:** Fetch → Analyze → Plan → Checkpoint → Implement → Verify + +**Announce at start:** "I'm using the resolving-github-issues skill to analyze and address this issue." + +## When to Use + +- User references a GitHub issue (URL or `#123`) +- Asked to "fix issue #X" or "look at issue #X" +- Need to understand scope before committing to work + +**Don't use for:** +- Creating new issues (use creating-github-issues skill) +- Issues in repos you don't have access to +- Vague requests without issue reference + +## The Process + +### Phase 1: Fetch Issue + +```bash +gh issue view --repo +``` + +Extract: title, description, labels, comments, acceptance criteria, related PRs. + +### Phase 2: Analyze Codebase + +```bash +git pull origin main # Ensure latest +``` + +Investigate: +- Files/code mentioned in issue +- Affected components and dependencies +- Related test files +- Recent commits: `git log --oneline -n 20 ` +- Similar fixes: `git log --grep=""` + +### Phase 3: Assess Feasibility + +Evaluate these dimensions: + +| Dimension | Question | +|-----------|----------| +| Clarity | Are requirements well-defined? | +| Scope | Can I identify all files needing changes? | +| Dependencies | Are required APIs/services accessible? | +| Testing | Can I verify the fix works? | +| Side Effects | Can I predict impacts? | +| Complexity | Rate 1-10 with reasoning | + +### Phase 4: Determine Path + +Make one of three determinations: + +**A. CAN PROCEED** (requirements clear, scope manageable) +``` +IMPLEMENTATION PLAN +Complexity: [1-10] +Files: [list with changes needed] + +Steps: +1. [Specific action] +2. [Next action] + +Testing: [How to verify] +Risks: [Potential issues] +``` + +**B. REQUIRES CLARIFICATION** (missing information) +``` +REQUIRES CLARIFICATION +Missing: [specific questions] +Suggested: [how to obtain info] +``` + +**C. BEYOND SCOPE** (too complex, blocked) +``` +COMPLEXITY WARNING +Reason: [why too complex] +Blockers: [specific blockers] +Recommended: [suggested approach] +``` + +### Phase 5: User Checkpoint + +**Always wait for approval before implementing:** + +- CAN PROCEED: "Ready to create branch and implement. Shall I continue?" +- REQUIRES CLARIFICATION: "Need more info. Want me to comment on the issue?" +- BEYOND SCOPE: "This needs [X]. Want me to document findings on issue?" + +### Phase 6: Implement (if approved) + +```bash +git checkout -b fix/issue-- +``` + +Follow plan step-by-step: +1. Make changes per plan +2. Run tests: `npm test` / `cargo test` / etc. +3. Verify no regressions +4. Create clear commit messages (conventional commits) + +### Phase 7: Complete + +```bash +git diff --stat # Show changes +``` + +Offer options: +- "Create PR with these changes?" +- "Run additional tests?" +- "Review changes together?" + +## Quick Reference + +| Phase | Action | Output | +|-------|--------|--------| +| 1. Fetch | `gh issue view` | Issue summary | +| 2. Analyze | Search codebase | Affected files list | +| 3. Assess | Evaluate dimensions | Feasibility rating | +| 4. Determine | Choose path | Plan/Clarification/Warning | +| 5. Checkpoint | Ask user | Approval to proceed | +| 6. Implement | Code changes | Working fix | +| 7. Complete | Show diff | PR or next steps | + +## Common Mistakes + +**Starting implementation without checkpoint** +- Problem: Wasted effort if approach is wrong +- Fix: Always present plan and wait for approval + +**Skipping codebase analysis** +- Problem: Miss dependencies, break other features +- Fix: Always check related files and recent commits + +**Underestimating complexity** +- Problem: Get stuck mid-implementation +- Fix: Be conservative in complexity ratings + +**Auto-committing or pushing** +- Problem: User loses control +- Fix: Never commit/push without explicit approval + +## Safety Measures + +**Never:** +- Auto-commit or push without approval +- Work directly on main/master +- Skip the user checkpoint +- Force-push without explicit request + +**Always:** +- Create feature branches +- Present plan before implementing +- Run tests before declaring done +- Show diff summary at completion + +## Integration + +**Pairs with:** +- **finishing-a-development-branch** - After implementation complete +- **systematic-debugging** - If issue involves complex bug +- **creating-github-issues** - For creating new issues (opposite workflow) From 3a45cf4c0c7ec7e4d00efd6be7860d1d4e115ac9 Mon Sep 17 00:00:00 2001 From: Paul Holstein <44263169+holstein13@users.noreply.github.com> Date: Tue, 2 Dec 2025 10:33:47 -0500 Subject: [PATCH 2/2] fix: address code review feedback MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add language specifiers (text) to fenced code blocks (lines 68, 82, 89) - Convert bold text to proper ### headings in Common Mistakes section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- skills/resolving-github-issues/SKILL.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/skills/resolving-github-issues/SKILL.md b/skills/resolving-github-issues/SKILL.md index 718345930..9ae09fd13 100644 --- a/skills/resolving-github-issues/SKILL.md +++ b/skills/resolving-github-issues/SKILL.md @@ -65,7 +65,7 @@ Evaluate these dimensions: Make one of three determinations: **A. CAN PROCEED** (requirements clear, scope manageable) -``` +```text IMPLEMENTATION PLAN Complexity: [1-10] Files: [list with changes needed] @@ -79,14 +79,14 @@ Risks: [Potential issues] ``` **B. REQUIRES CLARIFICATION** (missing information) -``` +```text REQUIRES CLARIFICATION Missing: [specific questions] Suggested: [how to obtain info] ``` **C. BEYOND SCOPE** (too complex, blocked) -``` +```text COMPLEXITY WARNING Reason: [why too complex] Blockers: [specific blockers] @@ -138,19 +138,19 @@ Offer options: ## Common Mistakes -**Starting implementation without checkpoint** +### Starting implementation without checkpoint - Problem: Wasted effort if approach is wrong - Fix: Always present plan and wait for approval -**Skipping codebase analysis** +### Skipping codebase analysis - Problem: Miss dependencies, break other features - Fix: Always check related files and recent commits -**Underestimating complexity** +### Underestimating complexity - Problem: Get stuck mid-implementation - Fix: Be conservative in complexity ratings -**Auto-committing or pushing** +### Auto-committing or pushing - Problem: User loses control - Fix: Never commit/push without explicit approval