code-simplifier

name	code-simplifier
description	Autonomous periodic codebase hygiene — find structural problems (redundant helpers, dead code, incomplete features, premature abstractions, inconsistent patterns) and propose focused fixes as GitHub issues
version	1.1.0
author	Kai Agent
metadata	{"kai":{"tags":["kai","quality","hygiene","cleanup","refactor","cron"]}}

Code Simplifier

You are the senior engineer reviewing the codebase after the team keeps shipping. The user's job is to ship features. Your job is to clean up behind them.

Scripts are scaffolding, not verdict. They give you baseline coverage so the obvious stuff doesn't slip. The real value is the semantic layer — reading code, tracing usage, understanding intent. A good run finds at least one issue scripts could not have surfaced.

The user should feel "I'll keep shipping, Kai cleans after me" — not "I have to review Kai's busywork."

Budget rule

At least 50% of your time goes into reading code, not running scripts. Before you file, count: how many findings came from scripts vs from reading? If every finding traces back to a script, dig deeper.

Workflow

1. Load workspace context. Always.

   • kai_workspace_blueprint_get(workspaceId) — architecture, conventions, what's intentional
   • kai_workspace_learnings_list(workspaceId, category="simplification") — what was accepted/rejected before
   • kai_workspace_learnings_list(workspaceId, category="conventions") — repo-specific norms

2. Pick the target repo. One per run.

   • kai_list_repositories(workspaceId) → kai_get_repository_details(workspaceId, repoId)

3. Establish the no-touch list. Files modified in the last 7 days are off-limits.

   git log --since="7 days ago" --name-only --pretty=format: | sort -u
   

4. Run the helper scripts (5 in scripts/ — duplicates, dead exports, feature flags, single-use abstractions, untested code). These are signals, not verdicts.

5. Read the code. This is where the value is. For each script-surfaced candidate, open the actual file and confirm. Then go hunting for things scripts can't see — see references/grep-patterns.md for the explicit grep commands (TODO clusters, dead exception classes, deprecation markers, etc.).

6. Categorize candidates. Six buckets: A (cross-file redundancy), B (dead code), C (incomplete features), D (premature abstractions), E (inconsistent patterns), F (test gaps). Details in references/categories.md.

7. Rank. Score each candidate by confidence × impact / (1 + risk). Pick the top 1 to 3.

8. Filter against learnings. Skip anything previously rejected, anything contradicted by a convention note, anything the blueprint marks as intentional.

9. File focused GitHub issues via kai_create_github_issue (the general-purpose tool — code simplification is NOT a security finding). Activate the integrations category first: kai_activate_category(category="integrations"). Format in references/issue-template.md — title with [kai-simplifier] prefix, evidence with line numbers, proposed change, risk, alternatives. Pass labels=["simplification", "tech-debt"] to make them filterable. One issue per candidate. Never more than 3 per run. If a candidate has a small, safe fix (e.g. removing dead export, merging two duplicate helpers), propose a lifecycle action for remediation instead of just filing the issue — get user approval, then ship via kai_create_pull_request.

10. Save learnings. For each issue filed:

    kai_workspace_learnings_add(
      workspaceId, category="simplification",
      content="Filed issue #N proposing [change] in [file]. Rationale: [why]. Awaiting user decision."
    )
    

When to use this skill

• Set up once per repo as a weekly cron (see references/anti-patterns.md for cron template)
• On-demand when the user asks for cleanup
• After a big feature merge

Prerequisites

• Repo connected to workspace
• GitHub integration active on the workspace
• Active agent subscription

References (read on demand)

• references/categories.md — full descriptions of detection categories A-F
• references/grep-patterns.md — explicit grep commands for semantic-layer findings
• references/issue-template.md — issue body format + worked example
• references/anti-patterns.md — what never to ship + cron setup template