Skip to content

Commit 5e955c3

Browse files
kcenonkcenon
committed
docs(commands): add Error Handling section to all commands
Add standardized Error Handling sections to all 5 command files: - code-quality.md: file validation, unsupported types, encoding errors - git-status.md: git prerequisites, remote issues, merge/rebase states - pr-review.md: gh CLI requirements, PR state handling, API limits - issue-work.md: prerequisites, build/test failures, push rejections - pr-work.md: PR validation, workflow failures, fix verification Each section includes Prerequisites Check and Runtime Errors tables with error messages and user resolutions. Closes #42
1 parent 4bf8867 commit 5e955c3

5 files changed

Lines changed: 113 additions & 0 deletions

File tree

‎global/commands/issue-work.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,3 +180,27 @@ After completion, provide summary:
180180
### Next Steps
181181
- Any follow-up items
182182
```
183+
184+
## Error Handling
185+
186+
### Prerequisites Check
187+
188+
| Requirement | Error Message | Resolution |
189+
|-------------|---------------|------------|
190+
| git installed | "Git is not installed" | Install git from https://git-scm.com |
191+
| gh CLI installed | "GitHub CLI is not installed" | Install from https://cli.github.com |
192+
| gh authenticated | "Not authenticated with GitHub" | Run `gh auth login` |
193+
| Project directory exists | "Project directory not found: [path]" | Verify project path in configuration |
194+
195+
### Runtime Errors
196+
197+
| Error Condition | Behavior | User Action |
198+
|-----------------|----------|-------------|
199+
| No matching issues | Report "No critical/high priority issues found" | Check issue labels or lower priority filter |
200+
| Issue already assigned | Report assignment status, offer to proceed or skip | Confirm continuation or select different issue |
201+
| Branch already exists | Report existing branch, offer to reuse or rename | Delete old branch or use new name |
202+
| Build failure | Create draft PR with failure log, request manual fix | Fix build errors before marking PR ready |
203+
| Test failure | Report failing tests with details, pause workflow | Fix tests and retry |
204+
| Push rejected | Report rejection reason (non-fast-forward, protected branch) | Pull latest changes or request permissions |
205+
| PR creation failed | Report GitHub API error with details | Check repository permissions |
206+
| Network timeout | Report "Cannot reach GitHub - check connection" | Verify internet connection |

‎global/commands/pr-work.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -205,3 +205,28 @@ error: code should be formatted with clang-format
205205
warning: variable name should be camelCase
206206
# Fix: Rename variable
207207
```
208+
209+
## Error Handling
210+
211+
### Prerequisites Check
212+
213+
| Requirement | Error Message | Resolution |
214+
|-------------|---------------|------------|
215+
| git installed | "Git is not installed" | Install git from https://git-scm.com |
216+
| gh CLI installed | "GitHub CLI is not installed" | Install from https://cli.github.com |
217+
| gh authenticated | "Not authenticated with GitHub" | Run `gh auth login` |
218+
| Project directory exists | "Project directory not found: [path]" | Verify project path in configuration |
219+
220+
### Runtime Errors
221+
222+
| Error Condition | Behavior | User Action |
223+
|-----------------|----------|-------------|
224+
| PR not found | Report "PR #X not found" and list valid PR numbers | Verify PR number with `gh pr list` |
225+
| All workflows passing | Report "No failed workflows found - PR is ready for review" | Proceed to review or merge |
226+
| Branch not found | Report "Branch not found" with PR details | Check if branch was deleted |
227+
| Cannot checkout branch | Report checkout failure reason | Resolve local changes or conflicts |
228+
| Fix verification failed | Report local test/build failure, pause workflow | Debug and fix before pushing |
229+
| Push rejected | Report rejection reason | Pull latest or resolve conflicts |
230+
| Workflow still failing after fix | Report persistent failure, suggest manual review | Analyze failure logs, may need different approach |
231+
| API rate limit | Report "GitHub API rate limit exceeded, resets at [time]" | Wait or authenticate with different token |
232+
| Network timeout | Report "Cannot reach GitHub - check connection" | Verify internet connection |

