---
name: ring:dev-refactor
description: Analyzes codebase against standards and generates refactoring tasks for ring:dev-cycle.
trigger: |
  - User wants to refactor existing project to follow standards
  - Legacy codebase needs modernization
  - Project audit requested

skip_when: |
  - Greenfield project → Use /pre-dev-* instead
  - Single file fix → Use ring:dev-cycle directly

---

# Dev Refactor Skill

Analyzes existing codebase against Ring/Lerian standards and generates refactoring tasks compatible with ring:dev-cycle.

---

## ⛔ MANDATORY GAP PRINCIPLE (NON-NEGOTIABLE)

**any divergence from Ring standards = MANDATORY gap to implement.**

<cannot_skip>
- All divergences are gaps - Every difference MUST be tracked as FINDING-XXX
- Severity affects PRIORITY, not TRACKING - Low severity = lower priority, not "optional"
- No filtering allowed - You CANNOT decide which divergences "matter"
- No alternative patterns accepted - Different approach = STILL A GAP
- No cosmetic exceptions - Naming, formatting, structure differences = GAPS
</cannot_skip>

Non-negotiable, not open to interpretation—a HARD RULE.

### Anti-Rationalization: Mandatory Gap Principle

See [shared-patterns/shared-anti-rationalization.md](../shared-patterns/shared-anti-rationalization.md) for:
- **Refactor Gap Tracking** section (mandatory gap principle rationalizations)
- **Gate Execution** section (workflow skip rationalizations)
- **TDD** section (test-first rationalizations)
- **Universal** section (general anti-patterns)

### Verification Rule

```
COUNT(non-✅ items in all Standards Coverage Tables) == COUNT(FINDING-XXX entries)

If counts don't match → SKILL FAILURE. Go back and add missing findings.
```

---

## ⛔ Architecture Pattern Applicability

**Not all architecture patterns apply to all services.** Before flagging gaps, verify the pattern is applicable.

| Service Type | Hexagonal/Clean Architecture | Directory Structure |
|--------------|------------------------------|---------------------|
| CRUD API (with services, adapters) | ✅ APPLY | ✅ APPLY (Lerian pattern) |
| Complex business logic | ✅ APPLY | ✅ APPLY |
| Multiple bounded contexts | ✅ APPLY | ✅ APPLY |
| Event-driven systems | ✅ APPLY | ✅ APPLY |
| Simple scripts/utilities | ❌ not APPLICABLE | ❌ not APPLICABLE |
| CLI tools | ❌ not APPLICABLE | ❌ not APPLICABLE |
| Workers/background jobs | ❌ not APPLICABLE | ❌ not APPLICABLE |
| Simple lambda/functions | ❌ not APPLICABLE | ❌ not APPLICABLE |

### Detection Criteria

**CRUD API (Hexagonal/Lerian Pattern APPLICABLE):**
- Service exposes API endpoints (REST, gRPC, GraphQL)
- Contains business logic and models
- Has CRUD operations (Create, Read, Update, Delete)
- Uses repositories for data access
- → **MUST follow Hexagonal Architecture and Lerian directory pattern**

**Simple Service (Hexagonal/Lerian not applicable):**
- CLI tools and scripts
- Workers and background jobs
- Simple utility functions
- Lambda functions with single responsibility
- No business logic layer

### Agent Instruction

When dispatching specialist agents, include:

```
⛔ ARCHITECTURE APPLICABILITY CHECK:
1. If service is an API with CRUD operations → APPLY Hexagonal/Lerian standards
2. If service is CLI tool, script, or simple utility → Do not flag Hexagonal/Lerian gaps

CRUD APIs MUST follow Hexagonal Architecture (ports/adapters) and Lerian directory pattern.
```

---

## ⛔ MANDATORY: Initialize Todo List FIRST

**Before any other action, create the todo list with all steps:**

```yaml
TodoWrite:
  todos:
    - content: "Validate PROJECT_RULES.md exists"
      status: "pending"
      activeForm: "Validating PROJECT_RULES.md exists"
    - content: "Detect project stack (Go/TypeScript/Frontend)"
      status: "pending"
      activeForm: "Detecting project stack"
    - content: "Read PROJECT_RULES.md for context"
      status: "pending"
      activeForm: "Reading PROJECT_RULES.md"
    - content: "Generate codebase report via ring:codebase-explorer"
      status: "pending"
      activeForm: "Generating codebase report"
    - content: "Dispatch specialist agents in parallel"
      status: "pending"
      activeForm: "Dispatching specialist agents"
    - content: "Save individual agent reports"
      status: "pending"
      activeForm: "Saving agent reports"
    - content: "Map agent findings to FINDING-XXX entries"
      status: "pending"
      activeForm: "Mapping agent findings"
    - content: "Generate findings.md"
      status: "pending"
      activeForm: "Generating findings.md"
    - content: "Group findings into REFACTOR-XXX tasks"
      status: "pending"
      activeForm: "Grouping findings into tasks"
    - content: "Generate tasks.md"
      status: "pending"
      activeForm: "Generating tasks.md"
    - content: "Get user approval"
      status: "pending"
      activeForm: "Getting user approval"
    - content: "Save all artifacts"
      status: "pending"
      activeForm: "Saving artifacts"
    - content: "Handoff to ring:dev-cycle"
      status: "pending"
      activeForm: "Handing off to ring:dev-cycle"
```

