---
description: Refine an issue with architectural perspective. Analyzes existing codebase patterns and provides implementation guidance.
argument-hint: <issue-number>
---

# 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