marsai:dev-refactor-frontend

Dev Refactor Frontend Skill

Analyzes existing frontend codebase against MarsAI/V4-Company standards and generates refactoring tasks compatible with marsai:dev-cycle-frontend.

---

Standards Loading (MANDATORY)

Before any step execution, you MUST load MarsAI standards.

Standards Source Resolution

if standards_path is provided:
  → Read tool: {standards_path}
  → If file not found or empty: STOP and report blocker
  → Use loaded content as frontend standards
else:
  → WebFetch the default MarsAI standards (see URLs below)

Default URLs (used when standards_path is not provided):

<fetch_required> https://raw.githubusercontent.com/V4-Company/marsai/main/CLAUDE.md https://raw.githubusercontent.com/V4-Company/marsai/main/dev-team/docs/standards/frontend.md </fetch_required>

Fetch URLs above and extract: Agent Modification Verification requirements, Anti-Rationalization Tables requirements, Critical Rules, and Frontend Standards.

<block_condition>

• standards_path provided but file not found or empty
• standards_path not provided AND WebFetch fails or returns empty
• CLAUDE.md not accessible </block_condition>

If any condition is true, STOP and report blocker. Cannot proceed without MarsAI standards.

---

MANDATORY GAP PRINCIPLE (NON-NEGOTIABLE)

any divergence from MarsAI 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 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-checkmark items in all Standards Coverage Tables) == COUNT(FINDING-XXX entries)

If counts don't match -> SKILL FAILURE. Go back and add missing findings.

---

Severity Calibration

Severity	Criteria	Examples
CRITICAL	Security risk, accessibility legal issue, production blocker	XSS vulnerability, WCAG violation blocking users, build broken
HIGH	Major standards violation, performance regression	Missing server components, Lighthouse < 80, wrong pattern
MEDIUM	Code quality, component structure issues	Client component overuse, missing snapshots
LOW	Best practices, documentation	Naming conventions, file organization

All severities are MANDATORY to track. Severity affects PRIORITY of execution, NOT whether to track.

---

Architecture Pattern Applicability

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

Service Type	Component Architecture	Directory Structure
Full React/Next.js App	APPLY (App Router, Server/Client components)	APPLY (frontend.md section 11)
Design System Library	APPLY	APPLY
Landing Page / Static	PARTIAL	APPLY
Utility / Config Package	NOT APPLICABLE	NOT APPLICABLE

Detection Criteria

Full React/Next.js App (Frontend Standards APPLICABLE):

• Project uses React/Next.js as framework
• Contains components, pages, and state management
• Uses App Router or Pages Router
• Has frontend routing and navigation
• -> MUST follow frontend.md standards

Simple Frontend (Partial applicability):

• Landing pages with minimal interactivity
• Static site generators (no dynamic data)
• -> Apply directory structure and styling; skip state management, BFF patterns

Agent Instruction

When dispatching specialist agents, include:

ARCHITECTURE APPLICABILITY CHECK:
1. If project is a full React/Next.js app -> APPLY all frontend.md sections
2. If project is a static/landing page -> APPLY directory structure and styling only
3. If project is a utility package -> Do not flag frontend-specific gaps

---

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 frontend stack and UI library mode"
      status: "pending"
      activeForm: "Detecting frontend stack"
    - content: "Read PROJECT_RULES.md for context"
      status: "pending"
      activeForm: "Reading PROJECT_RULES.md"
    - content: "Generate codebase report via marsai:codebase-explorer"
      status: "pending"
      activeForm: "Generating codebase report"
    - content: "Dispatch frontend specialist agents in parallel"
      status: "pending"
      activeForm: "Dispatching frontend 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: "Map findings 1:1 to REFACTOR-XXX tasks"
      status: "pending"
      activeForm: "Mapping findings to tasks (1:1)"
    - content: "Generate tasks.md"
      status: "pending"
      activeForm: "Generating tasks.md"
    - content: "Generate visual change report"
      status: "pending"
      activeForm: "Generating visual change report"
    - content: "Get user approval"
      status: "pending"
      activeForm: "Getting user approval"
    - content: "Save all artifacts"
      status: "pending"
      activeForm: "Saving artifacts"
    - content: "Handoff to marsai:dev-cycle-frontend"
      status: "pending"
      activeForm: "Handing off to marsai:dev-cycle-frontend"

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

---