**This is NON-NEGOTIABLE. Do not skip creating the todo list.**

---

## ⛔ CRITICAL: Specialized Agents Perform All Tasks

See [shared-patterns/shared-orchestrator-principle.md](../shared-patterns/shared-orchestrator-principle.md) for full ORCHESTRATOR principle, role separation, forbidden/required actions, step-to-agent mapping, and anti-rationalization table.

**Summary:** You orchestrate. Agents execute. If using Bash/Grep/Read to analyze code → STOP. Dispatch agent.

---

## Step 1: Validate PROJECT_RULES.md

**TodoWrite:** Mark "Validate PROJECT_RULES.md exists" as `in_progress`

<block_condition>
- docs/PROJECT_RULES.md does not exist
</block_condition>

If condition is true, output blocker and TERMINATE. Otherwise continue to Step 1.

**Check:** Does `docs/PROJECT_RULES.md` exist?

- **YES** → Mark todo as `completed`, continue to Step 1
- **no** → Output blocker and TERMINATE:

```markdown
## BLOCKED: PROJECT_RULES.md Not Found

Cannot proceed without project standards baseline.

**Required Action:** Create `docs/PROJECT_RULES.md` with:
- Architecture patterns
- Code conventions
- Testing requirements
- Technology stack decisions

Re-run after file exists.
```

---

## Step 1: Detect Project Stack

**TodoWrite:** Mark "Detect project stack (Go/TypeScript/Frontend)" as `in_progress`

Check for manifest files and frontend indicators:

| File/Pattern | Stack | Agent |
|--------------|-------|-------|
| `go.mod` | Go Backend | ring:backend-engineer-golang |
| `package.json` + `src/` (no React) | TypeScript Backend | ring:backend-engineer-typescript |
| `package.json` + React/Next.js | Frontend | ring:frontend-engineer |
| `package.json` + BFF pattern | TypeScript BFF | frontend-bff-engineer-typescript |

**Detection Logic:**
- `go.mod` exists → Add Go backend agent
- `package.json` exists + `next.config.*` or React in dependencies → Add frontend agent
- `package.json` exists + `/api/` routes or Express/Fastify → Add TypeScript backend agent
- `package.json` exists + BFF indicators (`/bff/`, gateway patterns) → Add BFF agent

If multiple stacks detected, dispatch agents for all.

**TodoWrite:** Mark "Detect project stack (Go/TypeScript/Frontend)" as `completed`

---

## Step 2: Read PROJECT_RULES.md

**TodoWrite:** Mark "Read PROJECT_RULES.md for context" as `in_progress`

```
Read tool: docs/PROJECT_RULES.md
```

Extract project-specific conventions for agent context.

**TodoWrite:** Mark "Read PROJECT_RULES.md for context" as `completed`

---

## Step 3: Generate Codebase Report

**TodoWrite:** Mark "Generate codebase report via ring:codebase-explorer" as `in_progress`

### ⛔ MANDATORY: Use Task Tool with ring:codebase-explorer

<dispatch_required agent="ring:codebase-explorer" model="opus">
Generate a comprehensive codebase report describing WHAT EXISTS.

Include:
- Project structure and directory layout
- Architecture pattern (hexagonal, clean, etc.)
- Technology stack from manifests
- Code patterns: config, database, handlers, errors, telemetry, testing
- Key files inventory with file:line references
- Code snippets showing current implementation patterns
</dispatch_required>

<output_required>
## EXPLORATION SUMMARY
[Your summary here]

## KEY FINDINGS
[Your findings here]

## ARCHITECTURE INSIGHTS
[Your insights here]

## RELEVANT FILES
[Your file inventory here]

## RECOMMENDATIONS
[Your recommendations here]
</output_required>

Do not complete without outputting full report in the format above.

### Anti-Rationalization Table for Step 3

| Rationalization | Why It's WRONG | Required Action |
|-----------------|----------------|-----------------|
| "I'll use Bash find/ls to quickly explore" | Bash cannot analyze patterns, just lists files. ring:codebase-explorer provides architectural analysis. | **Use Task with subagent_type="ring:codebase-explorer"** |
| "The Explore agent is faster" | "Explore" subagent_type ≠ "ring:codebase-explorer". Different agents. | **Use exact string: "ring:codebase-explorer"** |
| "I already know the structure from find output" | Knowing file paths ≠ understanding architecture. Agent provides analysis. | **Use Task with subagent_type="ring:codebase-explorer"** |
| "This is a small codebase, Bash is enough" | Size is irrelevant. The agent provides standardized output format required by Step 4. | **Use Task with subagent_type="ring:codebase-explorer"** |
| "I'll explore manually then dispatch agents" | Manual exploration skips the codebase-report.md artifact required for Step 4 gate. | **Use Task with subagent_type="ring:codebase-explorer"** |

