feat: reduction ladder + cleanup-audit skill (clean-design-by-default)

[elkaix]

What

Make the agent produce minimal-yet-robust code by default. Honest framing: the agent soul already
encodes most of this — §6 "Simplicity first" (minimalism), §6 "Production guardrails" (failure-first
defensive patterns), §2 + Security hygiene (fail-closed). This PR adds only the genuine delta.

Two commits:

• feat(prompt): an explicit ordered reduction ladder (YAGNI → stdlib → native/framework →
  installed dep → one line → minimum code) in agents/default/system.md §6 and the /best-practices
  profile, plus deliberate-shortcut ceiling-comment guidance folded into §6's existing allowed-comments
  clause. Two prompt pins guard it against silent drift.
• feat(skills): a new read-only cleanup-audit skill — a one-shot, whole-repo over-engineering
  audit (ranked delete/simplify/replace-with-stdlib list). It is the repo-wide complement to the
  existing diff-scoped pythinker review diff --mode deslopify, and forbids cutting validation,
  data-loss handling, security, or accessibility.

Out of scope (deliberately not built)

• No always-on injection machinery — the soul is already always-on, so a hook/MCP/adapter layer would
  be redundant here.
• No intensity-level knob (new user-facing machinery, not the delta).
• No duplicate of deslopify (diff-scoped over-engineering review already ships).

Verification

• make check-pythinker-code → All checks passed (ruff + format + pyright + ty)
• make test-pythinker-code → 65 passed, 4 skipped (real-LLM only)
• Focused: test_default_agent, test_pyinstaller_utils, test_wire_protocol → 17 passed
• ## Unreleased changelog entries added for both changes.

Notes

• The prompt graft is an adherence intervention; its behavioral effect on generated code is
  unverified here. The honest proof would be a diff-LOC A/B on a feature task (agent with vs. without
  the ladder) — out of scope for this PR.
• Out-of-scope observation: the tree already contains some pre-existing deferral-comment markers and
  plugin-test fixtures named after an external tool; they could be de-branded in a separate surgical
  pass. Left untouched here to keep this PR scoped.

Summary by CodeRabbit

• New Features

  • Added the cleanup-audit skill to perform a whole-repository, read-only scan to flag accidental complexity and over-engineering for safe cleanup opportunities.

• Documentation

  • Expanded code guidance with a “reduction ladder” for simplifying work step-by-step—favoring standard library/platform options before writing minimal custom code.
  • Updated default-agent and best-practices prompts to strengthen guardrails around safety, security, and accessibility.

• Tests

  • Updated unit and end-to-end expectations to include the new cleanup-audit skill and verify prompt invariants.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 8ff07885-7cd3-42f5-9c77-c7fbae22cd35

📥 Commits

Reviewing files that changed from the base of the PR and between 665d015 and 2841bf1.

📒 Files selected for processing (1)

• src/pythinker_code/prompts/best_practices.md

---

📝 Walkthrough

Walkthrough

Adds a new cleanup-audit skill with whole-repo read-only over-engineering audit capabilities, inserts a "reduction ladder" rule set into the default agent system prompt and best_practices.md, and updates CHANGELOG. Tests extend prompt assertions, PyInstaller bundling coverage, and wire-protocol slash command registration.

Changes

cleanup-audit skill and reduction ladder guidance

Layer / File(s)	Summary
Skill definition and prompt content src/pythinker_code/skills/cleanup-audit/SKILL.md, src/pythinker_code/agents/default/system.md, src/pythinker_code/prompts/best_practices.md, CHANGELOG.md	Defines the cleanup-audit SKILL.md with scope, hunt targets, ranked output format, and guardrails against removing safety/security code. Adds the reduction ladder rule set to the default agent system prompt and a matching "Before writing code" bullet to best_practices.md. Both entries recorded in CHANGELOG.
Tests and bundling assertions tests/core/test_default_agent.py, tests/utils/test_pyinstaller_utils.py, tests_e2e/test_wire_protocol.py	Asserts "The reduction ladder" and "stop at the first rung that holds" are present in the default agent prompt. Adds the cleanup-audit SKILL.md to the expected PyInstaller datas. Updates both e2e initialization snapshots to include the skill:cleanup-audit slash command entry.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related PRs

