pick-issue-and-plan-claude

name

pick-issue-and-plan-claude

description

Discovers open GitHub issues via GitHub MCP (list_issues on user-github) or gh CLI, excludes issues with labels AIIGNORE or FUTUREWORK, prioritizes maint over feat, picks one, analyzes the repo and issue, writes a detailed implementation plan to .claude/workplans/Pending/, commits that plan on the current branch, then sets the issue to "not planned" (closed, state_reason not_planned). Prefer GitHub MCP over gh CLI. Use when the user says "pick an issue and plan", "pick issue and plan", "plan next issue", "choose issue and create plan", or "pick from GitHub issues and plan".

Pick Issue and Plan

Discovers open GitHub issues via the GitHub MCP server (tools list_issues, issue_read, and issue_write on server user-github) or, if MCP is unavailable, via gh issue list / gh issue view / gh issue close. Issues are tagged by title prefix or label (maint: / feat:); the skill prioritizes maint over feat, picks one, analyzes the codebase and that issue, uses context7 to fetch appropriate docs and writes a detailed implementation plan to .claude/workplans/Pending/<slug>.md, commits that plan on the current branch, then sets the picked issue to not planned (closed with state_reason: not_planned). The plan references which existing skills to use (e.g. add-plugin-test, smart-test-runner, review-plugin, check-test-logical-resp). The skill does not run tests or apply code edits; it produces the plan file, commits it, and updates the issue state.

When to Apply

• User says: "pick an issue and plan", "pick issue and plan", "plan next issue", "choose issue and create plan", "pick from GitHub issues and plan"
• User wants to turn a GitHub issue into an actionable implementation plan with skill references

Prerequisites