### FORBIDDEN Actions for Step 3

<forbidden>
- Bash(command="find ... -name '*.go'") → SKILL FAILURE
- Bash(command="ls -la ...") → SKILL FAILURE
- Bash(command="tree ...") → SKILL FAILURE
- Task(subagent_type="Explore", ...) → SKILL FAILURE
- Task(subagent_type="general-purpose", ...) → SKILL FAILURE
- Task(subagent_type="Plan", ...) → SKILL FAILURE
</forbidden>

Any of these = IMMEDIATE SKILL FAILURE.

### REQUIRED Action for Step 3

```
✅ Task(subagent_type="ring:codebase-explorer", model="opus", ...)
```

**After Task completes, save with Write tool:**

```
Write tool:
  file_path: "docs/refactor/{timestamp}/codebase-report.md"
  content: [Task output]
```

**TodoWrite:** Mark "Generate codebase report via ring:codebase-explorer" as `completed`

---

## Step 4: Dispatch Specialist Agents

**TodoWrite:** Mark "Dispatch specialist agents in parallel" as `in_progress`

### ⛔ HARD GATE: Verify codebase-report.md Exists

**BEFORE dispatching any specialist agent, verify:**

```
Check 1: Does docs/refactor/{timestamp}/codebase-report.md exist?
  - YES → Continue to dispatch agents
  - no  → STOP. Go back to Step 3.

Check 2: Was codebase-report.md created by ring:codebase-explorer?
  - YES → Continue
  - no (created by Bash output) → DELETE IT. Go back to Step 3. Use correct agent.
```

**If you skipped Step 3 or used Bash instead of Task tool → You MUST go back and redo Step 3 correctly.**

**Dispatch all applicable agents in ONE message (parallel):**

### ⛔ MANDATORY: Reference Standards Coverage Table

**All agents MUST follow [shared-patterns/standards-coverage-table.md](../shared-patterns/standards-coverage-table.md) which defines:**
- all sections to check per agent (including DDD)
- Required output format (Standards Coverage Table)
- Anti-rationalization rules
- Completeness verification

**Section indexes are pre-defined in shared-patterns. Agents MUST check all sections listed.**

---

### For Go projects:

<parallel_dispatch agents="ring:backend-engineer-golang, ring:qa-analyst, ring:devops-engineer, ring:sre" model="opus">
All four agents MUST be dispatched in parallel via Task tool.
Input: codebase-report.md, PROJECT_RULES.md
</parallel_dispatch>

```yaml
Task tool 1:
  subagent_type: "ring:backend-engineer-golang"
  model: "opus"
  description: "Go standards analysis"
  prompt: |
    **MODE: ANALYSIS only**

    ⛔ MANDATORY: Check all sections in golang.md per shared-patterns/standards-coverage-table.md

    ⛔ FRAMEWORKS & LIBRARIES DETECTION (MANDATORY):
    1. Read go.mod to extract all dependencies used in codebase
    2. Load golang.md standards via WebFetch → extract all listed frameworks/libraries
    3. For each category in standards (HTTP, Database, Validation, Testing, etc.):
       - Compare codebase dependency vs standards requirement
       - If codebase uses DIFFERENT library than standards → ISSUE-XXX
       - If codebase is MISSING required library → ISSUE-XXX
    4. any library not in standards that serves same purpose = ISSUE-XXX

    Input:
    - Ring Standards: Load via WebFetch (golang.md)
    - Section Index: See shared-patterns/standards-coverage-table.md → "ring:backend-engineer-golang"
    - Codebase Report: docs/refactor/{timestamp}/codebase-report.md
    - Project Rules: docs/PROJECT_RULES.md

    Output:
    1. Standards Coverage Table (per shared-patterns format)
    2. ISSUE-XXX for each ⚠️/❌ finding with: Pattern name, Severity, file:line, Current Code, Expected Code

Task tool 2:
  subagent_type: "ring:qa-analyst"
  model: "opus"
  description: "Test coverage analysis"
  prompt: |
    **MODE: ANALYSIS only**
    Check all testing sections per shared-patterns/standards-coverage-table.md → "ring:qa-analyst"
    Input: codebase-report.md, PROJECT_RULES.md
    Output: Standards Coverage Table + ISSUE-XXX for gaps

Task tool 3:
  subagent_type: "ring:devops-engineer"
  model: "opus"
  description: "DevOps analysis"
  prompt: |
    **MODE: ANALYSIS only**
    Check all 7 sections per shared-patterns/standards-coverage-table.md → "ring:devops-engineer"
    ⛔ "Containers" means BOTH Dockerfile and Docker Compose
    ⛔ "Makefile Standards" means all required commands: build, lint, test, cover, up, down, etc.
    Input: codebase-report.md, PROJECT_RULES.md
    Output: Standards Coverage Table + ISSUE-XXX for gaps

Task tool 4:
  subagent_type: "ring:sre"
  model: "opus"
  description: "Observability analysis"
  prompt: |
    **MODE: ANALYSIS only**
    Check all 6 sections per shared-patterns/standards-coverage-table.md → "ring:sre"
    Input: codebase-report.md, PROJECT_RULES.md
    Output: Standards Coverage Table + ISSUE-XXX for gaps
```

