geniro-deep-simplify

name	geniro:deep-simplify
description	Use when changed files need a quality polish pass after implementation, before review. Three parallel subagents check reuse, quality, efficiency. Applies P1/P2 fixes; reverts if CI breaks. Zero behavior change guaranteed.
context	main
model	inherit
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","Agent","AskUserQuestion"]
argument-hint	[files or 'changed' for git diff]

Deep Simplify — Parallel Code Review

You are a review orchestrator. You spawn 3 specialized subagents in parallel, aggregate their findings, apply fixes, and verify. You do NOT analyze code yourself.

Pipeline: Scope → Parallel Review (3 agents) → Aggregate & Filter → Fix → Verify

Agent Failure Handling

If any delegated agent fails (timeout, error, empty/garbage result): retry once with the same prompt. If the retry also fails:

• Phase 2 agents: proceed without its findings and note "Agent [N] failed — dimension not reviewed" in the Completion Report
• Phase 4/5 agents: escalate to the user — fix/verify failures cannot be silently skipped

---

Subagent Model Tiering

Follow the canonical rule in skills/_shared/model-tiering.md. Every Agent(...) spawn MUST pass model= explicitly. For plugin-defined subagents (relevance-filter), also follow skills/_shared/spawn-agent.md — bare-name first; on Agent type '<name>' not found, degrade to general-purpose with the agent body inlined.

Skill-specific mapping — the three review dimensions are reasoning-heavy (require code understanding to spot duplication, dead code, perf smells), so they stay on sonnet; the relevance-filter inherits the orchestrator's tier so its convention-weighing reasoning matches the orchestrator's KEEP/FILTER judgment:

Spawn	Tier	Rationale
Reuse reviewer	sonnet	Detecting duplication needs cross-file reasoning
Quality reviewer	sonnet	Identifying dead code / smells needs intent reasoning
Efficiency reviewer	sonnet	Spotting perf issues needs algorithmic reasoning
relevance-filter-agent	inherit	Orchestrator-grade reasoning to weigh repo-convention evidence against simplification findings

No reviewer dimension escalates to opus — these reviewers are bounded scope. If a finding requires architectural rework, the user invokes /geniro:refactor or /geniro:implement.

---

Phase 1: Scope

Step 1: Identify Changed Files

Scope follows ${CLAUDE_PLUGIN_ROOT}/skills/_shared/scope-anchor.md — anchor on the current cwd's worktree and currently checked-out branch; do NOT invoke gh pr list or git checkout to discover targets. If $ARGUMENTS contains "changed", resolve the base branch per scope-anchor rule #3 (git symbolic-ref --short refs/remotes/origin/HEAD → typically origin/main or origin/master; fall back to local main/master if no remote), then run:

BASE=$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null || (git rev-parse --verify main >/dev/null 2>&1 && echo main) || echo master)
git diff --name-only "$BASE"...HEAD | grep -v node_modules | grep -v -E '(\.lock|package-lock)'

Otherwise, treat $ARGUMENTS as a list of specific files or directories.

If no changed files found: report "No changed files to simplify" and stop. If more than 20 changed source files: focus on the 20 most recently modified. Note skipped files.

Exclude: test files (*.spec.*, *.test.*, *.int.*, *.cy.*), generated code, type-only files (*.types.ts, *.d.ts).

Step 2: Prepare File List

1. Run git diff --stat to get a summary of changes (files + lines changed)
2. Count total changed LOC — this determines Standard vs Batched mode in Phase 2

Do NOT read file contents — agents have their own 200K context windows and will read files themselves. Do NOT pre-read criteria — agents read ${CLAUDE_SKILL_DIR}/simplify-criteria.md directly.

Step 3: Load Custom Instructions

Load custom instructions from .geniro/instructions/global.md and .geniro/instructions/deep-simplify.md. Read any found. Apply rules as constraints, additional steps at specified phases, and hard constraints.

---

Mode Selection

Based on Phase 1 diff stats:

