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