### For TypeScript Backend projects:

<parallel_dispatch agents="ring:backend-engineer-typescript, ring:qa-analyst, ring:devops-engineer, ring:sre" model="opus">
All four agents MUST be dispatched in parallel via Task tool.
Input: codebase-report.md, PROJECT_RULES.md
</parallel_dispatch>

```yaml
Task tool 1:
  subagent_type: "ring:backend-engineer-typescript"
  model: "opus"
  description: "TypeScript backend standards analysis"
  prompt: |
    **MODE: ANALYSIS only**

    ⛔ MANDATORY: Check all sections in typescript.md per shared-patterns/standards-coverage-table.md

    ⛔ FRAMEWORKS & LIBRARIES DETECTION (MANDATORY):
    1. Read package.json to extract all dependencies used in codebase
    2. Load typescript.md standards via WebFetch → extract all listed frameworks/libraries
    3. For each category in standards (Backend Framework, ORM, Validation, Testing, etc.):
       - Compare codebase dependency vs standards requirement
       - If codebase uses DIFFERENT library than standards → ISSUE-XXX
       - If codebase is MISSING required library → ISSUE-XXX
    4. any library not in standards that serves same purpose = ISSUE-XXX

    Input:
    - Ring Standards: Load via WebFetch (typescript.md)
    - Section Index: See shared-patterns/standards-coverage-table.md → "ring:backend-engineer-typescript"
    - Codebase Report: docs/refactor/{timestamp}/codebase-report.md
    - Project Rules: docs/PROJECT_RULES.md

    Output:
    1. Standards Coverage Table (per shared-patterns format)
    2. ISSUE-XXX for each ⚠️/❌ finding with: Pattern name, Severity, file:line, Current Code, Expected Code
```

### For Frontend projects (React/Next.js):

<parallel_dispatch agents="ring:frontend-engineer, ring:qa-analyst, ring:devops-engineer, ring:sre" model="opus">
All four agents MUST be dispatched in parallel via Task tool.
Input: codebase-report.md, PROJECT_RULES.md
</parallel_dispatch>

```yaml
Task tool 5:
  subagent_type: "ring:frontend-engineer"
  model: "opus"
  description: "Frontend standards analysis"
  prompt: |
    **MODE: ANALYSIS only**

    ⛔ MANDATORY: Check all 13 sections in frontend.md per shared-patterns/standards-coverage-table.md

    Input:
    - Ring Standards: Load via WebFetch (frontend.md)
    - Section Index: See shared-patterns/standards-coverage-table.md → "ring:frontend-engineer"
    - Codebase Report: docs/refactor/{timestamp}/codebase-report.md
    - Project Rules: docs/PROJECT_RULES.md

    Output:
    1. Standards Coverage Table (per shared-patterns format)
    2. ISSUE-XXX for each ⚠️/❌ finding with: Pattern name, Severity, file:line, Current Code, Expected Code
```

### For BFF (Backend-for-Frontend) projects:

<parallel_dispatch agents="frontend-bff-engineer-typescript, ring:qa-analyst, ring:devops-engineer, ring:sre" model="opus">
All four agents MUST be dispatched in parallel via Task tool.
Input: codebase-report.md, PROJECT_RULES.md
</parallel_dispatch>

```yaml
Task tool 6:
  subagent_type: "ring:frontend-bff-engineer-typescript"
  model: "opus"
  description: "BFF TypeScript standards analysis"
  prompt: |
    **MODE: ANALYSIS only**

    ⛔ MANDATORY: Check all sections in typescript.md per shared-patterns/standards-coverage-table.md

    ⛔ FRAMEWORKS & LIBRARIES DETECTION (MANDATORY):
    1. Read package.json to extract all dependencies used in codebase
    2. Load typescript.md standards via WebFetch → extract all listed frameworks/libraries
    3. For each category in standards (Backend Framework, ORM, Validation, Testing, etc.):
       - Compare codebase dependency vs standards requirement
       - If codebase uses DIFFERENT library than standards → ISSUE-XXX
       - If codebase is MISSING required library → ISSUE-XXX
    4. any library not in standards that serves same purpose = ISSUE-XXX

    Input:
    - Ring Standards: Load via WebFetch (typescript.md)
    - Section Index: See shared-patterns/standards-coverage-table.md → "frontend-bff-engineer-typescript"
    - Codebase Report: docs/refactor/{timestamp}/codebase-report.md
    - Project Rules: docs/PROJECT_RULES.md

    Output:
    1. Standards Coverage Table (per shared-patterns format)
    2. ISSUE-XXX for each ⚠️/❌ finding with: Pattern name, Severity, file:line, Current Code, Expected Code
```

