architecture/old/skills/arch-refine-issue/SKILL.md

name, description, model, argument-hint, user-invocable

name	description	model	argument-hint	user-invocable
arch-refine-issue	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.	opus	<issue-number>	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

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:

tea issues edit $1 --description "<refined description>"

Add a comment with the architectural analysis:

tea comment $1 "## Architectural Analysis

<findings from software-architect agent>

---
Generated by /arch-refine-issue"

Output Format

Present findings in a clear, actionable format:

## 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