• Pythoughts-labs/pythinker-code#43: Both PRs modify the default agent system prompt and its tests at the same file surfaces — this PR adds the reduction ladder block while #43 redesigned the prompt around a judge gate.

Suggested labels

enhancement

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 70.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows conventional commits format (feat: description) and accurately summarizes the two main changes: the reduction ladder and the new cleanup-audit skill.
Description check	✅ Passed	The description covers all required sections: related issue context, detailed what/why, out-of-scope clarifications, verification steps, and notes on limitations. The PR checklist items appear satisfied.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/clean-design-by-default

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

src/pythinker_code/agents/default/system.md (1)

146-155: ⚠️ Potential issue | 🟡 Minor

Mirror missing rung 4 guidance into best_practices.md.

system.md line 152 and best_practices.md line 33 describe the reduction ladder inconsistently:

• Rung 4 context gap: system.md explicitly states "never add a new dependency for what a few lines cover"; best_practices.md omits this constraint. This is load-bearing guidance about the zero-new-bundled-deps policy.
• Tiebreaker missing: system.md includes "When two rungs both hold, take the higher one and move on — the ladder is a reflex, not a research project"; best_practices.md has no equivalent, leaving ambiguity about rung priority.
• Example detail: system.md provides concrete examples (e.g., "a built-in form control over a picker library"); best_practices.md is more abstract.

Update best_practices.md to preserve the rung 4 warning and tiebreaker logic so the agent reads consistent policy from both sources.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/pythinker_code/agents/default/system.md` around lines 146 - 155, The
reduction ladder guidance in best_practices.md is missing critical constraints
that are present in system.md. Specifically, best_practices.md omits the rung 4
warning about never adding new dependencies for what a few lines of code can
cover, and lacks the tiebreaker rule stating "when two rungs both hold, take the
higher one and move on — the ladder is a reflex, not a research project." Update
the reduction ladder section in best_practices.md to include both of these
elements from system.md, preserving the exact constraint about the
zero-new-bundled-deps policy and the priority rule for ambiguous cases, so both
documents provide consistent guidance.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Outside diff comments:
In `@src/pythinker_code/agents/default/system.md`:
- Around line 146-155: The reduction ladder guidance in best_practices.md is
missing critical constraints that are present in system.md. Specifically,
best_practices.md omits the rung 4 warning about never adding new dependencies
for what a few lines of code can cover, and lacks the tiebreaker rule stating
"when two rungs both hold, take the higher one and move on — the ladder is a
reflex, not a research project." Update the reduction ladder section in
best_practices.md to include both of these elements from system.md, preserving
the exact constraint about the zero-new-bundled-deps policy and the priority
rule for ambiguous cases, so both documents provide consistent guidance.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: f0c943c6-961a-40e2-a438-ceef8f4678e0

📥 Commits

Reviewing files that changed from the base of the PR and between 529bdff and 665d015.

📒 Files selected for processing (7)

• CHANGELOG.md
• src/pythinker_code/agents/default/system.md
• src/pythinker_code/prompts/best_practices.md
• src/pythinker_code/skills/cleanup-audit/SKILL.md
• tests/core/test_default_agent.py
• tests/utils/test_pyinstaller_utils.py
• tests_e2e/test_wire_protocol.py

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[elkaix]

CodeRabbit's single finding — mirror the rung-4 dependency warning + tiebreaker from system.md into best_practices.md — is addressed in 2841bf1. best_practices.md line 33 now carries both the "never add a new one for what a few lines cover" rung-4 warning (zero-new-bundled-deps policy) and the "when two rungs both hold, take the higher one and move on" tiebreaker. CodeRabbit re-reviewed 2841bf1 (status: success, no new actionable comments); all 28 checks are green. Merging via squash.