/planning-backend-refactor

name: ring:planning-backend-refactor
description: "Planning a backend refactor: audits an existing Go or TypeScript backend against Ring/Lerian standards and produces a prioritized task list (findings.md + tasks.md) ready for ring:running-dev-cycle. Plans only — no edits. Use when an existing backend service needs to meet standards or an audit is requested. Skip for greenfield projects, single-file fixes, or frontend (use ring:planning-frontend-refactor)."

Dev Refactor Skill

When to use

• User wants to refactor existing project to follow standards
• Legacy codebase needs modernization
• Project audit requested

Skip when

• Greenfield project → Use ring:planning-large-features or ring:planning-small-features instead
• Single file fix → Use ring:running-dev-cycle directly
• Frontend project → Use ring:planning-frontend-refactor

Analyzes existing backend codebase against Ring/Lerian standards and generates refactoring tasks for ring:running-dev-cycle.

You orchestrate. Agents analyze. NEVER run Bash/Grep/Read to analyze code directly — dispatch agents.

Gap Principle

Every divergence from Ring standards = a mandatory gap to implement. No exceptions.

All divergences → FINDING-XXX → REFACTOR-XXX task → ring:running-dev-cycle input.

Architecture Pattern Applicability

| Service Type | Apply Hexagonal/Lerian Pattern? | |---|---| | CRUD API | ✅ YES | | Complex business logic | ✅ YES | | Event-driven systems | ✅ YES | | CLI tools / scripts | ❌ NO | | Workers / background jobs | ❌ NO | | Simple lambdas | ❌ NO |

Execution Steps

Step 1: Validate Prerequisites

• Check `docs/PROJECT_RULES.md` exists → STOP if missing
• Detect stack: `go.mod` → Go; `package.json` + Express/Fastify/NestJS (no React) → TypeScript
• If `package.json` + React/Next.js → STOP: use `ring:planning-frontend-refactor`

Step 2: Generate Codebase Report

Dispatch `ring:codebase-explorer`:

Generate comprehensive codebase report: project structure, architecture pattern,
tech stack, code patterns (config, database, handlers, errors, telemetry, testing),
key files inventory with file:line references, code snippets.
Output: docs/ring:planning-backend-refactor/{timestamp}/codebase-report.md

Step 3: Dispatch Specialist Agents (parallel)

Verify `codebase-report.md` exists before dispatching.

**For Go projects — dispatch backend analysis:**

Task 1: ring:backend-go (MODE: ANALYSIS only)
  - Load golang.md via WebFetch
  - Check all sections per shared-patterns/standards-coverage-table.md
  - Flag framework/library mismatches vs standards
  - File size enforcement: >1000 lines = ISSUE-XXX (HIGH), >1500 = CRITICAL
  - Multi-tenant analysis per shared-patterns/multi-tenant-analysis.md
  - Check tests, coverage, docker-compose/local runtime, and observability as backend-owned responsibilities
  - Output: Standards Coverage Table + ISSUE-XXX per finding

**For TypeScript projects:** Use `ring:backend-ts` with the same analysis contract.

Step 4: Map Findings → Tasks

After all agents complete:

1. Save individual agent reports to `docs/ring:planning-backend-refactor/{timestamp}/` 2. Map each ISSUE-XXX → FINDING-XXX (normalize severity, add file:line, current vs expected) 3. Generate `docs/ring:planning-backend-refactor/{timestamp}/findings.md` 4. Map each FINDING-XXX → one REFACTOR-XXX task (1:1 mapping) 5. Generate `docs/ring:planning-backend-refactor/{timestamp}/tasks.md` (ring:running-dev-cycle compatible)

**Findings template:**

# {project-name} Refactor Findings

## FINDING-001: {Pattern Name} in {file_path}
- **Severity:** CRITICAL | HIGH | MEDIUM | LOW
- **File:** {path}:{line}
- **Current:** {code or description}
- **Expected:** {Ring standard}
- **Standard Reference:** {standards doc section}

**Tasks template:**

# {project-name} Refactor Tasks

## REFACTOR-001: {Pattern Name} in {file_path}
- **Finding:** FINDING-001
- **Estimated Complexity:** trivial | moderate | complex
- **Acceptance Criteria:**
  - [ ] {specific, testable criteria}

Step 5: Visual Change Report + User Approval

Generate visual HTML summary of KILL/CHANGE/ADD operations → dispatch `ring:visualizing`.

Present to user for approval. Wait for explicit APPROVED.

Step 6: Save + Handoff

Save all artifacts to `docs/ring:planning-backend-refactor/{timestamp}/`.

Handoff to `ring:running-dev-cycle`: feed tasks.md as input.

Agent Analysis Report Template

# {Agent Name} Analysis Report

## EXPLORATION SUMMARY
High-level architecture assessment

## KEY FINDINGS
ISSUE-XXX list with file:line, current, expected

## ARCHITECTURE INSIGHTS
Patterns detected, notable deviations

## RELEVANT FILES
Files most impacted by findings

## RECOMMENDATIONS
Priority order for refactoring