Start Issue

/start-issue

Load a GitHub Issue, create a branch, and develop an implementation plan.

Usage

/start-issue <issue-number> [--force] [--current-branch]

Arguments

Instructions

When the user invokes /start-issue <number>, follow these steps:

Step 1: Load Issue

gh issue view <number> --json number,title,body,labels,state

Verify the issue exists and is open. If not open, warn the user.

Step 2: Determine Branch Type

If --current-branch is specified, skip this step entirely.

Based on the issue labels and content, determine the appropriate branch prefix:

If no matching label, check title/body for keywords. Default to feat/.

Step 3: Create Branch

If --current-branch is specified, skip branch creation. Instead, display the current branch name:

git branch --show-current

If the result is empty (detached HEAD), display an error and abort.

Otherwise (default behavior):

Generate branch name: <prefix>/<issue-number>-<normalized-title>

Normalization rules:

• Lowercase
• Remove special characters
• Replace spaces with hyphens
• Limit to 40 characters

git checkout -b <branch-name>

If branch exists, checkout instead of create.

Step 4: Plan Implementation

Unless --force is specified, enter plan mode before proceeding. With --force, execute all phases directly without entering plan mode and without interactive confirmations.

Regardless of --force, execute the following phases to create an implementation plan.

First, read the workflow configuration:

cat .claude/workflow-config.json

Check documentation.ddd.enabled to determine if DDD workflow is active.

Phase 1: Analyze Requirements

1. Extract requirements from issue body
2. Identify acceptance criteria
3. Clarify any ambiguous requirements with user

Phase 2: Identify Impact Scope

1. Identify affected code files
2. Identify affected documentation using doc-updater skill detection patterns:

Target documents are defined in documentation.paths from workflow config.

Phase 3: Document-Driven Development (DDD)

Skip this phase if documentation.ddd.enabled is false.

Before implementation, update documentation as specification using doc-updater skill:

1. Draft documentation changes

   • Write usage examples for new features
   • Document expected behavior
   • Define configuration options
   • If documentation.ddd.retcon_writing is true, write documentation as if the feature already exists
     • Purpose: Produces clearer, more confident documentation
     • Example: "Run --format json" instead of "will allow users to..."

2. Update target documents (from documentation.paths):

   • README.md - Usage and examples
   • docs/ - Detailed documentation
   • CLI --help text (in code comments)
   • CHANGELOG.md (from documentation.changelog) if applicable

3. Review documentation with user

   • Documentation becomes the "contract" for implementation

Phase 4: Design Test Cases (TDD Approach)

Based on the documented specification, design test cases using tdd-workflow skill:

1. Identify test scenarios from documentation
2. Define expected inputs and outputs
3. Consider edge cases documented in Phase 3

If --force is specified:

Skip all TDD user confirmation steps and execute the Red-Green-Refactor cycle autonomously without user approval:

• Do not ask "Do you want me to follow TDD workflow?" — assume yes
• Do not wait for user approval of test cases — proceed directly to Red confirmation
• Write tests → confirm failure (Red) → implement (Green) → refactor — all automatically
• Still report test results at each phase, but do not pause for confirmation

If --force is not specified (default):

Follow the standard TDD workflow with user confirmation:

• Ask the user if they want to follow TDD workflow
• Present test cases and get user approval before proceeding
• Wait for user confirmation at each TDD phase transition

Phase 5: Create Implementation Plan

1. List tasks in dependency order
2. Identify potential risks and mitigations
3. Summarize in table format

Step 5: Report to Issue

Post the plan as a comment on the issue using issue-reporter skill:

## Implementation Plan

**Task**: [Issue title]

### Plan
1. [Step 1]
2. [Step 2]
...

### Expected Challenges
- [Challenge 1]

---
*Posted by Claude Code at YYYY-MM-DD HH:MM*

Output Format

## Issue #<number>: <title>

### Requirements
[Requirements extracted from issue body]

### Documentation Updates (DDD)
- [ ] [Target document]: [Update description]
- [ ] [Target document]: [Update description]

### Test Plan
- [Test case 1]
- [Test case 2]

### Implementation Plan
1. [Step 1]
2. [Step 2]
...

### Verification
[Verification steps]

Error Handling