### Agent Dispatch Summary

| Stack Detected | Agents to Dispatch |
|----------------|-------------------|
| Go only | Task 1 (Go) + Task 2-4 |
| TypeScript Backend only | Task 1 (TS Backend) + Task 2-4 |
| Frontend only | Task 5 (Frontend) + Task 2-4 |
| Go + Frontend | Task 1 (Go) + Task 5 (Frontend) + Task 2-4 |
| TypeScript Backend + Frontend | Task 1 (TS Backend) + Task 5 (Frontend) + Task 2-4 |
| BFF detected | Add Task 6 (BFF) to above |

**TodoWrite:** Mark "Dispatch specialist agents in parallel" as `completed`

---

## Step 4.5: Save Individual Agent Reports

**TodoWrite:** Mark "Save individual agent reports" as `in_progress`

**⛔ MANDATORY: Each agent's output MUST be saved as an individual report file.**

After all parallel agent tasks complete, save each agent's output to a separate file:

```
docs/refactor/{timestamp}/reports/
├── ring:backend-engineer-golang-report.md     (if Go project)
├── ring:backend-engineer-typescript-report.md (if TypeScript Backend)
├── ring:frontend-engineer-report.md           (if Frontend)
├── frontend-bff-engineer-report.md       (if BFF)
├── ring:qa-analyst-report.md                  (always)
├── ring:devops-engineer-report.md             (always)
└── ring:sre-report.md                         (always)
```

### Report File Format

**Use Write tool for each agent report:**

```markdown
# {Agent Name} Analysis Report

**Generated:** {timestamp}
**Agent:** {agent-name}
**Mode:** ANALYSIS only

## Standards Coverage Table

{Copy agent's Standards Coverage Table output here}

## Issues Found

{Copy all ISSUE-XXX entries from agent output}

## Summary

- **Total Issues:** {count}
- **Critical:** {count}
- **High:** {count}
- **Medium:** {count}
- **Low:** {count}

---
*Report generated by ring:dev-refactor skill*
```

### Agent Report Mapping

| Agent Dispatched | Report File Name |
|------------------|------------------|
| ring:backend-engineer-golang | `ring:backend-engineer-golang-report.md` |
| ring:backend-engineer-typescript | `ring:backend-engineer-typescript-report.md` |
| ring:frontend-engineer | `ring:frontend-engineer-report.md` |
| frontend-bff-engineer-typescript | `frontend-bff-engineer-report.md` |
| ring:qa-analyst | `ring:qa-analyst-report.md` |
| ring:devops-engineer | `ring:devops-engineer-report.md` |
| ring:sre | `ring:sre-report.md` |

### Anti-Rationalization Table for Step 4.5

| Rationalization | Why It's WRONG | Required Action |
|-----------------|----------------|-----------------|
| "I'll combine all reports into one file" | Individual reports enable targeted re-runs and tracking | **Save each agent to SEPARATE file** |
| "Agent output is already visible in chat" | Chat history is ephemeral; files are artifacts | **MUST persist as files** |
| "Only saving reports with issues" | Empty reports prove compliance was checked | **Save all dispatched agent reports** |
| "findings.md already captures everything" | findings.md is processed; reports are raw agent output | **Save BOTH raw reports and findings.md** |

### REQUIRED Action for Step 4.5

```
Write tool:
  file_path: "docs/refactor/{timestamp}/reports/{agent-name}-report.md"
  content: [Agent Task output formatted per template above]
```

**Repeat for each agent dispatched in Step 4.**

**TodoWrite:** Mark "Save individual agent reports" as `completed`

---

## Step 4.1: Agent Report → Findings Mapping (HARD GATE)

**TodoWrite:** Mark "Map agent findings to FINDING-XXX entries" as `in_progress`

**⛔ MANDATORY: all agent-reported issues MUST become findings.**

| Agent Report | Action |
|--------------|--------|
| Any difference between current code and Ring standard | → Create FINDING-XXX |
| Any missing pattern from Ring standards | → Create FINDING-XXX |
| Any deprecated pattern usage | → Create FINDING-XXX |
| Any observability gap | → Create FINDING-XXX |

### FORBIDDEN Actions for Step 4.1

```
❌ Ignoring agent-reported issues because they seem "minor"  → SKILL FAILURE
❌ Filtering out issues based on personal judgment           → SKILL FAILURE
❌ Summarizing multiple issues into one finding              → SKILL FAILURE
❌ Skipping issues without ISSUE-XXX format from agent       → SKILL FAILURE
❌ Creating findings only for "interesting" gaps             → SKILL FAILURE
```

### REQUIRED Actions for Step 4.1

```
✅ Every line item from agent reports becomes a FINDING-XXX entry
✅ Preserve agent's severity assessment exactly as reported
✅ Include exact file:line references from agent report
✅ Every non-✅ item in Standards Coverage Table = one FINDING-XXX
✅ Count findings in Step 5 MUST equal total issues from all agent reports
```