‎project/.claude/commands/code-quality.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,3 +81,24 @@ Perform comprehensive code quality analysis:
8181

8282
#### Score: X/10
8383
```
84+
85+
## Error Handling
86+
87+
### Prerequisites Check
88+
89+
| Requirement | Error Message | Resolution |
90+
|-------------|---------------|------------|
91+
| File exists | "File not found: [path]" | Verify path and file existence |
92+
| Readable file | "Permission denied: [path]" | Check file permissions |
93+
| Supported file type | "Unsupported file type: [ext]" | Use supported extensions (.ts, .py, .kt, .cpp, etc.) |
94+
95+
### Runtime Errors
96+
97+
| Error Condition | Behavior | User Action |
98+
|-----------------|----------|-------------|
99+
| Empty file | Report "No code to analyze" and skip | Add code to file or remove from analysis |
100+
| Binary file | Report "Cannot analyze binary file" and skip | Exclude binary files from target |
101+
| Encoding error | Report "Unable to read file encoding" | Convert file to UTF-8 |
102+
| Directory not found | Report error with suggested similar paths | Verify directory path |
103+
| Unsupported language | Report "Language not supported: [lang]" and list similar files | Target supported file types |
104+
| Analysis timeout | Report partial results with warning | Reduce scope or split analysis |

‎project/.claude/commands/git-status.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -74,3 +74,24 @@ Analyze the current git state and provide:
7474
### Recommendations
7575
- [Actionable suggestions]
7676
```
77+
78+
## Error Handling
79+
80+
### Prerequisites Check
81+
82+
| Requirement | Error Message | Resolution |
83+
|-------------|---------------|------------|
84+
| git installed | "Git is not installed" | Install git from https://git-scm.com |
85+
| In git repository | "Not a git repository" | Navigate to a git repo or run `git init` |
86+
| Valid git state | "Corrupted git repository" | Run `git fsck` to diagnose |
87+
88+
### Runtime Errors
89+
90+
| Error Condition | Behavior | User Action |
91+
|-----------------|----------|-------------|
92+
| No remote configured | Report "No remote configured - showing local status only" | Add remote with `git remote add origin <url>` |
93+
| Remote unreachable | Report "Cannot reach remote - showing cached status" | Check network connection |
94+
| Detached HEAD | Report current commit hash and warn about detached state | Create branch with `git checkout -b <name>` |
95+
| Merge in progress | Report merge status and conflicting files | Complete or abort merge |
96+
| Rebase in progress | Report rebase status and current step | Continue or abort rebase |
97+
| Lock file exists | Report "Repository locked by another process" | Wait or remove `.git/index.lock` |

‎project/.claude/commands/pr-review.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,3 +76,25 @@ Provide feedback in this format:
7676
### Recommendation
7777
[APPROVE / REQUEST_CHANGES / NEEDS_DISCUSSION]
7878
```
79+
80+
## Error Handling
81+
82+
### Prerequisites Check
83+
84+
| Requirement | Error Message | Resolution |
85+
|-------------|---------------|------------|
86+
| gh CLI installed | "GitHub CLI is not installed" | Install from https://cli.github.com |
87+
| gh authenticated | "Not authenticated with GitHub" | Run `gh auth login` |
88+
| Repository access | "No access to repository" | Verify permissions or request access |
89+
90+
### Runtime Errors
91+
92+
| Error Condition | Behavior | User Action |
93+
|-----------------|----------|-------------|
94+
| PR not found | Report "PR #X not found" and suggest `gh pr list` | Verify PR number exists |
95+
| PR already merged | Report "PR #X is already merged - showing historical review" | No action needed |
96+
| PR closed | Report "PR #X is closed without merge" | Reopen PR if review still needed |
97+
| No PR for branch | Report "No open PR found for current branch" and show how to create | Create PR with `gh pr create` |
98+
| Large PR (>1000 lines) | Warn about review complexity, offer to split by file type | Consider splitting PR |
99+
| API rate limit | Report "GitHub API rate limit exceeded, resets at [time]" | Wait or authenticate with different token |
100+
| Network timeout | Report "Cannot reach GitHub - check connection" | Verify internet connection |

0 commit comments

Comments
 (0)