drillan/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

| Argument | Type | Required | Description | |----------|------|----------|-------------| | issue-number | integer | Yes | GitHub Issue number | | --force | flag | No | Skip plan mode and all interactive confirmations (including TDD user approval) | | --current-branch | flag | No | Skip branch creation, use the current branch |

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:

| Label | Prefix | |-------|--------| | enhancement, feature | feat/ | | bug | fix/ | | refactoring, refactor | refactor/ | | documentation, docs | docs/ | | test | test/ | | chore | chore/ |

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:

| Change Type | Documentation Impact | |-------------|---------------------| | New CLI option | README, --help output | | API endpoint added/changed | API documentation | | Configuration option added | Config guide | | Environment variable added | Setup guide | | Feature added | Feature documentation |

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

| Error | Action | |-------|--------| | Issue not found | Display error with gh issue view suggestion | | Issue is closed | Warn user and ask for confirmation | | gh not authenticated | Display gh auth login instruction | | Uncommitted changes | Ask user to commit or stash changes | | Branch creation failed | Display error details | | Detached HEAD with --current-branch | Display error: not on a branch, checkout a branch first | | workflow-config.json not found | Display error: "Run /init to create configuration." | | documentation section missing | Treat as DDD disabled, inform user | | documentation.paths missing or empty | Display warning about no documentation targets | | doc-updater/tdd-workflow skill not found | Display error with skill installation guidance |