Dev Refactor

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.

Anti-Rationalization: Mandatory Gap Principle

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

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:

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:

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

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

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

Anti-Rationalization Table for Step 4.5

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.

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.

⛔ 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:

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

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 Skill tool to invoke dev-cycle directly:

Skill tool:
  skill: "dev-cycle"

⛔ CRITICAL: Pass tasks file path in context: After invoking the skill, provide the tasks file location:

• Tasks file: docs/refactor/{timestamp}/tasks.md

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

Anti-Rationalization: Skill Invocation

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

If user approved execution, you MUST:

1. Invoke Skill tool: dev-cycle
2. Pass tasks file path: docs/refactor/{timestamp}/tasks.md
3. Wait for dev-cycle to complete all 6 gates

Skipping this step = SKILL FAILURE.

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

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

Execution Report

Base metrics per shared-patterns/output-execution-report.md.

Refactor-Specific Metrics

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