Input Flags: Early Exit Check

if dry_run == true:
  → Execute Step 1 (Validate PROJECT_RULES.md) and Step 1b (Detect Frontend Stack)
  → Output dry-run summary:
      - Project path: {project_path or current directory}
      - Standards source: {standards_path or "MarsAI defaults via WebFetch"}
      - Frontend stack detected: {React/Next.js version}
      - UI library mode: {sindarian-ui / fallback-only}
      - Agents that would be dispatched: {list of 5-7 agents}
      - Conditional agents: {BFF if detected, UI Engineer if ux-criteria.md exists}
      - Artifact path: docs/marsai:dev-refactor-frontend/{timestamp}/
  → Mark all remaining todos as `completed` (skipped - dry run)
  → TERMINATE with "Dry run complete. Re-run without --dry-run to execute."

If dry_run is not true, continue to next section.

---

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 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 1b.

Check: Does docs/PROJECT_RULES.md exist?

• YES -> Mark todo as completed, continue to Step 1b
• 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 1b: Detect Frontend Stack

TodoWrite: Mark "Detect frontend stack and UI library mode" as in_progress

⛔ SCOPE: FRONTEND AND BFF CODE ONLY. This skill analyzes frontend code (React, Next.js) and BFF layers exclusively. MUST use marsai:dev-refactor for backend code (pure TypeScript backend with Express/Fastify/NestJS without React).

⛔ FORBIDDEN: Dispatching marsai:backend-engineer-typescript from this skill. This is a backend agent and belongs to marsai:dev-refactor.

MANDATORY: Verify this is a frontend project. If not, redirect.

Check for frontend indicators:

Check	Detection	Result
package.json exists	Glob for package.json	Required
React/Next.js in deps	react, next in dependencies	Required for frontend
@V4-Company/sindarian-ui in deps	Check dependencies/devDependencies	Store ui_library_mode
BFF layer detected	/api/ routes, Express/Fastify in deps	Add marsai:frontend-bff-engineer-typescript
ux-criteria.md exists	docs/pre-dev/*/ux-criteria.md	Add marsai:ui-engineer

Detection Logic:

1. package.json exists?
   NO  -> STOP: "Not a Node.js project. Use marsai:dev-refactor instead."
   YES -> Continue

2. React or Next.js in dependencies?
   NO  -> STOP: "Not a frontend project. Use marsai:dev-refactor instead."
   YES -> Continue

3. @V4-Company/sindarian-ui in dependencies?
   YES -> ui_library_mode = "sindarian-ui"
   NO  -> ui_library_mode = "fallback-only"

4. BFF layer detected? (/api/ routes, Express/Fastify in deps)
   YES -> dispatch_bff = true
   NO  -> dispatch_bff = false

5. ux-criteria.md exists?
   YES -> dispatch_ui_engineer = true
   NO  -> dispatch_ui_engineer = false

TodoWrite: Mark "Detect frontend stack and UI library mode" 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 marsai:codebase-explorer" as in_progress

MANDATORY: Use Task Tool with marsai:codebase-explorer

<dispatch_required agent="marsai:codebase-explorer"> Generate a comprehensive frontend codebase report describing WHAT EXISTS.

Include:

• Project structure and directory layout
• React/Next.js architecture (App Router vs Pages Router, Server vs Client components)
• UI library usage (sindarian-ui, shadcn/ui, custom components)
• State management patterns (TanStack Query, Zustand, Context)
• Form handling patterns (React Hook Form, Zod)
• Styling approach (TailwindCSS, CSS Modules, styled-components)
• Testing setup (Vitest, Playwright, Testing Library)
• Performance configuration (next.config, image optimization)
• 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

See shared-patterns/anti-rationalization-codebase-explorer.md for the marsai:codebase-explorer dispatch anti-rationalization table.

FORBIDDEN Actions for Step 3

- Bash(command="find ... -name '*.tsx'") -> 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

Any of these = IMMEDIATE SKILL FAILURE.

REQUIRED Action for Step 3

Task(subagent_type="marsai:codebase-explorer", ...)

Timestamp format: {timestamp} = YYYY-MM-DDTHH:MM:SS (e.g., 2026-02-10T15:30:00). Generate once at start, reuse for all artifacts.

After Task completes, save with Write tool:

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

TodoWrite: Mark "Generate codebase report via marsai:codebase-explorer" as completed

---

Step 4: Dispatch Frontend Specialist Agents

TodoWrite: Mark "Dispatch frontend specialist agents in parallel" as in_progress

HARD GATE: Verify codebase-report.md Exists

BEFORE dispatching any specialist agent, verify:

Check 1: Does docs/marsai:dev-refactor-frontend/{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 marsai: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.

MANDATORY: Reference Standards Coverage Table

All agents MUST follow shared-patterns/standards-coverage-table.md which defines:

• All sections to check per agent
• 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.

---

Always Dispatched (5 agents in parallel)

Dispatch all 5 agents in ONE message (parallel):

Task tool 1:
  subagent_type: "marsai:frontend-engineer"
  description: "Frontend standards analysis"
  prompt: |
    **MODE: ANALYSIS only**

    MANDATORY: Check all 19 sections in frontend.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 frontend.md standards via WebFetch -> extract all listed frameworks/libraries
    3. For each category in standards (Framework, State, Forms, UI, Styling, 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

    UI Library Mode: {ui_library_mode}

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

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

Task tool 2:
  subagent_type: "marsai:qa-analyst-frontend"
  description: "Frontend testing analysis"
  prompt: |
    **MODE: ANALYSIS only**

    MANDATORY: Check all 19 testing sections per shared-patterns/standards-coverage-table.md -> "marsai:qa-analyst-frontend"

    Analyze ALL testing dimensions:
    - Accessibility (ACC-1 to ACC-5): axe-core, semantic HTML, keyboard nav, focus, color contrast
    - Visual (VIS-1 to VIS-4): snapshots, state coverage, responsive, component duplication
    - E2E (E2E-1 to E2E-5): user flows, error paths, cross-browser, responsive, selectors
    - Performance (PERF-1 to PERF-5): Core Web Vitals, Lighthouse, bundle, server components, anti-patterns

    UI Library Mode: {ui_library_mode}

    Input:
    - MarsAI Standards: Load via WebFetch (frontend/testing-accessibility.md, testing-visual.md, testing-e2e.md, testing-performance.md)
    - Section Index: See shared-patterns/standards-coverage-table.md -> "marsai:qa-analyst-frontend"
    - Codebase Report: docs/marsai:dev-refactor-frontend/{timestamp}/codebase-report.md
    - Project Rules: docs/PROJECT_RULES.md

    Output:
    1. Standards Coverage Table (per shared-patterns format) for ALL 19 sections
    2. ISSUE-XXX for each non-compliant finding

Task tool 3:
  subagent_type: "marsai:frontend-designer"
  description: "Frontend design analysis"
  prompt: |
    **MODE: ANALYSIS only**

    MANDATORY: Check all 19 sections in frontend.md per shared-patterns/standards-coverage-table.md -> "marsai:frontend-designer"

    Focus on design perspective:
    - Typography standards (font selection, pairing, hierarchy)
    - Styling standards (TailwindCSS, CSS variables, design tokens)
    - Animation standards (transitions, Framer Motion usage)
    - Component patterns (compound components, design system compliance)
    - Accessibility UX (color contrast, focus indicators, motion preferences)

    UI Library Mode: {ui_library_mode}

    Input:
    - MarsAI Standards: Load via WebFetch (frontend.md)
    - Section Index: See shared-patterns/standards-coverage-table.md -> "marsai:frontend-designer"
    - Codebase Report: docs/marsai:dev-refactor-frontend/{timestamp}/codebase-report.md
    - Project Rules: docs/PROJECT_RULES.md

    Output:
    1. Standards Coverage Table (per shared-patterns format)
    2. ISSUE-XXX for each non-compliant finding

Task tool 4:
  subagent_type: "marsai:devops-engineer"
  description: "DevOps analysis"
  prompt: |
    **MODE: ANALYSIS only**
    Check all 8 sections per shared-patterns/standards-coverage-table.md -> "marsai:devops-engineer"

    Frontend-specific DevOps focus:
    - Dockerfile for SSR/SSG Next.js app
    - Docker Compose for local development
    - Nginx configuration for static assets/reverse proxy
    - .env management for frontend environment variables
    - Makefile with frontend commands (dev, build, lint, test, e2e)
    - CI/CD pipeline for frontend build/test/deploy

    "Containers" means BOTH Dockerfile and Docker Compose
    "Makefile Standards" means all required commands

    Input:
    - MarsAI Standards: Load via WebFetch (devops.md)
    - Codebase Report: docs/marsai:dev-refactor-frontend/{timestamp}/codebase-report.md
    - Project Rules: docs/PROJECT_RULES.md

    Output: Standards Coverage Table + ISSUE-XXX for gaps

Task tool 5:
  subagent_type: "marsai:sre"
  description: "Observability analysis"
  prompt: |
    **MODE: ANALYSIS only**
    Check all 6 sections per shared-patterns/standards-coverage-table.md -> "marsai:sre"

    Frontend-specific observability focus:
    - Error tracking (error boundaries, global error handlers)
    - Health check endpoints (if SSR)
    - Real User Monitoring (RUM) / Core Web Vitals reporting
    - Structured client-side logging
    - Distributed tracing for BFF/API calls

    Input:
    - MarsAI Standards: Load via WebFetch (sre.md)
    - Codebase Report: docs/marsai:dev-refactor-frontend/{timestamp}/codebase-report.md
    - Project Rules: docs/PROJECT_RULES.md

    Output: Standards Coverage Table + ISSUE-XXX for gaps

Conditionally Dispatched

Add to the parallel dispatch if conditions from Step 1b are met:

Task tool 6 (if dispatch_bff == true):
  subagent_type: "marsai:frontend-bff-engineer-typescript"
  description: "BFF TypeScript standards analysis"
  prompt: |
    **MODE: ANALYSIS only**

    MANDATORY: Check all 20 sections in typescript.md per shared-patterns/standards-coverage-table.md -> "frontend-bff-engineer-typescript"

    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

    UI Library Mode: {ui_library_mode}

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

    Output:
    1. Standards Coverage Table (per shared-patterns format)
    2. ISSUE-XXX for each non-compliant finding

Task tool 7 (if dispatch_ui_engineer == true):
  subagent_type: "marsai:ui-engineer"
  description: "UI engineer standards analysis"
  prompt: |
    **MODE: ANALYSIS only**

    MANDATORY: Check all 19 sections in frontend.md per shared-patterns/standards-coverage-table.md -> "marsai:ui-engineer"

    Additionally verify against product-designer outputs:
    - UX criteria compliance (ux-criteria.md)
    - User flow implementation (user-flows.md)
    - Wireframe adherence (wireframes/*.yaml)
    - UI states coverage (loading, error, empty, success)

    UI Library Mode: {ui_library_mode}

    Input:
    - MarsAI Standards: Load via WebFetch (frontend.md)
    - Section Index: See shared-patterns/standards-coverage-table.md -> "marsai:ui-engineer"
    - UX Criteria: docs/pre-dev/{feature}/ux-criteria.md
    - Codebase Report: docs/marsai:dev-refactor-frontend/{timestamp}/codebase-report.md
    - Project Rules: docs/PROJECT_RULES.md

    Output:
    1. Standards Coverage Table (per shared-patterns format)
    2. UX Criteria Compliance table
    3. ISSUE-XXX for each non-compliant finding

Agent Dispatch Summary

Condition	Agents to Dispatch
Always	Tasks 1-5 (Frontend Engineer + QA Frontend + Designer + DevOps + SRE)
BFF layer detected	+ Task 6 (BFF Engineer)
ux-criteria.md exists	+ Task 7 (UI Engineer)

TodoWrite: Mark "Dispatch frontend specialist agents in parallel" as completed

---

Step 4.5: 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 MarsAI standard	-> Create FINDING-XXX
Any missing pattern from MarsAI standards	-> Create FINDING-XXX
Any deprecated pattern usage	-> Create FINDING-XXX
Any accessibility gap	-> Create FINDING-XXX
Any testing gap	-> Create FINDING-XXX
Any performance issue	-> Create FINDING-XXX

FORBIDDEN Actions for Step 4.5

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

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-compliant 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.5

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 is not 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.5

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

This means:

• Compliant items in Standards Coverage Table = No finding needed
• Partial items = MUST create FINDING-XXX (partial compliance is a gap)
• Non-compliant 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 (Frontend 9-Gate Cycle)

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

Finding Category	Should Be Caught In	Flag
Implementation pattern gaps	Gate 0 (Implementation)	Normal finding
React/Next.js architectural issues	Gate 0 (Implementation)	Normal finding
Docker/DevOps gaps	Gate 1 (DevOps)	GATE 1 ESCAPE
WCAG violations, keyboard nav, ARIA	Gate 2 (Accessibility)	GATE 2 ESCAPE
Semantic HTML, focus management	Gate 2 (Accessibility)	GATE 2 ESCAPE
Unit test gaps, coverage <85%	Gate 3 (Unit Testing)	GATE 3 ESCAPE
Test isolation issues	Gate 3 (Unit Testing)	GATE 3 ESCAPE
Missing snapshot tests	Gate 4 (Visual)	GATE 4 ESCAPE
Missing state/responsive coverage	Gate 4 (Visual)	GATE 4 ESCAPE
sindarian-ui component duplication	Gate 4 (Visual)	GATE 4 ESCAPE
Untested user flows	Gate 5 (E2E)	GATE 5 ESCAPE
Cross-browser issues	Gate 5 (E2E)	GATE 5 ESCAPE
Flaky tests	Gate 5 (E2E)	GATE 5 ESCAPE
CWV violations (LCP > 2.5s, CLS > 0.1, INP > 200ms)	Gate 6 (Performance)	GATE 6 ESCAPE
Lighthouse < 90	Gate 6 (Performance)	GATE 6 ESCAPE
Bundle size bloat	Gate 6 (Performance)	GATE 6 ESCAPE
Bare <img> tags (not next/image)	Gate 6 (Performance)	GATE 6 ESCAPE
Code quality (reviewer-catchable)	Gate 7 (Review)	GATE 7 ESCAPE

Gate Escape Output Format:

### FINDING-XXX: [Issue Title] GATE N ESCAPE

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

[Rest of finding format...]

Purpose: Track which issues escape which gates. If many escapes occur at a gate, that gate's exit criteria 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 (Accessibility) | N | [type] |
| Gate 3 (Unit Testing) | N | [type] |
| Gate 4 (Visual) | N | [type] |
| Gate 5 (E2E) | N | [type] |
| Gate 6 (Performance) | N | [type] |
| Gate 7 (Review) | 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 4.6: 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/marsai:dev-refactor-frontend/{timestamp}/reports/
+-- marsai:frontend-engineer-report.md           (always)
+-- marsai:qa-analyst-frontend-report.md         (always)
+-- marsai:frontend-designer-report.md           (always)
+-- marsai:devops-engineer-report.md             (always)
+-- marsai:sre-report.md                         (always)
+-- marsai:frontend-bff-engineer-typescript-report.md       (if BFF detected)
+-- marsai:ui-engineer-report.md                 (if ux-criteria.md exists)

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 marsai:dev-refactor-frontend skill*

Anti-Rationalization Table for Step 4.6

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

Write tool:
  file_path: "docs/marsai:dev-refactor-frontend/{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 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.5. 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: MarsAI 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.5

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 is not clear to implementer.	Complete all sections without exception
"I'll group small findings together"	Each finding = one task in Step 6. 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}
**UI Library Mode:** {ui_library_mode}

## Mandatory Gap Principle Applied

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

| Metric | Count |
|--------|-------|
| Total non-compliant 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:** {component-architecture | ui-library | styling | accessibility | testing | performance | devops}
**Agent:** {agent-name}
**Standard:** {file}.md:{section}

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

MarsAI Standard Reference

Standard: {standards-file}.md -> Section: {section-name} Pattern: {pattern-name} URL: https://raw.githubusercontent.com/V4-Company/marsai/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 MarsAI standards}
• Impact: {business/technical impact if not fixed}

---

FINDING-002: ...

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

---

## Step 6: Map Findings to Tasks (1:1)

**TodoWrite:** Mark "Map findings 1:1 to REFACTOR-XXX tasks" as `in_progress`

**HARD GATE: One FINDING-XXX = One REFACTOR-XXX task. No grouping.**

Each finding becomes its own task. This prevents findings from being lost inside grouped tasks.

**1:1 Mapping Rule:**
- FINDING-001 -> REFACTOR-001
- FINDING-002 -> REFACTOR-002
- FINDING-NNN -> REFACTOR-NNN

**Ordemarsai:** Sort tasks by severity (Critical first), then by dependency order.

**Mapping Verification:**

Before proceeding to Step 7, verify:

• Total FINDING-XXX in findings.md: X
• Total REFACTOR-XXX in tasks.md: X (MUST MATCH exactly)
• Orphan findings (not mapped): 0 (MUST BE ZERO)
• Grouped tasks (multiple findings): 0 (MUST BE ZERO)

**If counts don't match, STOP. Every finding MUST have its own task.**

### Anti-Rationalization Table for Step 6

| Rationalization | Why It's WRONG | Required Action |
|-----------------|----------------|-----------------|
| "These findings are in the same file, I'll group them" | Grouping hides findings. One fix may be done, others forgotten. | **One finding = One task. No exceptions.** |
| "Grouping reduces task count and is easier to manage" | Fewer tasks = less visibility. Each finding needs independent tracking. | **Create one REFACTOR-XXX per FINDING-XXX** |
| "These are related and should be fixed together" | Related is not same task. marsai:dev-cycle-frontend can execute them sequentially. | **Separate tasks, use Dependencies field to link** |
| "Too many tasks will overwhelm the developer" | Missing fixes overwhelms production. Completeness > convenience. | **Create all tasks. Priority handles ordering.** |

**TodoWrite:** Mark "Map findings 1:1 to 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}
**UI Library Mode:** {ui_library_mode}

## Mandatory 1:1 Mapping Verification

**Every FINDING-XXX has exactly one REFACTOR-XXX. No grouping.**

| Metric | Count |
|--------|-------|
| Total FINDING-XXX in findings.md | {X} |
| Total REFACTOR-XXX in tasks.md | {X} |
| **Counts match exactly?** | YES (REQUIRED) |
| Grouped tasks (multiple findings) | 0 (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: {Finding Pattern Name}

**Finding:** FINDING-001
**Severity:** Critical | High | Medium | Low (all ARE MANDATORY)
**Category:** {component-architecture | ui-library | styling | accessibility | testing | performance | devops}
**Agent:** {agent-name}
**Effort:** {hours}h
**Dependencies:** {other REFACTOR-XXX tasks or none}

### Current Code
```{lang}
// file: {path}:{lines}
{actual code from FINDING-001}

MarsAI Standard Reference

Standard File	Section	URL
{file}.md	{section}	Link

Required Actions

1. {action 1 - specific change to make}
2. {action 2 - pattern to implement}

Acceptance Criteria

• Code follows {standard}.md -> {section} pattern
• No {anti-pattern} usage remains
• Tests pass after refactoring

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

---

## Step 7.5: Visual Change Report

**TodoWrite:** Mark "Generate visual change report" as `in_progress`

**MANDATORY:** Invoke `Skill("marsai:visual-explainer")` to produce a self-contained HTML page showing all planned frontend refactoring changes. This replaces reading raw findings.md / tasks.md markdown for approval decisions.

**Read the code-diff template first:** Read `default/skills/visual-explainer/templates/code-diff.html` to absorb the patterns before generating.

**Generate the HTML report with these sections:**

### 1. Summary Dashboard
- UI Library Mode (from findings.md header)
- Total FINDING-XXX count with severity breakdown (Critical / High / Medium / Low)
- Total files affected (unique file paths from all findings)
- Horizontal severity breakdown bar

### 2. Per-Finding Diff Panels (one section per FINDING-XXX)
For each FINDING-XXX in findings.md:
- **Header:** Finding ID, severity badge, category, agent that reported it
- **Before panel:** Current Code block from findings.md (with file:line reference, syntax highlighted via Highlight.js)
- **After panel:** MarsAI Standard pattern from Required Changes section (syntax highlighted)
- **Collapsible "Why This Matters":** Problem / Standard Violated / Impact from findings.md

### 3. Task Mapping Table
Table showing: FINDING-XXX → REFACTOR-XXX → Severity → Category → Estimated Effort

**Output:** Save to `docs/marsai:dev-refactor-frontend/{timestamp}/change-report.html`

**Open in browser:**
```text
macOS: open docs/marsai:dev-refactor-frontend/{timestamp}/change-report.html
Linux: xdg-open docs/marsai:dev-refactor-frontend/{timestamp}/change-report.html

Tell the user the file path. The report opens before the approval question so the user can review changes visually.

See shared-patterns/anti-rationalization-visual-report.md for anti-rationalization table.

TodoWrite: Mark "Generate visual change report" as completed

---

Step 8: User Approval

TodoWrite: Mark "Get user approval" as in_progress

Auto-Resolution via Input Flags

if analyze_only == true:
  → Auto-select "Cancel" (analysis complete, skip execution)
  → Output: "analyze_only=true — analysis artifacts saved, skipping marsai:dev-cycle-frontend."
  → Skip to Step 9 (Save Artifacts), then TERMINATE after Step 9.

if critical_only == true:
  → Auto-select "Critical only" (no user prompt needed)
  → Output: "critical_only=true — auto-selecting Critical/High tasks only."
  → Continue to Step 9, then Step 10 with Critical/High tasks.

Interactive Approval (when no auto-resolution flags are set)

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

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

CANNOT proceed without explicit user selection (or an auto-resolution flag).

TodoWrite: Mark "Get user approval" as completed

---

Step 9: Save Artifacts

TodoWrite: Mark "Save all artifacts" as in_progress

docs/marsai:dev-refactor-frontend/{timestamp}/
+-- codebase-report.md  (Step 3)
+-- reports/            (Step 4.6)
|   +-- marsai:frontend-engineer-report.md
|   +-- marsai:qa-analyst-frontend-report.md
|   +-- marsai:frontend-designer-report.md
|   +-- marsai:devops-engineer-report.md
|   +-- marsai:sre-report.md
|   +-- marsai:frontend-bff-engineer-typescript-report.md    (conditional)
|   +-- marsai:ui-engineer-report.md              (conditional)
+-- findings.md         (Step 5)
+-- tasks.md           (Step 7)
+-- change-report.html (Step 7.5)

TodoWrite: Mark "Save all artifacts" as completed

---

Step 10: Handoff to marsai:dev-cycle-frontend

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

Skip Conditions

if analyze_only == true:
  → Output: "analyze_only=true — skipping handoff. Artifacts saved at docs/marsai:dev-refactor-frontend/{timestamp}/."
  → Mark todo as `completed`
  → TERMINATE.

if dry_run == true:
  → This step is unreachable (dry_run exits after Step 1b).

if user selected "Cancel" in Step 8:
  → Output: "User cancelled execution. Artifacts saved at docs/marsai:dev-refactor-frontend/{timestamp}/."
  → Mark todo as `completed`
  → TERMINATE.

Execution (when user approved or critical_only resolved)

Use Skill tool to invoke marsai:dev-cycle-frontend directly:

Skill tool:
  skill: "marsai:dev-cycle-frontend"

CRITICAL: Pass tasks file path in context:

After invoking the skill, provide:

• Tasks file: docs/marsai:dev-refactor-frontend/{timestamp}/tasks.md

Context for marsai:dev-cycle-frontend:
  tasks-file: "docs/marsai:dev-refactor-frontend/{timestamp}/tasks.md"

Where {timestamp} format is YYYY-MM-DDTHH:MM:SS. Use the same timestamp across all artifacts in a single run.

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 /marsai:dev-cycle-frontend manually"	Manual run risks skill not being loaded	Invoke Skill tool directly
"marsai:dev-cycle-frontend will auto-discover tasks"	Explicit path ensures correct file is used	Pass explicit tasks path
"User approved, I can skip marsai:dev-cycle-frontend"	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
"analyze_only was not set but I'll skip anyway"	Only analyze_only, dry_run, or user "Cancel" can skip this step	Invoke Skill tool

HARD GATE: When execution is approved (user selected "Approve all" or "Critical only", or critical_only auto-resolved), you CANNOT complete marsai:dev-refactor-frontend without invoking Skill tool: marsai:dev-cycle-frontend.

If execution is approved, you MUST:

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

Skipping this step when execution is approved = SKILL FAILURE.

marsai:dev-cycle-frontend executes each REFACTOR-XXX task through the 9-gate frontend process.

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

---

Execution Report

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

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

Refactor-Frontend-Specific Metrics

Metric	Value
Agents Dispatched	N (5-7)
UI Library Mode	sindarian-ui / fallback-only
Findings Generated	N
Tasks Created	N
Gate Escapes Detected	N
Artifacts Location	docs/marsai:dev-refactor-frontend/{timestamp}/

Output Schema

artifacts:
  - codebase-report.md (Step 3)
  - reports/{agent-name}-report.md (Step 4.6)
  - findings.md (Step 5)
  - tasks.md (Step 7)
  - change-report.html (Step 7.5)

traceability:
  MarsAI Standard -> Agent Report -> FINDING-XXX -> REFACTOR-XXX -> Implementation