---

### Anti-Rationalization Table for Step 4.1

**⛔ See also: "Anti-Rationalization: Mandatory Gap Principle" at top of this skill.**

| Rationalization | Why It's WRONG | Required Action |
|-----------------|----------------|-----------------|
| "Multiple similar issues can be one finding" | Distinct file:line = distinct finding. Merging loses traceability. | **One issue = One FINDING-XXX** |
| "Agent report didn't use ISSUE-XXX format" | Format varies; presence matters. Every gap = one finding. | **Extract all gaps into findings** |
| "I'll consolidate to reduce noise" | Consolidation = data loss. Noise is signal. | **Preserve all individual issues** |
| "Some findings are duplicates across agents" | Different agents = different perspectives. Keep both. | **Create separate findings per agent** |
| "Team has approved this deviation" | Team approval ≠ standards compliance. Document the gap. | **Create FINDING-XXX, note team decision** |
| "Fixing this would break existing code" | Breaking risk = implementation concern, not tracking concern. | **Create FINDING-XXX, note risk in description** |

### ⛔ MANDATORY GAP RULE FOR STEP 4.1

**Per the Mandatory Gap Principle (see top of skill): any divergence from Ring standards = FINDING-XXX.**

This means:
- ✅ items in Standards Coverage Table = No finding needed
- ⚠️ items = MUST create FINDING-XXX (partial compliance is a gap)
- ❌ items = MUST create FINDING-XXX (non-compliance is a gap)
- Different pattern = MUST create FINDING-XXX (alternative is still a gap)

**Verification:** Use formula from "Mandatory Gap Principle → Verification Rule" section.

### ⛔ Gate Escape Detection (Anti-Duplication)

**When mapping findings, identify which gate SHOULD have caught the issue:**

| Finding Category | Should Be Caught In | Flag |
|------------------|---------------------|------|
| Missing edge case tests | Gate 3 (Testing) | `🚨 GATE 3 ESCAPE` |
| Test isolation issues | Gate 3 (Testing) | `🚨 GATE 3 ESCAPE` |
| Skipped/assertion-less tests | Gate 3 (Testing) | `🚨 GATE 3 ESCAPE` |
| Test naming convention | Gate 3 (Testing) | `🚨 GATE 3 ESCAPE` |
| Missing test coverage | Gate 3 (Testing) | `🚨 GATE 3 ESCAPE` |
| TDD RED phase missing | Gate 3 (Testing) | `🚨 GATE 3 ESCAPE` |
| Implementation pattern gaps | Gate 0 (Implementation) | Normal finding |
| Standards compliance gaps | Gate 0 (Implementation) | Normal finding |
| Observability gaps | Gate 2 (SRE) | `🚨 GATE 2 ESCAPE` |
| Docker/DevOps gaps | Gate 1 (DevOps) | `🚨 GATE 1 ESCAPE` |

**Gate Escape Output Format:**

```markdown
### FINDING-XXX: [Issue Title] 🚨 GATE 3 ESCAPE

**Escaped From:** Gate 3 (Testing)
**Why It Escaped:** [Quality Gate check that should have caught this]
**Prevention:** [Specific check to add to Gate 3 exit criteria]

[Rest of finding format...]
```

**Purpose:** Track which issues escape which gates. If many `GATE 3 ESCAPE` findings occur, the Quality Gate checks need strengthening.

---

**Summary Table (MANDATORY at end of findings.md):**

```markdown
## Gate Escape Summary

| Gate | Escaped Issues | Most Common Type |
|------|----------------|------------------|
| Gate 0 (Implementation) | N | [type] |
| Gate 1 (DevOps) | N | [type] |
| Gate 2 (SRE) | N | [type] |
| Gate 3 (Testing) | N | [type] |

**Action Required:** If any gate has >2 escapes, review that gate's exit criteria.
```

**TodoWrite:** Mark "Map agent findings to FINDING-XXX entries" as `completed`

---

## Step 5: Generate findings.md

**TodoWrite:** Mark "Generate findings.md" as `in_progress`

### ⛔ HARD GATE: Verify All Issues Are Mapped

**BEFORE creating findings.md, apply the Verification Rule from "Mandatory Gap Principle" section.**

If counts don't match → STOP. Go back to Step 4.1. Map missing issues.

### FORBIDDEN Actions for Step 5

```
❌ Creating findings.md with fewer entries than agent issues  → SKILL FAILURE
❌ Omitting file:line references from findings                → SKILL FAILURE
❌ Using vague descriptions instead of specific code excerpts → SKILL FAILURE
❌ Skipping "Why This Matters" section for any finding        → SKILL FAILURE
❌ Generating findings.md without reading all agent reports   → SKILL FAILURE
```

### REQUIRED Actions for Step 5

```
✅ Every FINDING-XXX includes: Severity, Category, Agent, Standard reference
✅ Every FINDING-XXX includes: Current Code with exact file:line
✅ Every FINDING-XXX includes: Ring Standard Reference with URL
✅ Every FINDING-XXX includes: Required Changes as numbered actions
✅ Every FINDING-XXX includes: Why This Matters with Problem/Standard/Impact
✅ Total finding count MUST match total issues from Step 4.1
```

