Issue Setup Skill

Purpose

Transform a GitHub issue into a fully-prepared development environment with:

• Complete issue context and acceptance criteria
• Structured implementation plan (scratchpad)
• Feature branch ready for work
• Situational codebase awareness

Context Prerequisites

Before beginning, load critical project context:

Project Structure

Read the project's CLAUDE.md to understand:

• Module architecture
• Development philosophy
• Current sprint priorities
• Branch naming conventions

Codebase Orientation

Get a high-level view of the repository structure to identify affected areas.

Workflow Execution

Phase 0: Check Existing Context (Self-Correction)

Before proceeding with setup, check if work already initialized:

1. Detect existing scratchpad:

``bash # Look for SCRATCHPAD{issuenumber}.md ls SCRATCHPAD_*.md 2>/dev/null ``

1. If scratchpad exists:

``` ✓ Scratchpad already exists for this issue.

Delegating to do-work skill... ```

Then invoke: `` Skill: do-work args: "{issue_number}" ``

STOP here - don't proceed with setup.

1. If no scratchpad:

- Proceed to Phase 1 (normal setup flow)

Phase 1: Gather Context (Parallel)

Input: Issue reference in format owner/repo#number or just #number (uses current repo)

Examples:

• owner/repository#42
• #42 (assumes current repository)

Execute these operations in parallel for faster setup:

1. Repository Context:

- Determine owner/repo from input or git remote - Read project's CLAUDE.md for conventions - Check current git status and branch

1. Issue Details:

- Retrieve complete issue using GitHub tools: - Title, body (description), labels - State (open/closed), assignees - Milestone, project associations - All comments (especially implementation details) - Linked issues (mentions, closes, related)

1. Generate branch name (after issue fetched):

- Format: {issue-number}-{slugified-title} - Example: 42-implement-fact-batching - Sanitize title: lowercase, spaces→hyphens, remove special chars

1. Build issue context map:

- Is this part of a milestone/project? - Are there dependent issues (blocks/blocked-by)? - What's the priority based on labels? - Are there linked PRs already?

Phase 2: Analyze & Plan

Goal: Understand the issue deeply before writing any code.

Analysis Steps:

1. Requirements Review:

- Parse issue body for requirements/acceptance criteria - Check for task lists (- [ ] items) in issue body - Identify ambiguities or missing information - Note any conflicting requirements in comments

1. Codebase Investigation (Delegate to Scratchpad-Planner Agent):

For thorough codebase analysis, use the scratchpad-planner agent:

``` Skill: scratchpad-planner args: "issue #{number}: {issue title}

Summary: {brief issue summary}

Key requirements: {extract key requirements from issue body}

Affected areas (if known): {mention specific modules/components if issue indicates}

Repository: {owner/repo} Project context: See CLAUDE.md for module structure and conventions" ```

The scratchpad-planner agent will: - Read project's CLAUDE.md for conventions and structure - Search for relevant existing code patterns using Grep and LSP - Identify affected modules/components and integration points - Find similar implementations to learn from - Generate atomic task breakdown following project conventions - Ask clarifying questions for ambiguous requirements - Support resumable analysis for complex codebases

The agent replaces generic exploration with specialized planning expertise, providing more structured analysis and implementation approach generation.

1. Technical Breakdown:

- Break work into atomic, committable tasks - Identify integration points - Flag potential challenges - Estimate complexity/scope

1. Dependency Check:

- Does this require other issues first? (check "depends on" mentions) - Will this block other work? (check "blocks" mentions) - Are there API contract implications? - Check milestone dependencies

Phase 3: Create Scratchpad

Generate: SCRATCHPAD{issuenumber}.md

Template Structure:

# {Issue Title} - #{issue_number}

## Issue Details
- **Repository:** {owner/repo}
- **GitHub URL:** {issue_url}
- **State:** {open/closed}
- **Labels:** {labels}
- **Milestone:** {milestone if exists}
- **Assignees:** {assignees}
- **Related Issues:** {linked issues if any}
  - Depends on: #{issue_numbers}
  - Blocks: #{issue_numbers}
  - Related: #{issue_numbers}

## Description
{full issue body from GitHub}

## Acceptance Criteria
{extract task list from issue body, or create from description}
- [ ] {criterion 1}
- [ ] {criterion 2}
- [ ] {criterion 3}

## Branch Strategy
- **Base branch:** main (or develop-ts/develop if exists)
- **Feature branch:** {issue_number}-{slugified-title}
- **Current branch:** {git branch --show-current}

## Implementation Checklist

### Setup
- [ ] Fetch latest from base branch
- [ ] Create and checkout feature branch

### Implementation Tasks
{Break down into atomic commits - each should be independently reviewable}

- [ ] {First atomic task with clear scope}
  - Files affected: {list}
  - Why: {brief rationale}
  
- [ ] {Second atomic task}
  - Files affected: {list}
  - Why: {brief rationale}

{Continue with granular breakdown...}

### Quality Checks
- [ ] Run linter/type checker
- [ ] Execute relevant tests
- [ ] Self-review for code quality
- [ ] Verify acceptance criteria met

