Hugo Nijhuis
7406517cd9
Claude Code has unified commands into skills with the user-invocable frontmatter field. This migration: - Converts 20 commands to skills with user-invocable: true - Consolidates docs into single writing-capabilities.md - Rewrites capability-writing skill for unified model - Updates CLAUDE.md, Makefile, and other references - Removes commands/ directory Skills now have two types: - user-invocable: true - workflows users trigger with /name - user-invocable: false - background knowledge auto-loaded Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
171 lines
3.9 KiB
Markdown
171 lines
3.9 KiB
Markdown
---
|
|
name: arch-refine-issue
|
|
description: >
|
|
Refine an issue with architectural perspective. Analyzes existing codebase patterns
|
|
and provides implementation guidance. Use when refining issues, adding architectural
|
|
context, or when user says /arch-refine-issue.
|
|
model: opus
|
|
argument-hint: <issue-number>
|
|
user-invocable: true
|
|
---
|
|
|
|
# Architecturally Refine Issue #$1
|
|
|
|
@~/.claude/skills/gitea/SKILL.md
|
|
@~/.claude/skills/issue-writing/SKILL.md
|
|
|
|
## Overview
|
|
|
|
Refine an issue in the context of the project's architecture. This command:
|
|
1. Fetches the issue details
|
|
2. Spawns the software-architect agent to analyze the codebase
|
|
3. Identifies how the issue fits existing patterns
|
|
4. Proposes refined description and acceptance criteria
|
|
|
|
## Process
|
|
|
|
### Step 1: Fetch Issue Details
|
|
|
|
```bash
|
|
tea issues $1 --comments
|
|
```
|
|
|
|
Capture:
|
|
- Title
|
|
- Description
|
|
- Acceptance criteria
|
|
- Any existing discussion
|
|
|
|
### Step 2: Spawn Software-Architect Agent
|
|
|
|
Use the Task tool to spawn the software-architect agent for issue refinement analysis:
|
|
|
|
```
|
|
Task tool with:
|
|
- subagent_type: "software-architect"
|
|
- prompt: See prompt below
|
|
```
|
|
|
|
**Agent Prompt:**
|
|
```
|
|
Analyze the architecture for issue refinement.
|
|
|
|
ANALYSIS_TYPE: issue-refine
|
|
TARGET: $1
|
|
CONTEXT:
|
|
<issue title and description from step 1>
|
|
|
|
Repository path: <current working directory>
|
|
|
|
Focus on:
|
|
1. Understanding existing project structure and patterns
|
|
2. Identifying packages/modules that will be affected
|
|
3. Analyzing existing conventions and code style
|
|
4. Detecting potential architectural concerns
|
|
5. Suggesting implementation approach that fits existing patterns
|
|
```
|
|
|
|
### Step 3: Parse Agent Analysis
|
|
|
|
The software-architect agent returns structured output with:
|
|
- Summary of architectural findings
|
|
- Affected packages/modules
|
|
- Pattern recommendations
|
|
- Potential concerns (breaking changes, tech debt, pattern violations)
|
|
- Implementation suggestions
|
|
|
|
### Step 4: Present Refinement Proposal
|
|
|
|
Present the refined issue to the user with:
|
|
|
|
**1. Architectural Context**
|
|
- Affected packages/modules
|
|
- Existing patterns that apply
|
|
- Dependency implications
|
|
|
|
**2. Concerns and Risks**
|
|
- Breaking changes
|
|
- Tech debt considerations
|
|
- Pattern violations to avoid
|
|
|
|
**3. Proposed Refinement**
|
|
- Refined description with architectural context
|
|
- Updated acceptance criteria (if needed)
|
|
- Technical notes section
|
|
|
|
**4. Implementation Guidance**
|
|
- Suggested approach
|
|
- Files likely to be modified
|
|
- Recommended order of changes
|
|
|
|
### Step 5: User Decision
|
|
|
|
Ask the user what action to take:
|
|
|
|
- **Apply**: Update the issue with refined description and technical notes
|
|
- **Edit**: Let user modify the proposal before applying
|
|
- **Skip**: Keep the original issue unchanged
|
|
|
|
### Step 6: Update Issue (if approved)
|
|
|
|
If user approves, update the issue using tea CLI:
|
|
|
|
```bash
|
|
tea issues edit $1 --description "<refined description>"
|
|
```
|
|
|
|
Add a comment with the architectural analysis:
|
|
|
|
```bash
|
|
tea comment $1 "## Architectural Analysis
|
|
|
|
<findings from software-architect agent>
|
|
|
|
---
|
|
Generated by /arch-refine-issue"
|
|
```
|
|
|
|
## Output Format
|
|
|
|
Present findings in a clear, actionable format:
|
|
|
|
```markdown
|
|
## Architectural Analysis for Issue #$1
|
|
|
|
### Affected Components
|
|
- `package/name` - Description of impact
|
|
- `another/package` - Description of impact
|
|
|
|
### Existing Patterns
|
|
- Pattern 1: How it applies
|
|
- Pattern 2: How it applies
|
|
|
|
### Concerns
|
|
- [ ] Breaking change: description (if applicable)
|
|
- [ ] Tech debt: description (if applicable)
|
|
- [ ] Pattern violation risk: description (if applicable)
|
|
|
|
### Proposed Refinement
|
|
|
|
**Updated Description:**
|
|
<refined description>
|
|
|
|
**Updated Acceptance Criteria:**
|
|
- [ ] Original criteria (unchanged)
|
|
- [ ] New criteria based on analysis
|
|
|
|
**Technical Notes:**
|
|
<implementation guidance based on architecture>
|
|
|
|
### Recommended Approach
|
|
1. Step 1
|
|
2. Step 2
|
|
3. Step 3
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
- If issue does not exist, inform user
|
|
- If software-architect agent fails, report partial analysis
|
|
- If tea CLI fails, show manual instructions
|