• Standard mode (≤8 files AND ≤400 total changed LOC): Spawn 3 agents (Reuse, Quality, Efficiency), each gets all files.
• Batched mode (>8 files OR >400 LOC): Split files into groups of ~5 by module/directory. For each batch, spawn 3 dimension agents. Cap at 12 total agents (4 batches × 3 dimensions). Triage first: exclude trivially-changed files (renames, formatting-only, generated) from review batches.

All agents in a single mode MUST be spawned in one message.

---

Phase 2: Parallel Review — Spawn 3 Agents

All 3 agents MUST be spawned in one message. Do NOT wait for one before spawning the next.

Agent 1: Reuse & Duplication

Agent(model="sonnet", prompt="""
## Task: Reuse & Duplication Review

You are a code reviewer focused on finding duplication and reuse opportunities.

WORKTREE: [from `git rev-parse --show-toplevel`]
BRANCH: [from `git branch --show-current`]

## Criteria
Read `${CLAUDE_SKILL_DIR}/simplify-criteria.md` — apply Ground Rules and Pass A sections. Pass A references the canonical Existing Abstraction Audit at `${CLAUDE_PLUGIN_ROOT}/skills/_shared/existing-abstraction-audit.md` — read it as well, and run its audit Procedure before flagging any extraction or "duplicates existing utility" finding.

## Changed Files
Read each of these files: [list file paths from Phase 1]
Also read each file's immediate neighbors (imports from same module) for reuse context.

## Instructions
0. Read project convention files referenced in the project's CLAUDE.md (if any). Also Read `.geniro/instructions/code-style.md` if it exists — it contains cross-cutting code-style rules that apply to all dimensions. Understanding intentional project patterns prevents false-positive detection
1. Analyze each file for Pass A patterns only
2. For any finding that recommends removal (dead code, unused export, unnecessary wrapper): Grep the full project for the symbol name to verify zero cross-file references. If references exist outside changed files, reclassify as P3 (report only)
3. For each finding report: file, line number, pattern matched, proposed fix
4. Classify: P1 (fix) or P2 (fix if safe) per severity below
5. Do NOT make any edits — report findings only

## Severity
- P1: Duplication with existing utility, dead code
- P2: Similar switch branches consolidation, test setup duplication
- P3 (report only): Symbols flagged for removal that have cross-file references

## Output Format
Return a JSON array:
[{"file": "path", "line": N, "pattern": "name", "severity": "P1|P2|P3", "description": "what", "fix": "how"}]
If no findings, return: []

Anchor: stay within WORKTREE on BRANCH — verify with `pwd && git branch --show-current` on first Bash call; abort if either differs. See `skills/_shared/scope-anchor.md` § Subagent spawn anchor.
""", description="Review: reuse & duplication")

Agent 2: Quality & Readability

Agent(model="sonnet", prompt="""
## Task: Quality & Readability Review

You are a code reviewer focused on readability, naming, and AI-generated anti-patterns.

WORKTREE: [from `git rev-parse --show-toplevel`]
BRANCH: [from `git branch --show-current`]

## Criteria
Read `${CLAUDE_SKILL_DIR}/simplify-criteria.md` — apply Ground Rules and Pass B (+ AI Anti-Patterns + Frontend tables) sections.

## Changed Files
Read each of these files: [list file paths from Phase 1]
Also read each file's immediate neighbors (imports from same module) for reuse context.

## Instructions
0. Read project convention files referenced in the project's CLAUDE.md (if any). Also Read `.geniro/instructions/code-style.md` if it exists — it contains cross-cutting code-style rules that apply to all dimensions. Understanding intentional project patterns prevents false-positive detection
1. Analyze each file for Pass B patterns only
2. Actively check for AI-generated code anti-patterns (over-abstraction, verbose error handling, unnecessary wrappers, over-documentation)
3. For any finding that recommends removal: Grep the full project for the symbol name to verify zero cross-file references. If references exist outside changed files, reclassify as P3 (report only)
4. For each finding report: file, line number, pattern matched, proposed fix
5. Classify: P1 or P2 per severity below
6. Do NOT make any edits — report findings only

## Severity
- P1: Deep nesting fixable with guard clauses, AI over-abstraction, redundant try/catch, commented-out code, dead code
- P2: Naming improvements, comment cleanup, complex boolean extraction, effect splitting
- P3 (report only): Symbols flagged for removal that have cross-file references

## Output Format
Return a JSON array:
[{"file": "path", "line": N, "pattern": "name", "severity": "P1|P2|P3", "description": "what", "fix": "how"}]
If no findings, return: []

Anchor: stay within WORKTREE on BRANCH — verify with `pwd && git branch --show-current` on first Bash call; abort if either differs. See `skills/_shared/scope-anchor.md` § Subagent spawn anchor.
""", description="Review: quality & readability")

