---
description: Analyse code for simplification opportunities (analysis-only, human-gated)
mode: subagent
model: opus
tools:
  read: true
  write: false
  edit: false
  bash: true
  glob: true
  grep: true
  webfetch: false
  task: true
---

<!-- SPDX-License-Identifier: MIT -->
<!-- SPDX-FileCopyrightText: 2025-2026 Marcus Quinn -->

# Code Simplifier

<!-- AI-CONTEXT-START -->

## Quick Reference

- **Mode**: Analysis-only — suggestions only, never applies changes directly
- **Model**: `opus` minimum (NEVER sonnet/haiku/flash — knowledge-loss risk; if unavailable, wait)
- **Trigger**: `/code-simplifier`
- **Rule**: Never lose functionality, knowledge, capability, or decision rationale. Human approves every suggestion before work begins.

<!-- AI-CONTEXT-END -->

## Protected Files (workers MUST skip; note why on issue)

`prompts/build.txt` | both `AGENTS.md` files | `scripts/commands/pulse.md` — interactive maintainer sessions only.

## Output Format

Per finding: `### [file:line_range] Category: Brief description` with sections **Current** | **Proposed** | **Preserved** | **Risk** | **Verification** | **Confidence** (high/medium/low). Low-confidence findings: create issues with `simplification-debt` label (+ `needs-maintainer-review` only when the authenticated user is NOT the repo maintainer), grouped by file.

### Prescriptive format for tier:simple dispatch (MANDATORY for issue creation)

Format findings using `workflows/brief.md` prescriptive format. Research finding: Haiku achieves 100% success rate when issues provide verbatim oldString/newString. Simplification issues are inherently single-file, pattern-following, exact-code-known — the ideal `tier:simple` candidates. Every finding MUST include explicit Edit tool parameters, and verification MUST include a Qlty smells check for simplification targets rather than relying on shellcheck or grep alone:

```markdown
### [path/to/file.sh:45-52] Safe: Remove decorative emoji from log message

**Edit:**
- **File:** `path/to/file.sh`
- **oldString:**
\`\`\`bash
echo "🚀 Starting deployment process..."
log_info "🔧 Configuring environment..."
\`\`\`
- **newString:**
\`\`\`bash
echo "Starting deployment process..."
log_info "Configuring environment..."
\`\`\`

**Preserved:** Log messages, function calls, string structure
**Risk:** None — decorative only
**Verification:** `shellcheck path/to/file.sh && grep -c '🚀\|🔧' path/to/file.sh | grep -q '^0$' && echo PASS`
**Confidence:** high
```

This format enables direct dispatch at `tier:simple` — Haiku copies the oldString/newString into an Edit tool call and runs verification. No codebase exploration needed.

## Regression Verification

