/self-improve

name: self-improve
description: Self-improve this skills repo — surface and (safely) apply quality improvements across four parallel read-only lenses (Clarity, Leanness, Coverage, Ergonomics). Sibling of /self-audit — audit fixes rule violations, improve raises quality where no rule is broken. Local meta-skill, independent of the /task:* pipeline.
disable-model-invocation: true
user-invocable: true

Improve **this repository** (the task-pipeline skills repo itself) — not by fixing rule violations (that is [`/self-audit`](../self-audit/SKILL.md)), but by raising quality where nothing is broken yet. Four lenses run in parallel as named read-only subagents: **Clarity**, **Leanness**, **Coverage**, **Ergonomics**.

improve vs audit — the split that defines this skill

`/self-audit` asks *"does the repo obey its own declared rules?"* — it has an oracle (CLAUDE.md invariants, the artifact contract in `docs/contract.md`, the real `skills/` tree), the fix direction is determined, and every gated finding is applied.

`/self-improve` asks *"nothing is violated — but where is the repo weaker than it could be?"* — there is **no oracle**. An "improvement" is a judgement call, and its direction is a design decision, not a mechanical correction. That is the literal difference between fixes (audit) and improvements (improve), and it drives the whole apply model:

• **Audit applies everything that passes its gate** — the source of truth says which way to go.
• **Improve applies only a narrow, mechanical, behavior-preserving subset automatically**, at a higher confidence bar, and **proposes** everything that changes the design for the user to greenlight. Improvements that reshape a flow, merge sections, or add a guardrail are decisions a human must nod at.

**Boundary rule (hard):** if a lens finds an actual violation of a declared rule (an invariant, a producer↔consumer mismatch, README↔code drift), that is audit's job, not improve's. The agent must set `defer: self-audit` on it and **not** propose a fix. `/self-improve` never edits under the banner of a rule violation — it only makes not-yet-broken things better.

This is a **meta-skill**. It operates on the repo's own files (`skills/*/SKILL.md`, `skills/_lib/*.sh`, `skills/validate/validate.sh`, `CLAUDE.md`, `README.md`, `docs/contract.md`), not on `.task/*` artifacts. The pipeline it improves is the chat-first capture protocol (six user skills — `grill`, `to-task`, `to-plan`, `to-roadmap`, `to-spec`, `roadmap-to-workflow` — plus the bash-only `validate`); the repo-level `agents/` directory holds exactly one file, `agents/code-reviewer.md`. It can be invoked at any time.

**Input:**

• Optional scope hint: $ARGUMENTS (e.g. a single skill name to focus on; default: full repo).
• Optional flag `--propose-only` (alias `--dry-run`) in $ARGUMENTS: apply nothing; report both tiers only. (This is a flag of the meta-skill itself, not of the audited pipeline — the pipeline is flag-free.)

**Precondition (hard-stop):** This skill is local to the task-pipeline repo. Verify the working directory contains `skills/to-task/`, `skills/validate/`, and `CLAUDE.md` at the repo root. If not, stop with: "This skill is local and only works inside the task-pipeline repository."

**Communication language:** Russian (per global user instructions). Findings text stays in English (it grounds in English source files and matches the existing auditor convention).

**Why a separate set of agents from self-audit?** Audit's three lenses are conformance checks (Invariants, Contract, Docs-sync) — reality-vs-declared-rule. Improve's four lenses are quality checks with no oracle. Different question, different failure modes, different apply posture — hence a separate agent set.

Architecture

Four directions of "better" — sharper / leaner / more complete / kinder-to-the-operator. Vectors are mutually exclusive (modify in place / subtract / add internal robustness / improve human touchpoints), so cross-lens overlap is minimal.

| Lens | Local agent | Vector | Facing | What it looks for | |------|-------------|--------|--------|-------------------| | **Clarity** | `self-clarity-improver` | modify in place | the agent reading the prompt | Ambiguous steps, weak output templates, internal contradictions in one file — places an LLM will plausibly do the wrong thing. | | **Leanness** | `self-leanness-improver` | subtract / link | — | Prose duplication with no single owner (→ collapse to a pointer) and over-engineering (a helper wrapping one line, a dead branch, ceremony that adds no seam). | | **Coverage** | `self-coverage-improver` | add robustness | the agent reading the prompt | Missing guardrails, absent worked-examples where an agent guesses, unhandled edge-cases in the flow, a missing test/doc. | | **Ergonomics** | `self-ergonomics-improver` | modify / add | the human operator | Error / hard-stop wording, next-step / handoff footers, discoverability, quality of final feedback. |

Boundaries against `/self-audit` (each agent enforces its own; `defer: self-audit` when crossed):

• **Leanness ≠ Contract auditor**: Contract flags copies that *disagree today*; Leanness flags copies that *exist and should be collapsed* even while they still agree — removing future-drift risk.
• **Leanness ≠ Docs-sync auditor**: Docs-sync flags docs that *omit/misname* a real skill; Leanness flags docs that *duplicate* something that should have one owner.
• **Coverage ≠ Invariants auditor**: Invariants flags a *declared* invariant that is *violated*; Coverage flags where *no rule exists yet* but one would help ("here is an invariant worth stating").

All four are **read-only** named agents at `.claude/agents/self-{clarity,leanness,coverage,ergonomics}-improver.md`, with `tools: Read, Grep, Glob, Bash` — no `Edit`/`Write` in the allowlist (that part is runtime-enforced); `Bash` is present only for read navigation (`git`/`ls`/`grep`), and the agent prompts forbid using it to write. Edits happen only in