---
name: intuitive-reduce-entropy
description: |
  Periodically inspect a repository and recommend the highest-value entropy
  reduction slice across agent guidance, human docs, tests, repo layout,
  architecture depth, stale APIs, and cleanup gates. Use when the user says the
  repo feels messy, asks what to clean next, wants to make an old repo easier
  for humans and AI agents to work in, or wants maintenance suggestions without
  already knowing the target seam. This is the small public entrypoint for repo
  maintenance; it routes to specialist skills instead of making the user choose
  them upfront.
---

# Intuitive Reduce Entropy

Use this skill as the maintenance entrypoint when the user does not already know
which repo surface most needs cleanup. It diagnoses likely entropy sources,
recommends one bounded slice, and routes to the specialist skill that owns that
slice.

The default goal is a repo where future agents can start quickly, humans can
review current truth from a small doc surface, tests show real behavior, and
the next meaningful task does not require rediscovering stale paths, bloated
agent files, mixed doc tiers, or unclear cleanup targets.

## Zen Of Python Bias

Rank cleanup candidates with an explicit Zen of Python-style bias. Prefer
maintenance slices that make the repo more obvious, readable, flat, explicit,
and unsurprising for the next human or agent.

- Prefer explicit current truth over implicit tribal knowledge.
- Prefer one obvious canonical path, command, API, or doc home over parallel
  near-equivalents.
- Prefer simple, direct structure over clever indirection, deep nesting, or
  special-case wrappers.
- Make exceptional compatibility, migration, or verification constraints
  explicit instead of hiding them behind silent fallbacks.
- Let practicality beat purity, but choose the practical slice that most reduces
  future rediscovery and surprise.
- If the best slice is not obvious after inspection, say so and show the
  tradeoff instead of forcing artificial certainty.

When presenting candidates, include a brief `Zen hint:` for the recommended
slice that states which clarity principle the slice advances.

## Human/Agent Surface Rule

The default human-facing source of truth is intentionally small:

- `README.md`
- `ARCHITECTURE.md`
- `STATUS.md`
- `docs/human/**`

`AGENTS.md` and `CLAUDE.md` are agent-operational docs. Use them for startup
rules, local hazards, command pointers, and skill routing, but do not treat them
as human-authoritative project truth by default.

Agent planning, generated evidence, history, and working notes belong in
explicit agent/process surfaces such as `.planning/**`, `docs/plans/**`,
`docs/retrospectives/**`, `docs/status/active/**`, and `output/**` unless a
human doc intentionally promotes a specific artifact into current truth.

AI coding docs are agent/process-facing docs that help future coding agents but
do not need to be human project truth. Prefer `docs/agents/**` for durable
agent runbooks, repo-specific coding procedures, tool quirks, and long harness
notes. Prefer `.planning/**`, `docs/plans/**`, `docs/retrospectives/**`,
`docs/status/active/**`, and `output/**` for execution state, plans,
retrospectives, generated evidence, and proof artifacts.

## Bounded Proposal Rule

For broad or ambiguous cleanup, audit first and stop after a decision-complete
proposal. Do not move files, delete tests, rewrite guidance, or edit production
code until the target slice, accepted checklist, evidence level, and stop
condition are explicit.

For a precise target where the user asks for implementation, apply one coherent
vertical slice. Keep newly discovered unrelated ideas parked instead of letting
the work expand by drift.

## Delegation Model

Keep the main session as the coordinator, decision point, and canonical
artifact editor. Use delegation to keep route evidence, worker logs, and
implementation detail out of the main context when the work naturally separates.

Default matrix:

| Work type | Default executor |
| --- | --- |
| Read-heavy independent probes | native subagents |
| Verification-heavy log or test-output inspection | native subagents |
| Bounded disjoint edits | native worker subagents |
| Stateful, interactive, or long-running skill pipelines | `skill-runner` / tmux |
| Canonical source-of-truth edits and route decisions | main session |

Use native subagents by default when there are two or more independent
read-heavy, verification-heavy, or safely partitioned edit workstreams. For
mutating native workers, assign disjoint file or path ownership before launch
and require a compact handoff back to the main session.

Use `skill-runner` for downstream skill work that is stateful, interactive,
long-running, or better supervised in a standalone tmux session. Prefer one
mutating `skill-runner` worker at a time in a single worktree unless the write
ownership is explicitly disjoint. Do not assume extra git worktrees; many repos
are too large or dependency-heavy for that to be the default.

