zf-find-simplifications

Files (1)

• SKILL.md

SKILL.md (first lines)

# ZaoFu Find Simplifications

Use this skill to reduce real maintenance surface, not to reward a smaller diff
or a lower line count. A valid candidate has call-site evidence, states what
behavior is surrendered, respects the repository's protected seams, and deletes
or coalesces more complexity than it relocates.

## Operating Modes

Choose exactly one mode before working:

- **Audit mode:** use for broad repository surveys, architecture reduction,
  release/refactor checkpoints, and every Autoresearch `simplify` request. It
  is read-only and produces a proposal; it never authorizes implementation,
  runtime-state mutation, task completion, or direct mainline application.
- **Recent-diff refinement mode:** use only when the current assignment already
  authorizes code edits. Limit edits to the current session's owned diff, keep
  observable behavior exact, and rerun the same focused verification. This is
  the daily ZaoFu/application-development counterpart to a code-simplifier
  pass, not permission to refactor untouched modules.

If scope or edit authorization is ambiguous, use audit mode.

## When To Use

Use it on demand in any of these contexts:

- **ZaoFu daily iteration:** repeated fallback branches, compatibility layers,
  duplicate facts, oversized ownership surfaces, or code repeatedly repaired in
  the same area. After an implementation, recent-diff refinement may improve
  clarity without changing behavior.
- **Applications developed with ZaoFu:** hand-written infrastructure, abandoned
  options, duplicated domain representations, or test-only public APIs in the
  target application. The application's owner contract and product behavior
  take precedence over generic ZaoFu preferences.
- **Autoresearch:** an explicit `autoresearch.loop.requested(mode=simplify)` or
  a separately approved simplification checkpoint. The output remains a
  `simplification_audit.v1` proposal; Autoresearch must not apply it directly.
- **Release/refactor checkpoint:** after the behavior is proven and before more
  variants are added, when consolidation can be evaluated against a stable
  target.

Do not auto-load this skill for every Impl, Verify, reflection, or ordinary code
review. Do not use it to turn an unrelated delivery task into a refactor.

## Recent-Diff Refinement

This narrow mode adopts the useful behavior-preserving discipline of Anthropic's
`code-simplifier` agent while keeping ZaoFu's evidence and ownership rules:

1. Pin the owned scope with `git diff -- <explicit paths>` and the current task
   contract. Do not edit another driver's staged, dirty, or untracked files.
2. Read the repository's current `AGENTS.md` / `CLAUDE.md` and existing nearby
   patterns. Project rules replace hard-coded language/framework preferences.
3. Preserve public APIs, outputs, errors, side effects, ordering, persistence,
   events, config defaults, security boundaries, timing/concurrency semantics,
   and accepted compatibility behavior.
4. Reduce unnecessary nesting, duplicate branches, redundant abstractions,
   vague names, and comments that only narrate syntax. Consolidate only logic
   with one owner and one invariant.
5. Prefer readable, explicit control flow over dense expressions, clever
   one-liners, nested ternaries, or line-count reduction. Fewer lines are not a
   success metric.
6. Apply the smallest refinement, inspect the resulting diff, and rerun the
   pre-refinement focused tests plus any direct caller/contract checks crossed.
7. If a candidate changes supported behavior, requires migration, crosses the
   task's allowed paths, or cannot be proved equivalent, do not apply it. Move
   it to an audit proposal or reject it.

No edit is a valid outcome when the current diff is already the clearest safe
implementation.

## Scope First

State the repository, target commit, bounded directories or subsystem, and the
reason simplification is being considered. Read the applicable `AGENTS.md`,
current owner/design documents, dependency manifest, and recent incident or
change evidence before searching for candidates.

For ZaoFu itself, load `zf-cr` and
`zf-harness-design-impl-game-review` when the audit needs architecture-wide
adjudication, verify claims against current code/tests, and preserve these
boundaries unless the owner explicitly approves an architecture change:

- `zf.yaml` remains the single control-plane configuration.
- EventLog ordering/causation, canonical Stores, artifact bodies/refs/digests,
  and SQLite projections have different owners; do not collapse truth into a
  read model or duplicate semantic bodies into events.
- The deterministic Kernel and a configured `orchestrator` role agent are not
  interchangeable.
- Product Flow and supported Legacy routes may intentionally differ.
- Provider, transport, worktree, session, and security seams may have dynamic
  consumers that a static symbol search cannot see.
- `skills/` is canonical; tracked provider copies are synchronized mirrors, not
  independent implementations.

For an application, derive the protected seams from its PRD, public API,
persisted data, deployment/runtime contract, and real E2E behavior. Never infer
that a product feature is disposable merely because ZaoFu does not use it.

## Survey Method

1. Start with the largest recent production deltas and repeatedly changed
   modules. Use `git log`, `git diff --stat`, line counts, incident reports, and
   rework evidence to prioritize the survey.
2. Search exact symbols, event names, config keys, routes, wire strings, artifact
   kinds, CLI commands, and reflective registry names with `rg`.
3. Read every plausible caller. Classify consumers as:
   - `production_static`: direct runtime callers;
   - `production_dynamic`: registries, config, events, plugins, serialization,
     templates, provider or transport loading;
   - `operations`: migration, recovery, CLI, runbook, compatibility;
   - `non_production`: tests, fixtures, docs, examples, snapshots;
   - `unresolved`: evidence is insufficient.
4. Draw the fact/ownership or lifecycle graph when two mechanisms appear to
   represent the same state. Similar names are not proof of duplication.
5. Check existing design decisions and prior incidents. A defensive branch that
   looks redundant may encode a recovered production failure.
6. Estimate **net surface delta**: removed implementation, tests, config, docs,

From uisee-ai/zaofu, Apache-2.0.

More from uisee-ai/zaofu