### Documentation
- [ ] Update relevant README/docs (if applicable)
- [ ] Add inline comments for complex logic (if applicable)

## Technical Notes

### Architecture Considerations
{Any architectural decisions to consider}
{Module boundaries to respect}
{Integration points to handle}

### Implementation Approach
{High-level strategy for solving the problem}
{Why this approach vs alternatives}

### Potential Challenges
{Known complexity areas}
{Technical debt to navigate}
{Performance considerations}

## Questions/Blockers

### Clarifications Needed
{List any unclear requirements}
{Ambiguities in issue description}

### Blocked By
{List any dependencies not yet complete - reference issue numbers}

### Assumptions Made
{Document assumptions if requirements unclear}

### Decisions Made
{Populated during Phase 3.5 Interactive Q&A}
{Format: Q: question → A: decision (rationale)}

## Work Log

{This section fills in during execution via /start-work}
{Each work session adds dated entries}

---
**Generated:** {timestamp}
**By:** Issue Setup Skill
**Source:** {github_issue_url}

Scratchpad Quality Guidelines:

• Atomic tasks: Each checklist item should be one commit
• Clear scope: Reader should understand what each task does
• Testable: Acceptance criteria should be verifiable
• Realistic: Don't over-engineer or under-scope
• Contextual: Reference project-specific conventions

Phase 3.5: Interactive Q&A (Resolve Clarifications)

Goal: Resolve any questions or ambiguities before starting implementation.

Trigger: If the scratchpad has items in the "Clarifications Needed" section.

Process:

1. Check for Outstanding Questions:

- Review the Questions/Blockers section of the scratchpad - If "Clarifications Needed" is empty, skip to Phase 4 - If questions exist, proceed with interactive resolution

1. Present Questions via AskUserQuestion:

For each clarification needed, use the AskUserQuestion tool to get user input:

`` AskUserQuestion: question: "{The specific clarification question}" header: "Clarify" options: - label: "{Option A}" description: "{What this choice means}" - label: "{Option B}" description: "{What this choice means}" - label: "{Option C}" (if applicable) description: "{What this choice means}" multiSelect: false (or true if multiple answers valid) ``

Guidelines for presenting questions: - Frame questions clearly with context - Provide 2-4 concrete options when possible - Include descriptions explaining implications of each choice - User can always select "Other" for custom input - Group related questions if they have dependencies

1. Update Scratchpad with Decisions:

After collecting all answers, update the scratchpad:

a) Add "Decisions Made" section (if not present) under Questions/Blockers: ```markdown ### Decisions Made {Timestamp}

Q: {Original question} A: {User's answer/decision} Rationale: {Brief explanation of why, if provided} ```

b) Remove resolved items from "Clarifications Needed"

c) Update relevant sections if decisions affect: - Implementation tasks (add/remove/modify based on decisions) - Technical approach - Assumptions (convert to confirmed decisions)

1. Confirm Resolution:

Display summary of decisions made: ``` ✓ Resolved {N} clarifications:

1. {Question summary} → {Decision} 2. {Question summary} → {Decision} ...

📋 SCRATCHPAD updated with decisions. ```

Example Interaction:

📋 SCRATCHPAD_42.md has 3 clarifications that need resolution before proceeding.

[AskUserQuestion 1/3]
Question: "Should we keep commands as aliases during the transition to skills?"
Header: "Migration"
Options:
  - "Keep as thin wrappers" - Commands remain but delegate to skills
  - "Remove immediately" - Clean break, skills only
  - "Decide per-command" - Evaluate each command individually

[User selects: "Keep as thin wrappers"]

[AskUserQuestion 2/3]
Question: "How should prime-session be handled?"
Header: "Behavior"
Options:
  - "Convert to auto-invoke skill" - Activates when entering new repo
  - "Keep as explicit command" - User must invoke manually
  - "Remove entirely" - Claude reads CLAUDE.md automatically anyway

[User selects: "Keep as explicit command"]

...

✓ Resolved 3 clarifications:

1. Migration strategy → Keep commands as thin wrappers
2. prime-session behavior → Keep as explicit command
3. ...

📋 SCRATCHPAD_42.md updated with decisions.
Proceeding to branch creation...

Skip Conditions:

• No items in "Clarifications Needed" → Skip directly to Phase 3.6
• User explicitly requests to skip → Note unresolved questions, proceed with assumptions

Phase 3.6: Plan Approval

Goal: Get explicit user approval of the implementation plan before preparing the workspace.

This mirrors Claude's EnterPlanMode/ExitPlanMode approval pattern — the user reviews and signs off on the plan before any workspace changes.

1. Present Plan Summary:

``` 📋 SCRATCHPAD{issuenumber}.md ready for review:

{X} implementation tasks {Y} quality checks {Z} decisions resolved

Key changes: - {Brief summary of major tasks} ```

1. Request Approval:

`` AskUserQuestion: question: "Approve this implementation plan?" header: "Plan" options: - label: "Approve" description: "Plan looks good, create branch and proceed" - label: "Revise plan" description: "Re-run planning with adjusted focus" - label: "Let me review" description: "I'll read the scratchpad first, then decide" ``