Worker handoff shape, whether native subagent or `skill-runner`:

```text
Scope:
Changed files:
Decisions made:
Verification:
Open risks:
Suggested next action:
```

For `skill-runner`, inspect `result.md`, `eval.md`, `last-message.md` when
available, targeted logs, the actual diff, and verification evidence before
trusting the worker's final status.

Model policy: prefer the current best/default model for normal delegated work.
Use smaller or quicker models only for truly easy probes where mistakes are
low-cost and easy to catch. Do not add multi-run orchestration here; leave
fan-out/fan-in runners for a later proven need.

## Canonical Cleanup Rule

Prefer the new intuitive API, path, module boundary, command shape, or folder
layout over backward compatibility. In an approved cleanup/refactor slice, old
surfaces are migration targets, not contracts.

- Update known in-repo callers, docs, tests, recipes, examples, CI, and command
  references to the new shape.
- Delete old wrappers, aliases, command paths, import paths, dead branches, and
  compatibility shims after known consumers are migrated.
- Keep compatibility only when the user explicitly protects it, a published
  external contract must remain live, or verification shows a non-migratable
  outside-repo consumer.
- If compatibility is kept, mark it temporary and record the removal trigger in
  the active plan, scope gate, or output report.

## Public Entry Model

Keep the user-facing choice small:

- `$intuitive-flow` -> build or ship something new.
- `$intuitive-refactor` -> clean a known module, seam, API, or architecture
  target.
- `$intuitive-reduce-entropy` -> find what repo maintenance would pay off most
  now.
- `$intuitive-squash` -> clean local agent commit history before handoff.

Specialist skills still exist, but the user should not need to pick one before
the repo has been diagnosed:

- `$intuitive-doc` owns human-facing docs and doc boundary drift.
- `$intuitive-init` owns `AGENTS.md`, `CLAUDE.md`, `docs/agents/**`, init
  discovery, hooks, skills, and MCP guidance.
- `$intuitive-tests` owns test taxonomy, behavior quality, markers, pruning,
  fixture/factory extraction, and test folder layout.
- `$improve-codebase-architecture` owns report-only architecture/deepening
  discovery when the repo has code architecture friction but no accepted target
  seam yet.
- `$intuitive-refactor` owns known code/module/API cleanup targets and
  persistent refactor gates, including execution of an accepted architecture
  candidate.

## Entropy Sources

Classify the user's prompt and repo evidence into one or more entropy sources:

| Source | Signals | Owner |
| --- | --- | --- |
| Agent guidance | bloated or stale `AGENTS.md` / `CLAUDE.md`, missing harness, unclear commands, copied human project state | `$intuitive-init` |
| Human docs | stale README/architecture/status, missing current truth, generated evidence in human docs | `$intuitive-doc` |
| Tests | low-signal tests, unclear markers, brittle fixtures, flat or confusing test layout, flaky or slow defaults | `$intuitive-tests` |
| Repo surface layout | mixed human/agent/runtime/test/script surfaces, flat scripts/examples, misplaced files, stale path consumers | route by object; see Layout Routing |
| Architecture discovery | open-ended architecture improvement, shallow modules, hard-to-test or hard-to-navigate code, unclear module depth or seams, request to find refactoring opportunities | `$improve-codebase-architecture` in report-only mode, then `$intuitive-refactor` after a candidate is accepted |
| Known code cleanup | named module, accepted seam, stale API, compatibility shim, or target-local architecture cleanup | `$intuitive-refactor` |
| Workflow drift | unclear source of truth between plans, GSD, issues, docs, and commits | `$intuitive-flow` or `$intuitive-refactor`, depending on whether work is planned or cleanup-shaped |

## Layout Routing

Layout is a symptom, not a standalone public skill. Route by the object being
organized:

- Human docs, doc tiers, generated evidence in docs, or doc indexes ->
  `$intuitive-doc`.
- Test folders, markers, fixtures, pruning, or test helper layout ->
  `$intuitive-tests`.
- Code/package/module/API layout, stale imports, wrappers, or compatibility
  surfaces -> `$intuitive-refactor`.
- Unclear module depth, shallow seams, or broad "find architecture cleanup"
  requests -> `$improve-codebase-architecture` first in report-only mode.
- Mixed top-level surfaces, flat scripts/examples, agent-vs-human workspace
  separation, or unclear repo navigation -> keep the slice here and route
  subparts to the relevant specialist.

For any layout-shaped slice, preserve the old safety rules:

- move one bounded slice at a time
- find path consumers before proposing moves: imports, docs, CI, recipes,
  scripts, package metadata, hooks, and user-facing commands
- update known consumers to the new canonical path
- delete stale wrappers, aliases, old command paths, and old imports unless the
  user explicitly protects an external contract
- verify with stale-path searches and the narrow commands that exercise the new
  paths

## Default Route

Use this route unless the user already names a specific entropy source.

1. **Orient**: launch parallel native probes for root guidance, human docs,
   package/test config, automation, top-level layout, and the current
   verification command when two or more surfaces need inspection. For tiny
   repos or precise prompts, inspect the relevant surface directly.
2. **Classify**: map observed friction to the entropy sources above.
3. **Recommend**: present 2-4 candidate slices when the best path is not
   obvious. Include one recommended slice first and attach a `Zen hint:` that
   explains how it makes the repo more explicit, simple, canonical, or
   unsurprising.
4. **Discover architecture**: when the best slice is architecture/deepening but
   no target seam has been accepted, route to `$improve-codebase-architecture`
   in report-only mode. Treat its output as candidate evidence, not execution
   approval, and stop for candidate selection unless the user already accepted a
   candidate.
5. **Gate**: if execution is requested, use `$intuitive-refactor` to create or
   update one persistent maintenance gate, normally
   `docs/plans/refactor-reduce-entropy-<target>.md` unless a better existing
   plan owns the scope.
6. **Route**: run the specialist owner for the accepted slice, or keep the slice
   here only when it spans mixed repo surfaces without a narrower owner.
7. **Verify and close**: run the repo's relevant checks, update the gate status,
   and park remaining cross-seam ideas.

Before routing to a specialist, produce a compact handoff packet so the next
stage does not repeat the whole audit:

```text
Selected slice:
Entropy source:
Zen hint:
Evidence:
Affected paths:
Discovery skill:
Owner skill:
Proof commands:
Parked items:
Stop condition:
```

For long or stateful specialist execution, pass that packet through
`skill-runner`/tmux and have the main session inspect `result.md`, `eval.md`,
worker output, the actual diff, and verification before closeout.

Run another slice only when the gate still has a concrete P0/P1/P2 item inside
scope. Do not repeat just because more possible cleanup exists.

## User Input Routing

If the user names a likely area, route directly:

- "docs", "README", "ARCHITECTURE.md", "architecture docs", "status",
  "human docs" ->
  `$intuitive-doc`.
- "AGENTS", "CLAUDE", "harness", "init", "MCP", "hooks", "skills setup" ->
  `$intuitive-init`.
- "tests", "pytest", "coverage", "fixtures", "flaky", "markers" ->
  `$intuitive-tests`.
- "improve architecture", "architecture cleanup", "deepening", "shallow
  module", "hard to test", "hard to navigate", "find refactoring
  opportunities" -> `$improve-codebase-architecture` when the user wants
  discovery or no target seam is accepted yet.
- "module", "API", "compatibility", "seam", "stale wrapper", "known
  architecture target" ->
  `$intuitive-refactor`.
- "layout", "folders", "scripts", "examples", "repo structure" -> inspect the
  object first, then route through Layout Routing.

If the user gives no area, do not guess silently. Return a short candidate list:

```text
Recommended slice: <one option>
Why: <repo evidence>
Alternatives:
- <option 2>
- <option 3>
Suggested proof: <commands/searches>
Proceed with recommended slice?
```

## Decision Policy

Auto-select a default only when repo evidence makes it low-risk and reversible.
Pause for the user when a decision would materially change:

- runtime behavior or public APIs
- externally documented command/import paths
- broad file moves, deletes, or test pruning
- compatibility shims that may have outside-repo consumers
- paid, slow, Docker, hardware, simulator, or local-provider verification gates
- product intent, audience, or scope

If the user asks for "choose defaults," interpret that as permission to choose
mechanical defaults, not permission to cross these pause points silently.

## Stop Condition

Stop when all of these are true:

- the accepted maintenance gate is `DONE` or `PARK`, with remaining ideas
  recorded
- exactly one primary entropy slice was completed or explicitly parked
- specialist skills were used for their owned surfaces instead of duplicating
  their full procedures here
- verification commands pass, or skipped gates are documented with a concrete
  reason
- the agent can state the next safe task without starting another broad cleanup
  sweep

## Report Format

End with:

```text
Entropy source:
Selected slice:
Specialist owner:
Gate:
Changes:
Verification:
Parked items:
Next safe task:
```