### Anti-Rationalization Table for Step 5

| Rationalization | Why It's WRONG | Required Action |
|-----------------|----------------|-----------------|
| "I'll add details later during implementation" | findings.md is the source of truth. Incomplete = useless. | **Complete all sections for every finding** |
| "Code snippet is too long to include" | Truncate to relevant lines, but never omit. Context is required. | **Include code with file:line reference** |
| "Standard URL is obvious, skip it" | Agents and humans need direct links. Nothing is obvious. | **Include full URL for every standard** |
| "Why This Matters is redundant" | It explains business impact. Standards alone don't convey urgency. | **Write Problem/Standard/Impact for all** |
| "Some findings are self-explanatory" | Self-explanatory to you ≠ clear to implementer. | **Complete all sections without exception** |
| "I'll group small findings together" | Grouping happens in Step 6 (tasks). findings.md = atomic issues. | **One finding = one FINDING-XXX entry** |

**Use Write tool to create findings.md:**

**⛔ CRITICAL: Every issue reported by agents in Step 4 MUST appear here as a FINDING-XXX entry.**

```markdown
# Findings: {project-name}

**Generated:** {timestamp}
**Total Findings:** {count}

## ⛔ Mandatory Gap Principle Applied

**all divergences from Ring standards are tracked below. No filtering applied.**

| Metric | Count |
|--------|-------|
| Total non-✅ items from agent reports | {X} |
| Total FINDING-XXX entries below | {X} |
| **Counts match?** | ✅ YES (REQUIRED) |

**Severity does not affect tracking - all gaps are mandatory:**
| Severity | Count | Priority | Tracking |
|----------|-------|----------|----------|
| Critical | {N} | Execute first | **MANDATORY** |
| High | {N} | Execute in current sprint | **MANDATORY** |
| Medium | {N} | Execute in next sprint | **MANDATORY** |
| Low | {N} | Execute when capacity | **MANDATORY** |

---

## FINDING-001: {Pattern Name}

**Severity:** Critical | High | Medium | Low (all MANDATORY)
**Category:** {lib-commons | architecture | testing | devops}
**Agent:** {agent-name}
**Standard:** {file}.md:{section}

### Current Code
```{lang}
// file: {path}:{lines}
{actual code}
```

### Ring Standard Reference
**Standard:** {standards-file}.md → Section: {section-name}
**Pattern:** {pattern-name}
**URL:** https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/{file}.md

### Required Changes
1. {action item 1 - what to change}
2. {action item 2 - what to add/remove}
3. {action item 3 - pattern to follow}

### Why This Matters
- **Problem:** {what is wrong with current code}
- **Standard Violated:** {specific section from Ring standards}
- **Impact:** {business/technical impact if not fixed}

---

## FINDING-002: ...
```

**TodoWrite:** Mark "Generate findings.md" as `completed`

---

## Step 6: Group Findings into Tasks

**TodoWrite:** Mark "Group findings into REFACTOR-XXX tasks" as `in_progress`

**⛔ HARD GATE: Every FINDING-XXX MUST appear in at least one REFACTOR-XXX task.**

Group related findings by:
1. Module/bounded context (same file/package = same task)
2. Dependency order (foundational changes first)
3. Severity (critical first)

**Mapping Verification:**
```
Before proceeding to Step 7, verify:
- Total findings in findings.md: X
- Total findings referenced in tasks: X (MUST MATCH)
- Orphan findings (not in any task): 0 (MUST BE ZERO)
```

**If any finding is not mapped to a task → STOP. Add missing findings to tasks.**

**TodoWrite:** Mark "Group findings into REFACTOR-XXX tasks" as `completed`

---

## Step 7: Generate tasks.md

**TodoWrite:** Mark "Generate tasks.md" as `in_progress`

**Use Write tool to create tasks.md:**

```markdown
# Refactoring Tasks: {project-name}

**Source:** findings.md
**Total Tasks:** {count}

## ⛔ Mandatory Gap Verification

**all findings from findings.md MUST be addressed in tasks below.**

| Metric | Count |
|--------|-------|
| Total FINDING-XXX in findings.md | {X} |
| Total FINDING-XXX referenced in tasks | {X} |
| Orphan findings (not in any task) | 0 (REQUIRED) |
| **All findings mapped?** | ✅ YES (REQUIRED) |

**Priority affects execution order, not whether to include:**
- Critical/High tasks: Execute first
- Medium tasks: Execute in current cycle
- Low tasks: Execute when capacity - STILL MANDATORY TO COMPLETE

---

## REFACTOR-001: {Task Name}

**Priority:** Critical | High | Medium | Low (all ARE MANDATORY)
**Effort:** {hours}h
**Dependencies:** {other tasks or none}

### Findings Addressed
| Finding | Pattern | Severity | File:Line |
|---------|---------|----------|-----------|
| FINDING-001 | {name} | Critical | src/handler.go:45 |
| FINDING-003 | {name} | High | src/service.go:112 |

### Ring Standards to Follow
| Standard File | Section | URL |
|---------------|---------|-----|
| golang.md | Error Handling | [Link](https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang.md) |
| sre.md | Structured Logging | [Link](https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/sre.md) |

### Required Actions
1. [ ] {action from FINDING-001 - specific change to make}
2. [ ] {action from FINDING-001 - pattern to implement}
3. [ ] {action from FINDING-003 - specific change to make}

### Acceptance Criteria
- [ ] Code follows {standard}.md → {section} pattern
- [ ] No {anti-pattern} usage remains
- [ ] Tests pass after refactoring
- [ ] {additional criteria from findings}
```

