---

name: dev-refactor description: Analyzes codebase against standards and generates refactoring tasks for 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 dev-cycle directly

---

Dev Refactor Skill

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

---

⛔ MANDATORY GAP PRINCIPLE (NON-NEGOTIABLE)

ANY divergence from Ring standards = MANDATORY gap to implement.

This is NOT optional. This is NOT subject to interpretation. This is a HARD RULE.

Principle	Meaning
ALL divergences are gaps	Every difference between codebase and Ring standards MUST be tracked as FINDING-XXX
Severity affects PRIORITY, not TRACKING	Low severity = lower execution priority, NOT "optional to track"
NO filtering allowed	You CANNOT decide which divergences "matter" - ALL matter
NO alternative patterns accepted	"Codebase uses different but valid approach" = STILL A GAP
NO cosmetic exceptions	Naming, formatting, structure differences = GAPS

Anti-Rationalization: Mandatory Gap Principle

Rationalization	Why It's WRONG	Required Action
"This divergence is too minor to track"	You don't decide what's minor. Standards do.	Create FINDING-XXX
"Codebase pattern is acceptable alternative"	Alternative ≠ compliant. Ring standards are the baseline.	Create FINDING-XXX
"Low severity means optional"	Low severity = low priority, NOT optional.	Create FINDING-XXX
"Cosmetic differences don't count"	Cosmetic = standards compliance. They count.	Create FINDING-XXX
"This would create too many findings"	Quantity is not your concern. Completeness is.	Create ALL FINDING-XXX entries
"Team prefers current approach"	Preference ≠ compliance. Document the gap.	Create FINDING-XXX
"Fixing this adds no value"	You don't assess value. Standards define value.	Create FINDING-XXX

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	DDD Patterns
CRUD API (with domains, entities)	✅ APPLY	✅ APPLY
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/DDD APPLICABLE):

• Service exposes API endpoints (REST, gRPC, GraphQL)
• Contains domain entities and models
• Has CRUD operations (Create, Read, Update, Delete)
• Uses repositories for data access
• → MUST follow Hexagonal Architecture and DDD patterns

Simple Service (Hexagonal/DDD NOT applicable):

• CLI tools and scripts
• Workers and background jobs
• Simple utility functions
• Lambda functions with single responsibility
• No domain model or entities

Agent Instruction

When dispatching specialist agents, include:

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

CRUD APIs with domain entities MUST follow Hexagonal Architecture (ports/adapters) and DDD patterns.

---

⛔ MANDATORY: Initialize Todo List FIRST

Before ANY other action, create the todo list with ALL steps:

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 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 dev-cycle"
      status: "pending"
      activeForm: "Handing off to 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 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 0: Validate PROJECT_RULES.md

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

Check: Does docs/PROJECT_RULES.md exist?

• YES → Mark todo as completed, continue to Step 1
• NO → Output blocker and TERMINATE:

## 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	backend-engineer-golang
package.json + src/ (no React)	TypeScript Backend	backend-engineer-typescript
package.json + React/Next.js	Frontend	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 codebase-explorer" as in_progress

⛔ MANDATORY: Use Task Tool with codebase-explorer

YOU MUST USE THIS EXACT TOOL CALL:

Task tool:
  subagent_type: "codebase-explorer"  # ← EXACT STRING, NOT "Explore"
  model: "opus"
  description: "Generate codebase architecture report"
  prompt: |
    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

    ⛔ MANDATORY OUTPUT: You MUST return your findings using EXACTLY this format:

    ## 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]

    **Do NOT complete without outputting your 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. codebase-explorer provides architectural analysis.	Use Task with subagent_type="codebase-explorer"
"The Explore agent is faster"	"Explore" subagent_type ≠ "codebase-explorer". Different agents.	Use exact string: "codebase-explorer"
"I already know the structure from find output"	Knowing file paths ≠ understanding architecture. Agent provides analysis.	Use Task with subagent_type="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="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="codebase-explorer"

FORBIDDEN Actions for Step 3

❌ 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

REQUIRED Action for Step 3

✅ Task(subagent_type="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 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 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 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:

Task tool 1:
  subagent_type: "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 → "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: "qa-analyst"
  model: "opus"
  description: "Test coverage analysis"
  prompt: |
    **MODE: ANALYSIS ONLY**
    Check ALL testing sections per shared-patterns/standards-coverage-table.md → "qa-analyst"
    Input: codebase-report.md, PROJECT_RULES.md
    Output: Standards Coverage Table + ISSUE-XXX for gaps

Task tool 3:
  subagent_type: "devops-engineer"
  model: "opus"
  description: "DevOps analysis"
  prompt: |
    **MODE: ANALYSIS ONLY**
    Check ALL 7 sections per shared-patterns/standards-coverage-table.md → "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: "sre"
  model: "opus"
  description: "Observability analysis"
  prompt: |
    **MODE: ANALYSIS ONLY**
    Check ALL 6 sections per shared-patterns/standards-coverage-table.md → "sre"
    Input: codebase-report.md, PROJECT_RULES.md
    Output: Standards Coverage Table + ISSUE-XXX for gaps

For TypeScript Backend projects:

Task tool 1:
  subagent_type: "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 → "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):

Task tool 5:
  subagent_type: "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 → "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:

Task tool 6:
  subagent_type: "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/
├── backend-engineer-golang-report.md     (if Go project)
├── backend-engineer-typescript-report.md (if TypeScript Backend)
├── frontend-engineer-report.md           (if Frontend)
├── frontend-bff-engineer-report.md       (if BFF)
├── qa-analyst-report.md                  (always)
├── devops-engineer-report.md             (always)
└── sre-report.md                         (always)

Report File Format

Use Write tool for EACH agent report:

# {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 dev-refactor skill*

Agent Report Mapping

Agent Dispatched	Report File Name
backend-engineer-golang	backend-engineer-golang-report.md
backend-engineer-typescript	backend-engineer-typescript-report.md
frontend-engineer	frontend-engineer-report.md
frontend-bff-engineer-typescript	frontend-bff-engineer-report.md
qa-analyst	qa-analyst-report.md
devops-engineer	devops-engineer-report.md
sre	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:

### 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):

## 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.

# 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

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

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)
│   ├── backend-engineer-golang-report.md
│   ├── qa-analyst-report.md
│   ├── devops-engineer-report.md
│   └── sre-report.md
├── findings.md         (Step 5)
└── tasks.md           (Step 7)

TodoWrite: Mark "Save all artifacts" as completed

---

Step 10: Handoff to dev-cycle

TodoWrite: Mark "Handoff to dev-cycle" as in_progress

If user approved, use SlashCommand tool with tasks path:

SlashCommand:
  command: "/dev-cycle docs/refactor/{timestamp}/tasks.md"

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

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

TodoWrite: Mark "Handoff to dev-cycle" as completed

---

Output Schema

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