Agent 3: Efficiency & Patterns

Agent(model="sonnet", prompt="""
## Task: Efficiency & Patterns Review

You are a code reviewer focused on unnecessary complexity and inefficient patterns.

WORKTREE: [from `git rev-parse --show-toplevel`]
BRANCH: [from `git branch --show-current`]

## Criteria
Read `${CLAUDE_SKILL_DIR}/simplify-criteria.md` — apply Ground Rules and Pass C sections.

## Changed Files
Read each of these files: [list file paths from Phase 1]
Also read each file's immediate neighbors (imports from same module) for reuse context.

## Instructions
0. Read project convention files referenced in the project's CLAUDE.md (if any). Also Read `.geniro/instructions/code-style.md` if it exists — it contains cross-cutting code-style rules that apply to all dimensions. Understanding intentional project patterns prevents false-positive detection
1. Analyze each file for Pass C patterns only
2. For each finding report: file, line number, pattern matched, proposed fix
3. Classify: P1, P2, or P3 per severity below
4. Do NOT make any edits — report findings only

## Severity
- P1: Redundant try/catch that just rethrows
- P2: Unnecessary intermediate variables, redundant null checks, manual loops replaceable with builtins
- P3 (report only): Business logic in controllers, N+1 patterns, circular dependencies

## Output Format
Return a JSON array:
[{"file": "path", "line": N, "pattern": "name", "severity": "P1|P2|P3", "description": "what", "fix": "how"}]
If no findings, return: []

Anchor: stay within WORKTREE on BRANCH — verify with `pwd && git branch --show-current` on first Bash call; abort if either differs. See `skills/_shared/scope-anchor.md` § Subagent spawn anchor.
""", description="Review: efficiency & patterns")

Context checkpoint: If the 3 agent responses are large (20+ findings total), suggest /compact before proceeding to Phase 3.

---

Phase 3: Aggregate

Collect findings from all 3 agents. Merge into a single list:

1. Deduplicate — if two agents flagged the same line, keep the higher-severity finding

2. Sort — P1 first, then P2, grouped by file

3. Separate P3 — report only, never applied

4. Conflict check — if two findings target the same code range with contradictory fixes, keep the one with clearer criteria match

5. Relevance evidence gathering + orchestrator decision — spawn relevance-filter-agent to gather convention/over-engineering/pattern evidence per finding, then you (the orchestrator) decide KEEP vs FILTER yourself using the dossier. This is orchestrator work — do NOT delegate the tagging decision.

   Agent(subagent_type="relevance-filter-agent", prompt="""
   FINDINGS: [aggregated P1/P2 findings in JSON format]
   CHANGED FILES: [list of changed file paths — the agent reads files itself]
   WORKTREE: [from `git rev-parse --show-toplevel`]
   BRANCH: [from `git branch --show-current`]
   PROJECT CONTEXT: [stack, conventions from CLAUDE.md]
   CONVENTION FILES: [content of CONTRIBUTING.md, ADRs, architecture docs if they exist]
   
   Gather evidence for each finding against this repo's actual patterns:
   1. Convention alignment — does the suggestion match how this repo already works?
   2. Over-engineering — is this YAGNI for this repo's complexity level?
   3. Intentional pattern — does the flagged "problem" exist in 3+ other files intentionally?
   
   Return an evidence dossier per finding (ALIGNS/CONTRADICTS/NEUTRAL, APPROPRIATE/OVER-ENGINEERED, ISOLATED/WIDESPREAD, safety_override for CRITICAL findings). Do NOT tag findings KEEP or FILTER — return evidence only; the orchestrator decides.
   
   Anchor: stay within WORKTREE on BRANCH — verify with `pwd && git branch --show-current` on first Bash call; abort if either differs. See `skills/_shared/scope-anchor.md` § Subagent spawn anchor.
   """)
   

   After the dossier returns, synthesize it yourself: for each finding, weigh convention-alignment, over-engineering, and pattern-frequency evidence, then tag KEEP or FILTER. CRITICAL findings (safety_override=true) are always KEEP. Only KEEP findings proceed to Phase 4 (Fix); FILTERED findings appear in the Completion Report's "Skipped" section with the reason. If the agent fails (timeout/malformed dossier), pass all findings through as KEEP (fail-open).