• GitHub issues source: Prioritize the GitHub MCP server (server user-github). Always use list_issues, issue_read, and issue_write first; use gh CLI only when the MCP server is unavailable or a call fails.
• Owner/repo: Use the current repository’s owner and repo name (e.g. from git remote get-url origin: https://github.com/dezverev/AnimalAL-v1.git → owner dezverev, repo AnimalAL-v1).
• Issue tags: Issues are classified by title prefix (maint: or feat:, case-insensitive) or by labels maint / feat. Unclassified issues are skipped or treated as lower priority.
• Ignore labels: Exclude from consideration any issue that has a label AIIGNORE or FUTUREWORK (case-insensitive). Do not plan or pick such issues.

Workflow

1. Discover issues (GitHub)

Preferred: GitHub MCP server

1. Resolve owner and repo from the current repository (e.g. git remote get-url origin or project context; e.g. dezverev, AnimalAL-v1).
2. Call the list_issues MCP tool on server user-github with:
   • owner (required): repository owner
   • repo (required): repository name
   • state: "OPEN"
   • perPage: 100
   • Optional: orderBy: "UPDATED_AT", direction: "DESC" to get newest first.
3. Tool schema: mcps/user-github/tools/list_issues.json (read if needed for exact argument names).
4. From the response, for each issue capture: number, title, labels. The MCP response shape may use node.number, node.title, node.labels (or similar); normalize to number, title, labels for classification.
5. Exclude by label: Drop any issue whose labels include AIIGNORE or FUTUREWORK (case-insensitive). Do not plan or pick these issues.

Fallback: GitHub CLI

6. If the GitHub MCP server is unavailable or the list_issues call fails, run from the repo root: gh issue list --state open --limit 100. If gh fails too, report that and stop.
7. Classify each remaining issue:
   • maint if title starts with maint: (case-insensitive) or any label name equals maint (case-insensitive).
   • feat if title starts with feat: or any label name equals feat (case-insensitive).
   • Unclassified issues are skipped or treated as lower priority (document in plan if any exist).
   • Exclude by label: Do not include in the candidate list any issue whose labels include AIIGNORE or FUTUREWORK (case-insensitive).

Fetching issue body for the chosen issue

7. When building the plan for the picked issue, get full details (body, etc.):
   • Preferred: Call issue_read on server user-github with method "get", owner, repo, issue_number (the picked issue’s number). Schema: mcps/user-github/tools/issue_read.json.
   • Fallback: Run gh issue view <number> from the repo root.

2. Prioritize and pick one

1. Build an ordered list from issues not excluded by AIIGNORE/FUTUREWORK: all maint first (e.g. by issue number or updated date), then all feat.
2. Pick: the first item in that list.
3. If the list is empty, report "No open issues with maint: or feat: (or labels maint/feat), or all candidates were excluded (AIIGNORE/FUTUREWORK)" and stop.

3. Analyze codebase and issue

1. Issue: Use title, body, and labels of the chosen issue to understand scope (e.g. "maint: fix disposal in NestedFetchPlugin"). Fetch body via issue_read (user-github, method=get, owner, repo, issue_number) or gh issue view <number> if not already present from the list response.
2. Codebase: Use Read, List, Grep to inspect relevant areas:
   • Paths implied by the issue (e.g. src/Plugins/NestedKernel/SK/NestedFetchPlugin.cs, src/AnimalKernel/Core/StandardKernel.cs, src/IntegrationTesterApp/TestCaseDefinitions.cs).
   • Conventions from CLAUDE.md and project docs (test workflow, plugin layout, provider pattern).
3. Context7 If available use the context7 mcp to fetch any relevant docs to aid in implementation.

4. Map to available skills

1. List .claude/skills/ and read each skill's frontmatter (name, description).
2. For the chosen issue, decide which skills apply at which step of the plan (e.g. review-plugin before editing, add-plugin-test when adding tests, smart-test-runner for running tests, check-test-logical-resp after a run).
3. Include this mapping in the written plan as a "Skills to use (in order)" section.

5. Write plan to Pending

1. Directory: .claude/workplans/Pending/. Create it if it does not exist.
2. Filename: Slug from the issue for stability and uniqueness, e.g. issue-42-fix-disposal-nested-fetch.md or maint-fix-disposal-nested-fetch.md. Include issue number when available.
3. Content: Use the plan document template below. Fill every section from the chosen issue and analysis.

6. Commit the plan on the current branch

1. Stage the new plan file: git add .claude/workplans/Pending/<slug>.md (use the same <slug> as in step 5).
2. Commit on the current branch with a descriptive message, e.g.: git commit -m "plan: add issue-<n>-<short-slug> to Pending" or git commit -m "plan: <issue number> <short title>". Keep the message concise and identifiable (issue number + brief slug/title).
3. If the working tree has other uncommitted changes, stage only the plan file so the commit contains only the new plan. If the user explicitly wants all changes committed, follow that; otherwise commit only the plan.

7. Set issue to not planned

1. After the plan file is written and committed, set the picked GitHub issue to not planned so it is no longer tracked as an open issue (the work is captured in the plan).
2. Prioritize GitHub MCP: Call issue_write on server user-github with:
   • method: "update"
   • owner, repo: same as used for list_issues/issue_read
   • issue_number: the picked issue’s number
   • state: "closed"
   • state_reason: "not_planned"
3. Tool schema: mcps/user-github/tools/issue_write.json (read if needed for exact argument names).
4. Fallback: If the GitHub MCP server is unavailable or the call fails, run from the repo root: gh issue close <number> --reason "not planned". If gh fails, report it but do not block delivery of the plan; the plan file is still the primary output.

Plan document template

Use this structure when writing the plan file. Replace placeholders with values from the chosen issue and analysis.

# Implementation plan: [Issue title]

## Issue
- **Number**: #<n>
- **Title**: <title>
- **Link**: <url if available, e.g. from gh repo view or https://github.com/<owner>/<repo>/issues/<n>>
- **Summary**: <one sentence>

## Why this issue
- **Priority**: maint | feat
- **Selection**: First in prioritized list (maint first, then feat).

## Scope
- **Affected areas**: <paths / components>
- **Key files**: <list>

## Implementation steps
1. <step> — Use skill: **<skill-name>** ([.claude/skills/<name>/SKILL.md](.claude/skills/<name>/SKILL.md))
2. …
3. Run tests / logical check — **smart-test-runner**, then **check-test-logical-resp**

## Skills to use (in order)
| Step | Skill | When |
|------|-------|------|
| 1 | … | … |
| 2 | … | … |

## References
- <paths and doc links, e.g. StandardKernel.cs, TestCaseDefinitions.cs, CLAUDE.md>

Dependencies and constraints

• GitHub MCP server: Prioritize calling list_issues, issue_read, and issue_write on server user-github (tools in mcps/user-github/tools/). Use owner/repo from the current repository.
• Fallback: If the GitHub MCP server is unavailable or the call fails, use gh issue list --state open --limit 100 and gh issue view <number> from the repo root (requires gh installed and repo linked).
• Discovery and one GitHub write: Listing and viewing issues are done via MCP or gh. The only file edits are writing the plan under .claude/workplans/Pending/. After the plan is written, it is committed on the current branch (stage only the plan file; commit message e.g. plan: add issue-<n>-<slug> to Pending). Then the picked issue is updated via issue_write (or gh issue close --reason "not planned") to closed / not_planned so it is no longer tracked as open.
• No execution: The skill produces the plan file and sets the issue to not planned. It does not run tests or apply code edits; the user or a follow-up agent runs the plan.

Paths reference

• Plan output: .claude/workplans/Pending/<slug>.md
• GitHub MCP tools: mcps/user-github/tools/list_issues.json, mcps/user-github/tools/issue_read.json, mcps/user-github/tools/issue_write.json (server user-github).
• Skills directory: .claude/skills/
• Conventions / dev guide: CLAUDE.md
• Kernel: src/AnimalKernel/Core/StandardKernel.cs
• Test definitions: src/IntegrationTesterApp/TestCaseDefinitions.cs
• Plugins: src/Plugins/Base/SK/, src/Plugins/NestedKernel/SK/

Relation to other skills and MCP

• GitHub MCP server (user-github): Use list_issues to pull open issues, issue_read (method=get) to get full details for the chosen issue, and issue_write (method=update, state=closed, state_reason=not_planned) to set the issue to not planned after the plan is written and committed. Prefer MCP over gh when the server is available.
• review-plugin, add-plugin-test, smart-test-runner, check-test-logical-resp: The plan references these by name and path so the executor knows which skill to run at each step.
• sync-dev-guide: Run after creating this skill (or any new skill) so it appears in CLAUDE.md; optionally mention this when delivering the skill.

Checklist before delivering

• Open issues obtained via list_issues (server user-github) with owner, repo, state=OPEN, perPage=100—or via gh issue list --state open --limit 100 if MCP unavailable; issues with labels AIIGNORE or FUTUREWORK excluded; remaining issues classified as maint/feat by title or labels.
• Prioritized list: maint first, then feat (excluding AIIGNORE/FUTUREWORK); one issue picked.
• For the picked issue, body/details obtained via issue_read (user-github, method=get) or gh issue view <number>.
• Codebase and issue analyzed (Read/List/Grep); scope and key files identified.
• Skills mapped from .claude/skills/ to implementation steps.
• .claude/workplans/Pending/ exists; plan written as <slug>.md with the template fully filled.
• Plan includes: Issue (number, title, link, summary), Why this issue, Scope, Implementation steps, Skills-to-use table, References.
• Plan committed on the current branch: git add .claude/workplans/Pending/<slug>.md and git commit -m "plan: …" (only the plan file; message includes issue number and short slug/title).
• Picked issue set to not planned via issue_write (user-github, method=update, state=closed, state_reason=not_planned) or gh issue close <number> --reason "not planned"; if the update fails, plan is still delivered and the failure is reported.