**TodoWrite:** Mark "Generate tasks.md" as `completed`

---

## Step 8: User Approval

**TodoWrite:** Mark "Get user approval" as `in_progress`

<user_decision>
MUST wait for explicit user response before proceeding.
Options: Approve all | Critical only | Cancel
</user_decision>

```yaml
AskUserQuestion:
  questions:
    - question: "Review refactoring plan. How to proceed?"
      header: "Approval"
      options:
        - label: "Approve all"
          description: "Proceed to ring:dev-cycle execution"
        - label: "Critical only"
          description: "Execute only Critical/High tasks"
        - label: "Cancel"
          description: "Keep analysis, skip execution"
```

CANNOT proceed without explicit user selection.

**TodoWrite:** Mark "Get user approval" as `completed`

---

## Step 9: Save Artifacts

**TodoWrite:** Mark "Save all artifacts" as `in_progress`

```
docs/refactor/{timestamp}/
├── codebase-report.md  (Step 3)
├── reports/            (Step 4.5)
│   ├── ring:backend-engineer-golang-report.md
│   ├── ring:qa-analyst-report.md
│   ├── ring:devops-engineer-report.md
│   └── ring:sre-report.md
├── findings.md         (Step 5)
└── tasks.md           (Step 7)
```

**TodoWrite:** Mark "Save all artifacts" as `completed`

---

## Step 10: Handoff to ring:dev-cycle

**TodoWrite:** Mark "Handoff to ring:dev-cycle" as `in_progress`

**If user approved, use Skill tool to invoke ring:dev-cycle directly:**

```yaml
Skill tool:
  skill: "ring:dev-cycle"
```

**⛔ CRITICAL: Pass tasks file path in context:**

After invoking the skill, provide:
- Tasks file: `docs/refactor/{timestamp}/tasks.md`

```yaml
Context for ring:dev-cycle:
  tasks-file: "docs/refactor/{timestamp}/tasks.md"
```

Where `{timestamp}` is the same timestamp used in Step 9 artifacts.

### Anti-Rationalization: Skill Invocation

| Rationalization | Why It's WRONG | Required Action |
|-----------------|----------------|-----------------|
| "SlashCommand is equivalent to Skill tool" | SlashCommand is a hint; Skill tool guarantees skill loading | **Use Skill tool, not SlashCommand** |
| "User can run /ring:dev-cycle manually" | Manual run risks skill not being loaded | **Invoke Skill tool directly** |
| "ring:dev-cycle will auto-discover tasks" | Explicit path ensures correct file is used | **Pass explicit tasks path** |
| "User approved, I can skip ring:dev-cycle" | Approval = permission to proceed, not skip execution | **Invoke Skill tool** |
| "Tasks are saved, job is done" | Saved tasks without execution = incomplete workflow | **Invoke Skill tool** |

**⛔ HARD GATE: You CANNOT complete ring:dev-refactor without invoking `Skill tool: ring:dev-cycle`.**

If user approved execution, you MUST:
1. Invoke `Skill tool: ring:dev-cycle`
2. Pass tasks file path: `docs/refactor/{timestamp}/tasks.md`
3. Wait for ring:dev-cycle to complete all 6 gates

**Skipping this step = SKILL FAILURE.**

ring:dev-cycle executes each REFACTOR-XXX task through 6-gate process.

**TodoWrite:** Mark "Handoff to ring:dev-cycle" as `completed`

---

## Execution Report

Base metrics per [shared-patterns/output-execution-report.md](../shared-patterns/output-execution-report.md).

| Metric | Value |
|--------|-------|
| Duration | Xm Ys |
| Iterations | N |
| Result | PASS/FAIL/PARTIAL |

### Refactor-Specific Metrics
| Metric | Value |
|--------|-------|
| Agents Dispatched | N |
| Findings Generated | N |
| Tasks Created | N |
| Artifacts Location | docs/refactors/{date}/ |

## Output Schema

```yaml
artifacts:
  - codebase-report.md (Step 3)
  - reports/{agent-name}-report.md (Step 4.5)
  - findings.md (Step 5)
  - tasks.md (Step 7)

traceability:
  Ring Standard → Agent Report → FINDING-XXX → REFACTOR-XXX → Implementation
```