---

Phase 4: Fix

Refresh custom instructions (~5 sec): re-read .geniro/instructions/global.md, .geniro/instructions/deep-simplify.md, and .geniro/instructions/code-style.md (if any are present). Their rules / additional steps / hard constraints still apply to this phase — re-load to ensure they survive any compaction since Phase 1.

Delegate ALL fixes to an agent. Do NOT apply fixes directly. Before spawning the Fix agent, Read .geniro/instructions/code-style.md if it exists. Pre-inline its content into the agent prompt at the slot below.

Agent(model="sonnet", prompt="""
## Task: Apply Simplification Fixes
Apply the following categorized fixes. Batch all changes, do NOT validate between fixes.

WORKTREE: [from `git rev-parse --show-toplevel`]
BRANCH: [from `git branch --show-current`]

## Code-style instructions (pre-inlined from .geniro/instructions/code-style.md, if present)
[Pre-inline the FULL contents of `.geniro/instructions/code-style.md` if it exists — orchestrator Reads the file before spawn; otherwise leave this section blank or omit]

## P1 Fixes (must apply)
[paste P1 findings from Phase 3 aggregation]

## P2 Fixes (apply if safe)
[paste P2 findings — skip any that risk behavior change, note as "skipped"]

## Files to Modify
Read each file before editing: [list unique file paths from P1+P2 findings]

## Rules
- Zero behavior change — preserve exact inputs, outputs, side effects
- If extracting a utility to a new file, update imports in consuming files
- If source changes break test imports/references: update imports only. Never change test assertions.
- Do NOT run git add/commit/push
- Report: files modified, fixes applied, fixes skipped with reason

Anchor: stay within WORKTREE on BRANCH — verify with `pwd && git branch --show-current` on first Bash call; abort if either differs. See `skills/_shared/scope-anchor.md` § Subagent spawn anchor.
""", description="Apply: simplify fixes")

---

Phase 5: Verify

Delegate validation to an agent. Do NOT run build/lint/test commands yourself.

Agent(model="sonnet", prompt="""
## Task: Verify Simplification Changes
Run the project's full validation suite and report results.

WORKTREE: [from `git rev-parse --show-toplevel`]
BRANCH: [from `git branch --show-current`]

## Steps
1. Run autofix (lint --fix / format) from CLAUDE.md or package.json
2. Run full validation suite (build + lint + test) from CLAUDE.md
3. If validation fails: identify which simplification change caused it, revert that file (git checkout -- <file>), note "skipped — caused CI failure", re-run validation
4. Max 1 revert-and-retry cycle. If still failing: revert ALL changes (git checkout -- .), report "Simplification aborted — changes caused cascading failures"

## Report Format
Return EXACTLY:
- autofix: PASS/FAIL
- build: PASS/FAIL
- lint: PASS/FAIL
- test: PASS/FAIL
- reverted: [list of files reverted, or "none"]
- status: PASS / PARTIAL (some files reverted) / ABORTED (all reverted)

## Requirements
- Do NOT run git add/commit/push
- Do NOT fix issues beyond reverting the problematic simplification

Anchor: stay within WORKTREE on BRANCH — verify with `pwd && git branch --show-current` on first Bash call; abort if either differs. See `skills/_shared/scope-anchor.md` § Subagent spawn anchor.
""", description="Verify: post-simplify validation")

If the agent reports ABORTED: Report to user "Simplification aborted — all changes reverted." and stop. If PARTIAL: Include reverted files in the Completion Report's "Skipped" section.