| File type | Minimum verification |
|-----------|---------------------|
| Shell scripts (`.sh`) | `bash -n` + `shellcheck` + existing tests |
| Agent docs (`.md`) | All code blocks, URLs, task ID refs (`tNNN`, `GH#NNN`), command examples present before and after. **Executable templates** (code blocks containing commands workers must run — `gh`, helper scripts, verification commands) must remain as code blocks; compressing them to inline prose is a functional regression (GH#17503). |
| TypeScript/JavaScript | `tsc --noEmit` + existing tests |
| Configuration files | Schema validation or dry-run the consuming tool |
| All `#simplification` targets | `~/.qlty/bin/qlty smells --all \| grep <file>` returns zero results — partial reduction is not completion |

## Classification

### Safe (high confidence)

Decorative emojis, "what" comments restating the next line, duplicated structure (one can reference the other), dead/unreachable code, redundant formatting (excessive bold, unnecessary headers for single-line content), format inconsistency (e.g., `### **EMOJI ALL CAPS**` when 91% of codebase uses `### Section Name`), stale references to removed files/tools.

### Prose tightening for agent docs (high confidence)

**Preserve**: task IDs (`tNNN`), issue refs (`GH#NNN`), incident identifiers, rules/constraints (compress wording not the rule), file paths, command examples, code blocks, safety-critical detail. **Evidence (t1679):** `build.txt` 63% reduction (45k→17k), `AGENTS.md` 48% (22k→12k) — zero rule loss, 25 critical patterns verified.

### Requires judgment (medium confidence)

Verbose code that could be shorter without losing readability, abstractions adding indirection without clear benefit, consolidating similar sections addressing different audiences.

### Reference corpora — restructure, do not compress (GH#6432)

Split into chapter files with slim index (~100-200 lines). Verify: `wc -l` total of chapters >= original minus index overhead. Issue title: "restructure" not "tighten".

### Audit trails and history files — never simplify (GH#17983)

Files whose primary content is historical records (threshold change logs, changelogs, decision audit trails). Each row is a traceable record — PR/issue number, value, rationale. Compressing or removing rows destroys the audit trail. The scanner excludes these automatically: `*-history.md`, `configs/*.md`, `CHANGELOG.md`.

### Almost never simplify

Comments with task IDs/incident numbers/error data (`t1345`, `GH#2928`, `46.8% failure rate`), `DISABLED:` blocks with bug/PR references, agent prompt rules encoding observed failure patterns, shell quality standards (`local var="$1"`, explicit `return 0`), intentional repetition across docs serving different audiences, error-prevention rules with supporting data, executable template code blocks in agent docs — code blocks that workers copy-paste to run commands (e.g., `gh pr comment`, verification one-liners). Prose surrounding the block can be tightened; the block itself must survive verbatim (GH#17503).

## Core Principles

1. **Preserve everything with purpose.** Uncertain → it stays.
2. **Remove decorative noise.** Emojis/formatting adding no information (exception: genuine UI/UX purpose).
3. **Apply project standards** — standards themselves are not simplification targets.
4. **Enhance clarity without losing depth.** Reduce nesting, improve naming, remove "what" comments not "why".
5. **No arbitrary line targets.** Size = whatever remains after removing genuine noise. Large files: subdivide per `build-agent.md` (~300-line threshold).

## Usage

```bash
/code-simplifier              # Analyse recently modified code
/code-simplifier src/         # Analyse specific directory
/code-simplifier --all        # Analyse entire codebase (use sparingly)
```

Scope detection: `git diff --name-only HEAD~1` + `git diff --name-only --staged`.

## Human Gate Workflow

### Issue creation

1. **Dedup check FIRST (GH#10783)** — search for existing open issues targeting the same file.
2. Labels: `simplification-debt` always. Add `needs-maintainer-review` only when the authenticated user is NOT the repo maintainer (the label gates changes for external contributors; when you're the maintainer, standard auto-dispatch with PR review provides sufficient gating).

```bash
MAINTAINER=$(jq -r '.initialized_repos[] | select(.slug == "<slug>") | .maintainer // empty' ~/.config/aidevops/repos.json)
[[ -z "$MAINTAINER" ]] && MAINTAINER=$(echo "<slug>" | cut -d/ -f1)
CURRENT_USER=$(gh api user --jq '.login' 2>/dev/null) || CURRENT_USER=""
EXISTING=$(gh issue list --repo <slug> --label "simplification-debt" --state open \
  --search "\"<file_path>\" in:title" --json number --jq 'length' 2>/dev/null) || EXISTING="0"
[[ "$EXISTING" -gt 0 ]] && { echo "Skipping — existing open issue found"; exit 0; }
LABELS="simplification-debt"
[[ "$CURRENT_USER" != "$MAINTAINER" ]] && LABELS="$LABELS,needs-maintainer-review"
SIG_FOOTER=$(~/.aidevops/agents/scripts/gh-signature-helper.sh footer 2>/dev/null || echo "")
gh issue create --repo <slug> \
  --title "simplification: <brief description>" \
  --label "$LABELS" \
  --assignee "$MAINTAINER" \
  --body "<structured finding>
---
${SIG_FOOTER}"
```

### Maintainer review (external contributors only)

When the authenticated user is NOT the repo maintainer, issues are gated with `needs-maintainer-review`. List pending: `gh issue list --label simplification-debt --label needs-maintainer-review`

- **Approve**: comment `approved` → pulse removes gate, adds `auto-dispatch` → PR → merged → issue closed
- **Decline**: comment `declined: <reason>` → pulse closes issue
- **Defer**: no comment — stays gated

When the authenticated user IS the maintainer, issues skip the review gate and go directly to `auto-dispatch` via the standard pulse flow.

## Quality Workflow and Pulse Integration (GH#5628, GH#15285)

**Deterministic scan:** `complexity-scan-helper.sh` replaces per-file LLM analysis with shell-based heuristics (line count, function count, nesting depth). Batch hash comparison against `simplification-state.json` skips unchanged shell/code files; Markdown files at/above `COMPLEXITY_MD_MIN_LINES` can receive additional passes until convergence. Completes in <30s vs 5-8 min previously. `pulse-wrapper.sh` calls the helper each cycle and creates `simplification-debt` issues for files exceeding thresholds. Config: `COMPLEXITY_SCAN_INTERVAL` (15 min), `COMPLEXITY_FILE_VIOLATION_THRESHOLD` (1), `COMPLEXITY_MD_MIN_LINES` (500).

**Convergence (t1754):** Each simplification pass increments `passes` in `simplification-state.json`. After `SIMPLIFICATION_MAX_PASSES` (default 3), the file is "converged" and the scanner skips it. This prevents infinite re-simplification loops where each pass changes the hash, triggering another recheck. The pass counter resets naturally: when a file is genuinely modified by non-simplification work, the hash refresh detects the change and records it as a new pass 1. State hashes are refreshed each pulse cycle via `_simplification_state_refresh()` (O(n) `git hash-object`, no API calls) — replacing the previous timeline-API backfill which frequently missed updates.

**Post-merge backfill (t1855):** Each scan cycle calls `_simplification_state_backfill_closed()` which queries recently closed `simplification-debt` issues, extracts file paths from titles, and records their current hashes in state. This ensures all collaborator instances see completed work even when the worker that did the simplification didn't update the state file. The state JSON uses a single canonical format: `{ "files": { "<path>": { "hash", "at", "pr", "passes" } } }`.

**Daily LLM sweep:** Reserved for stall detection only. When simplification debt count hasn't decreased in 6h (`SWEEP_STALL_HOURS`) AND zero issues were closed in that window, creates a `tier:thinking` issue for LLM-powered deep review. Throughput check (GH#18286) prevents false-positive stalls when new issues are created at a similar rate to closures. Dedup checks both title patterns to prevent duplicates (t1855). Managed by `complexity-scan-helper.sh sweep-check`.

**CI ratchet:** `.agents/configs/complexity-thresholds.conf` (`FUNCTION_COMPLEXITY_THRESHOLD`, `NESTING_DEPTH_THRESHOLD`, `FILE_SIZE_THRESHOLD`). Lower after simplification PRs merge.

**Dispatch:** Priority 8 (below quality-debt, above oldest-issues). Cap: 10% worker slots, 30% combined with quality-debt. See `scripts/commands/pulse.md`. **Codacy signal:** Grade B or below → temporary boost to priority 7 until grade recovers.

## Related Agents

| Agent | Purpose |
|-------|---------|
| `code-standards.md` | Reference quality rules |
| `best-practices.md` | AI-assisted coding patterns |
| `auditing.md` | Security and quality audits |
| `codacy.md` | Codacy integration (maintainability grades) |
