speckit-architecture-guard-refactor-generator

name	speckit-architecture-guard-refactor-generator
description	Convert architecture violations into non-blocking, structured refactor tasks.
compatibility	Requires spec-kit project structure with .specify/ directory
metadata	{"author":"github-spec-kit","source":"architecture-guard:commands/refactor-generator.md"}

Refactor Generator Command

You are generating non-blocking refactor tasks for architecture-guard.

Convert architecture violations into structured tasks that preserve delivery momentum while making architectural debt visible and actionable.

Flash-Mem-First Architecture Context Retrieval

When Flash-Mem is available, query it first for summary and metadata context before performing architecture analysis:

1. Search Flash-Mem for relevant architecture context:
   • architecture decisions
   • ADRs
   • design constraints
   • coding conventions
   • prior guard findings
   • approved exceptions
   • architectural patterns
2. Prefer summary-first retrieval:
   • use summaries
   • use metadata
   • use confidence
   • use tags
   • use related files
3. Load full memory content only when summaries are insufficient.
4. Reuse approved architectural decisions whenever possible.
5. Flag conflicts between proposed changes and existing architectural decisions.
6. After analysis, store durable architecture knowledge back into Flash-Mem:
   • new architecture decisions
   • approved exceptions
   • recurring violations
   • architectural constraints
   • project conventions
   • validated design patterns

If Flash-Mem is unavailable or the retrieved summaries are insufficient, continue with the repository artifacts and constitution files available in the workspace.

Use the same normalized command context as the review workflow. When mode=performance, do not invent refactor tasks from performance guidance; that mode is advisory and belongs to architecture-review output only.

Command Normalization

Accept the same normalized command context as the review workflow:

• mode=architecture by default
• mode=performance when the command includes performance
• focus=general by default
• focus=db when the command includes db
• focus=api when the command includes api
• focus=async when the command includes async

If mode=performance, do not create refactor tasks from performance guidance. That mode is advisory and belongs to architecture-review output only.

If the input points to a Constitution Update Proposal, do not convert it into a normal refactor task. Leave it for architecture-review and architecture-apply.

Inputs

Use any available:

• Detected violations.
• Constitution rules.
• Feature specification.
• Implementation plan.
• Task list.
• Existing architecture decisions.
• Existing module patterns.
• Optional framework preset guidance.

Refactor Task Rules

Each task must:

• Be non-blocking unless the Constitution explicitly says otherwise.
• Have a clear title.
• Explain the architectural reason.
• Define a concrete scope.
• Assign a priority.
• Suggest a small, practical fix.
• Avoid framework-specific requirements unless preset guidance is present.
• Avoid security or performance remediation unless it is strictly architectural.
• Do not duplicate Performance Insights into refactor tasks.

Priority Guide

• P0: Must resolve before release because the Constitution makes it blocking.
• P1: Should resolve soon to prevent architectural spread.
• P2: Safe to schedule as technical debt.
• P3: Opportunistic cleanup.

Scope Guide

Good scopes:

• One module.
• One request or response boundary.
• One API and its UI consumer.
• One service and its data access path.
• One repeated contract shape.
• One integration boundary.

Avoid scopes that are too broad:

• Refactor the whole backend.
• Clean up all components.
• Rewrite service architecture.
• Make everything consistent.

Suggested Fix Guide

Suggested fixes should be concrete:

• Introduce or align a DTO, schema, interface, request object, response object, event contract, command object, or equivalent.
• Move business rules from the entry boundary into application or domain logic.
• Add a module-facing abstraction instead of reaching into internals.
• Route persistence access through an established data abstraction.
• Normalize output shape to match nearby modules.
• Add validation at the external input boundary.
• Document an accepted deviation if the current design is intentional.

Incremental Migration Strategy

When generating refactor tasks based on architecture drift, you MUST avoid proposing full system rewrites. Prefer incremental, boundary-by-boundary, or module-by-module migrations. Output your phased migration strategy to specs/<feature>/architecture-migration-plan.md. Include coexistence strategies for old and new patterns.

Architecture Migration Plan Structure

When creating specs/<feature>/architecture-migration-plan.md, use this structure:

# [Violation Title] Migration Plan

## Current State
[Brief description or ASCII diagram of current architecture]

### Problems
- [Problem 1 from violation]
- [Problem 2 from violation]

## Target State
[Brief description or ASCII diagram of target architecture]

### Benefits
- [Benefit 1]
- [Benefit 2]

## Migration Phases

### Phase 1: [Name] (Estimated: X days)
**Goal**: [Outcome]

- **Task 1.1**: [Specific, actionable task]
- **Task 1.2**: [Specific, actionable task]

**Coexistence**: [How old and new patterns coexist in this phase]

### Phase 2: [Name] (Estimated: X days)
[Same structure]

## Coexistence Strategy

**Why coexistence?** Avoid big-bang rewrites; allow gradual migration.

**How**:
- New code uses new pattern immediately
- Old code continues on old pattern temporarily
- Boundary layer adapts between old and new
- Example: Run both repositories in parallel until all consumers migrate

## Rollback Plan
[If migration fails, how do we revert?]

## Success Criteria
- [ ] All new code uses target pattern
- [ ] Old pattern removed or marked deprecated
- [ ] Tests pass
- [ ] No performance regression

Output Format

Return only:

Refactor Tasks:
[Refactor Task]
Title:
Reason:
Scope:
Priority:
Suggested Fix:

If no tasks are needed:

Refactor Tasks:
- None

Constitution Update Proposals are not refactor tasks.

Example

Refactor Tasks:
[Refactor Task]
Title: Move pricing rule out of checkout route
Reason: The route currently owns a business decision that should live behind the checkout application boundary.
Scope: Checkout request handler and checkout application service.
Priority: P1
Suggested Fix: Extract pricing decision logic into the checkout service or domain policy, keep the route responsible for validation, mapping, and delegation only.