1. Handle Response:

- Approve: Proceed to Phase 4 - Revise plan: Resume scratchpad-planner agent with user feedback, then return to Phase 3.6 - Let me review: Wait for user to read SCRATCHPAD, then re-ask approval

This phase is NOT skippable. The user must explicitly approve before workspace preparation begins.

Phase 4: Prepare Workspace

Branch Creation:

1. Detect base branch:

```bash # Check what branches exist git fetch origin

# Prefer in this order: # 1. develop-ts (if exists) # 2. develop (if exists) # 3. main (default) git branch -r | grep -E 'origin/(develop-ts|develop|main)' ```

1. Create feature branch:

```bash # Generate branch name from issue # Format: {issue_number}-{slugified-title} # Example: 42-implement-fact-batching

git branch {issue-number}-{slugified-title} origin/{base-branch} # Don't checkout yet - let operator decide when to switch ```

1. Confirm creation:

``bash git branch --list {branch-name} ``

Final Output:

Display concise summary:

✓ Issue #{issue_number} analyzed and prepared

📋 SCRATCHPAD_{issue_number}.md created with:
   - {X} implementation tasks
   - {Y} quality checks
   - {Z} decisions made (via Q&A)

🌿 Branch '{issue-number}-{slugified-title}' created from {base-branch}

🔗 GitHub Issue: {issue_url}

🚀 Ready to begin work:
   git checkout {branch-name}
   # Then start implementation

Note: If clarifications were resolved in Phase 3.5, the scratchpad now contains confirmed decisions rather than open questions. All ambiguities should be resolved before reaching this point.

Project-Specific Adaptations

For UI/Frontend Projects:

Component Context:

• Which components affected?
• State management implications?
• API contract dependencies?

For API/Backend Projects:

Contract Context:

• API endpoints added/modified?
• Breaking changes?
• Database migrations needed?

Error Handling

Issue Not Found

If GitHub issue doesn't exist:

• Verify issue number and repository
• Check if issue is in different repo
• Offer to search issues by title/keyword
• Confirm you have access to private repos (if applicable)

Insufficient Information

If issue lacks description or clear scope:

• Note this prominently in Questions/Blockers
• Suggest adding task list to issue before starting work
• Don't guess - make assumptions explicit
• Consider commenting on issue to request clarification

Branch Already Exists

If feature branch already exists:

• Check if work in progress (git log)
• Offer to resume vs. create new branch
• Warn about potential conflicts
• Suggest reviewing existing commits

Repository Access Issues

If can't access repository:

• Verify GitHub authentication (gh auth status)
• Check repository exists (might be private)
• Confirm repository name spelling
• Ensure gh CLI is installed and configured

Integration with Other Skills

Flows to:

• /start-work {issue_number} - Begin execution from scratchpad
• /commit - Make atomic commits as checklist progresses

Receives context from:

• Project CLAUDE.md - Architecture and conventions
• /prime-session - Current development priorities

Best Practices

✅ DO:

• Read acceptance criteria carefully
• Break work into truly atomic commits
• Flag ambiguities early
• Research codebase before planning
• Make scratchpad detailed but scannable
• Document assumptions explicitly

❌ DON'T:

• Start coding before scratchpad approved
• Skip Phase 3.6 plan approval — user must sign off before branch creation
• Guess at unclear requirements
• Create tasks too large to review
• Skip codebase investigation
• Over-engineer the plan
• Hide complexity in vague task descriptions

Operator Interaction Points

Before Scratchpad Creation: If issue is complex or ambiguous, ask:

• "This issue affects multiple modules. Should we break it into sub-issues?"
• "Acceptance criteria unclear on X. Should we clarify before planning?"

After Scratchpad Created (Phase 3.6): Explicit approval required — handled by Phase 3.6 Plan Approval step. User must approve, request revision, or review before branch creation proceeds.

Before Branch Creation: Confirm readiness:

• "Base branch develop-ts is 5 commits behind origin. Pull first?"
• "Ready to create feature branch?"

Success Criteria

A successful issue setup produces:

✓ Complete context: All issue details captured ✓ Clear plan: Implementation steps are atomic and logical ✓ Identified risks: Challenges flagged upfront ✓ Ready workspace: Branch created, scratchpad prepared ✓ Operator confidence: Developer knows exactly what to build

The scratchpad should be so clear that another developer could pick it up and execute it.

Complex Implementation Detection

If the issue analysis reveals a complex implementation, suggest entering plan mode:

Triggers for EnterPlanMode:

• Implementation affects more than 3-4 files
• Multiple valid architectural approaches exist
• Significant refactoring required
• New patterns or abstractions needed
• Breaking changes to existing APIs

Suggestion:

This issue appears complex ({reason}). Would you like me to enter
plan mode to design the implementation approach before we proceed?

Version: 1.1.0 Last Updated: 2025-12-31 Maintained By: Escapement Changelog:

• v1.1.0: Added Task delegation to Explore agent, parallel execution, LSP integration, EnterPlanMode triggers