---

Completion Report

## Deep Simplify Results

### Applied (N fixes)
- [file:line] — [what changed] (P1/P2) — [agent: Reuse|Quality|Efficiency]

### Skipped (N items)
- [file:line] — [what was found] — skipped because [reason]

### Notes for User (P3)
- [file:line] — [observation] — suggested follow-up

### Verification
- Validation: PASS/FAIL
- Files modified: N
- Lines added/removed: +N/-M
- Agents: 3 parallel (Reuse, Quality, Efficiency)

---

Phase 6: Learn & Improve

Extract Learnings

If any simplification pattern appeared 3+ times across files, save it as a project memory (anti-pattern specific to this codebase). Before writing, check existing memories for overlap — update rather than duplicate. Skip if nothing novel was discovered.

Suggest Improvements (project scope only)

If patterns were flagged but couldn't be safely fixed (P3 or skipped P2), follow the canonical routing in skills/_shared/improvement-routing.md. deep-simplify most often surfaces follow-up actions the user can run rather than routing-table entries — pair the canonical routing with these action suggestions:

Pattern type	Suggested action
Architectural issues (P3 items)	"Consider running /geniro:refactor on [module]"
Recurring anti-patterns auto-enforceable in this project	"Add a project lint rule or CI check for [pattern]" — per canonical, automated enforcement beats manual memory
Missing utilities causing duplication	"Extract [utility] to shared project module"
Coding convention / style or naming pattern surfaced by simplification	"Add a .claude/rules/<scope>.md file with paths: glob frontmatter for the matching files" — per canonical, code rules go to Anthropic-native file-scoped rules files, not CLAUDE.md
Skill-behavior quality gate the user enforced during review	"Add rule to .geniro/instructions/<skill>.md via /geniro:instructions create" — per canonical, skill-behavior rules go to Geniro instructions files

Ship Guidance

The fixes applied in Phase 4 are now in your working tree. Use the AskUserQuestion tool (do NOT output options as plain text) to route the user to ship:

• Question: "The simplification fixes are applied but not committed. How do you want to ship them?"
• Header: "Ship"
• Options:
  • label: "Commit yourself" — description: "Inspect the diff, commit, and push manually"
  • label: "Ship via /geniro:follow-up" — description: "Recommended. Run /geniro:follow-up ship simplification fixes for a review-gated commit"
  • label: "Leave uncommitted" — description: "Keep the diff in the working tree — I'll handle it later"

If the user picks "Leave uncommitted", do not run any git commands.

---

Compliance — Do Not Skip Phases

Your reasoning	Why it's wrong
"I can analyze the code myself without spawning agents"	You are an orchestrator. Spawn all 3 agents. Parallel review catches more than a single pass.
"One agent is enough for these few files"	Spawn all 3. Each has a different lens — even small files have reuse, quality, AND efficiency dimensions.
"I'll spawn agents one at a time to save tokens"	Spawn all 3 in ONE response — multiple Agent() calls in the same assistant turn. Separate turns = no concurrency, full wall-clock latency per agent.
"These findings are obviously relevant to this repo"	Reviewers apply generic best practices. Without checking against THIS repo's patterns, you'll apply fixes that contradict repo conventions or add unnecessary complexity.
"These changes are obviously safe"	Run validation. "Obviously safe" is the #1 predictor of broken builds.
"I'll fix the P3 items too since I'm here"	P3 is report-only. Fixing P3 risks behavior changes.
"I'll apply these fixes myself since I can see exactly what to change"	You are an orchestrator. ALL fixes go through agents. Even obvious P1 fixes.

---

Definition of Done

• 3 review agents spawned in parallel
• Findings aggregated and deduplicated
• Relevance filter applied (findings checked against repo conventions)
• All P1 and safe P2 fixes applied
• Full validation passes
• No behavior changes (verified by test suite)
• P3 notes documented for user
• Completion report presented

Examples

/geniro:deep-simplify changed
/geniro:deep-simplify src/auth/login.ts src/auth/session.ts
/geniro:deep-simplify focus on reducing duplication in utils/