Analyzes codebase against standards and generates refactoring tasks for dev-cycle.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
name: dev-refactor description: Analyzes codebase against standards and generates refactoring tasks for dev-cycle. trigger: |
skip_when: |
Analyzes existing codebase against Ring/Lerian standards and generates refactoring tasks compatible with dev-cycle.
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 |
| 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 |
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.
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 |
CRUD API (Hexagonal/DDD APPLICABLE):
Simple Service (Hexagonal/DDD NOT applicable):
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.
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.
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.
TodoWrite: Mark "Validate PROJECT_RULES.md exists" as in_progress
Check: Does docs/PROJECT_RULES.md exist?
completed, continue to Step 1## 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.
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 agentpackage.json exists + next.config.* or React in dependencies → Add frontend agentpackage.json exists + /api/ routes or Express/Fastify → Add TypeScript backend agentpackage.json exists + BFF indicators (/bff/, gateway patterns) → Add BFF agentIf multiple stacks detected, dispatch agents for ALL.
TodoWrite: Mark "Detect project stack (Go/TypeScript/Frontend)" as completed
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
TodoWrite: Mark "Generate codebase report via codebase-explorer" as in_progress
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.**
| 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" |
❌ 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
✅ 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
TodoWrite: Mark "Dispatch specialist agents in parallel" as in_progress
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):
All agents MUST follow shared-patterns/standards-coverage-table.md which defines:
Section indexes are pre-defined in shared-patterns. Agents MUST check ALL sections listed.
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
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
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
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
| 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
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)
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 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 |
| 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 |
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
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 |
❌ 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
✅ 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
⛔ 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 |
Per the Mandatory Gap Principle (see top of skill): ANY divergence from Ring standards = FINDING-XXX.
This means:
Verification: Use formula from "Mandatory Gap Principle → Verification Rule" section.
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
TodoWrite: Mark "Generate findings.md" as in_progress
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.
❌ 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
✅ 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
| 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}
Standard: {standards-file}.md → Section: {section-name} Pattern: {pattern-name} URL: https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/{file}.md
**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:
**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
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
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
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
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