reduce

# Reduce (De-abstraction for Agents)

## Overview
Diagnose abstraction cost versus value and recommend lower-level primitives using a surgical, minimal-incision mindset.

Defaults:
- Optimize for agent-editability (few layers, explicit config, deterministic commands).
- Be aggressive: prefer primitives even if it increases short-term duplication or migration work.
- Preserve observable behavior unless the user explicitly requests a semantic change.
- Analysis/recommendations only; do not implement unless explicitly asked.

## Double Diamond fit
Reduce is a Discover/Define-heavy skill that produces a concrete cut list and migration plan without writing code.
- Discover: inventory the abstraction stack and locate indirection points.
- Define: score each abstraction (agent-tax vs value) and choose keep/cut.
- Develop: select the next-lower replacement rung and the smallest reversible migration.
- Deliver: report an audit table + prioritized cut list + migration plan + minimal-incision patch suggestions.

## Entry Criteria
Use this skill only when at least one condition is true:
- Change latency is dominated by abstraction/tooling hops rather than local readability.
- Behavior is controlled by framework hooks, plugins, codegen, or configuration indirection.
- The target outcome is to remove or downgrade layers while preserving observable behavior.
- The current interface is changing during interaction, but that evolution is hidden in ad-hoc runtime checks instead of explicit protocol/state boundaries.

## Triage Gate
- Prefer `$reduce` for architecture/tooling de-abstraction and dependency cuts.
- Prefer `$complexity-mitigator` for local readability or control-flow simplification inside the current stack.
- If both apply, run `$reduce` first to delete layers, then simplify the residue.
- If interaction-dependent interfaces are core to the domain (session/capability/progressive protocol), reduce incidental wrappers first; do not flatten the protocol itself without proof.

## Core Principles
- Minimal incision, maximal simplification: target the smallest change that deletes the most indirection.
- Agent-friendly primitives win: plain files, explicit config, simple CLIs, no hidden generators, no interactive prompts.
- Prefer deletion over replacement when behavior is unused or redundant (prove unused via repo evidence).
- Prefer one obvious path over flexible multiplexing (plugins, adapters, DI containers) unless value is proven.

## Guardrails
- Default to repo-local evidence; do not guess usage/value.
- Do not recommend big-bang rewrites; require seams, phases, proof signals, and a rollback lever.
- Do not propose breaking external surfaces without a compatibility wrapper or an explicit user ask.
- Do not add tools/dependencies unless explicitly requested.
- If implementation is requested, hand off to `$tk`.
- Do not collapse an essential evolving interface into one global fixed interface unless the same observable protocol can be proven with deterministic tests.

## What "Agent-editability" Means (practical)
An agent can:
- Find where behavior lives (few hops; few conventions; minimal magic).
- Change it with a small diff (no repo-wide cascading edits).
- Run/verify quickly (one deterministic command; minimal environment).

Non-goals (unless explicitly requested):
- Beautification refactors.
- Re-platforming for its own sake.
- Tuning performance/scale beyond what the existing contract requires.

## Workflow

### 1. Discover: Map the abstraction stack
Inventory what makes change hard.

Required scan (repo-local):
- Toolchain: build/test commands, task runners, codegen, formatter/linter, monorepo tooling.
- Runtime: frameworks/meta frameworks, plugin systems, DI, reflection, middleware layers.
- Data: ORMs/query builders/migrations, caches, queues, service mesh.
- Frontend: SPA frameworks, bundlers, state libraries.
- Infra/deploy: k8s, Helm, Terraform layers, bespoke pipelines.

Evidence collection defaults:
- Prefer direct evidence: `package.json` scripts, `Makefile`/`justfile`, CI config, `Dockerfile`, deploy manifests.
- Trace one real request path: input -> validation -> core rule -> persistence -> output.
- Note every indirection point (codegen boundary, framework hook, config indirection, adapter layers).
- If interface evolution is suspected, trace at least 2-3 interaction paths and record how the allowed operation set changes after each response/event.

### 2. Define: Decide whether abstraction cost is too high
Classify each abstraction as: keep | wrap | slice | replace | delete.

Cost signals (agent-tax):
- Hidden steps: codegen, implicit conventions, runtime magic, reflection, decorators.
- Indirection: behavior lives in hooks/middleware/config rather than code you can edit.
- Tool weight: slow installs/builds/tests; large dependency graph; multi-tool orchestration.
- Non-determinism: environment-sensitive behavior, flaky tests, network-required dev loops.
- Churn risk: upgrades break frequently; generated diffs; brittle integrations.

Value signals (justification):
- Hard constraints: compliance, multi-tenant isolation, true scale needs, audited change control.
- Proven reuse: multiple independent consumers, stable shared domain rules.
- Operational leverage: materially reduces oncall risk (with evidence).
- Protocol realism: allowed operations genuinely change with interaction state (for example session phase, capability grants/revocations, adaptive UI state, progressive model stages).

Scoring rubric (make cut decisions mechanical):
- Agent-tax score (T): 0-3
  - 0 = negligible (direct code; obvious entrypoints; no extra tools)
  - 1 = mild (one extra layer; still searchable; deterministic commands)
  - 2 = high (codegen/indirection; slow loops; multi-tool orchestration)
  - 3 = severe (hidden magic; multiple generators; interactive/manual steps; flaky loops)
- Value score (V): 0-3 (score 0 if you cannot cite evidence)
  - 0 = unproven/optional (no tests/docs/callsites/ops evidence)
  - 1 = convenience (small DX win; could be replaced without changing the contract)
  - 2 = proven leverage (multiple consumers; reduces a bug-class; real ops benefit)
  - 3 = mandatory (compliance/legal requirement; SLO-critical; audited change control)
- Delta (D) = T - V

Default verdict mapping (aggressive, but not reckless):
- D >= 2: replace or delete (prefer delete if unused)
- D == 1: slice now, replace next (or wrap to isolate first)
- D == 0: wrap or slice (reduce surface area and remove sharp edges)
- D == -1: keep, but simplify interfaces/entrypoints
- D <= -2: keep

Definitions (verdicts):
- keep: retain abstraction; reduce incidental friction (docs, scripts, entrypoints).
- wrap: keep internally, but put a stable adapter in front to localize future removal.
- slice: remove optional flexibility (plugins, multi-variant configs) to the one proven path.
- replace: swap for a lower-level primitive with a migration seam.
- delete: remove entirely.

Aggressive default policy:
- If value is not proven (tests/docs/callsites/ops evidence), treat it as optional and recommend reduction.
- If the abstraction exists "for flexibility" but only one variant is used, inline to the one variant.
- If an abstraction exists to prevent duplication but adds hops/tooling, prefer duplication.

Evidence-confidence modifier (required before final verdict):
- Confidence level (C): high | medium | low
  - high: constraints/value are proven with repo-local evidence (tests/docs/callsites/ops config).
  - medium: partial evidence exists, but at least one critical assumption is inferred.
  - low: external obligations are plausible (compliance/SLO/audit/runtime policy), but not proven locally.
- External-obligation guardrail:
  - If C=low and verdict is `replace` or `delete`, cap to `slice` or `wrap` until one of these is true:
    - explicit user approval to change external obligations, or
    - evidence proving no such obligations exist.
- Report confidence in the audit row notes for every `replace`/`delete` recommendation.

Interaction-evolution guardrail:
- If evidence shows interface evolution is essential (state-dependent allowed operations), treat that protocol boundary as core domain structure.
- In that case, prefer `slice`/`wrap` on incidental tooling around the protocol before attempting `replace`/`delete` of the protocol model itself.

### 3. Develop: Propose lower-level replacements
Pick the next lower rung on the replacement ladder (avoid big-bang rewrites).

Replacement ladder (common moves):
- Meta framework -> framework -> stdlib primitives.
- Codegen -> checked-in artifacts + small deterministic generator (or delete entirely).
- ORM -> query builder -> parameterized SQL.
- GraphQL -> REST/JSON -> RPC -> direct function calls (internal only).
- Implicit runtime gating -> explicit state-indexed protocol map (operation set per state) -> optional typed client/session wrappers.
- SPA -> server-rendered pages -> static HTML/CSS/JS.
- k8s -> Docker Compose -> single process + systemd (or platform native).
- Monorepo tool -> package-manager workspaces -> plain scripts.
- DI container -> explicit constructors/wiring.
- Custom DSL -> JSON/YAML/TOML with a small parser + schema.

Deconstruction patterns (agent-centric):
- "Make the invisible visible": replace conventions with explicit entrypoints and wiring.
- "Collapse configuration": many layers -> one canonical config file (with comments only if unavoidable).
- "Delete the orchestrator": replace toolchains with a single `scripts/dev` and `scripts/test` (or `make dev/test`).
- "Strangler seam": introduce a stable adapter boundary; implement the primitive behind it; migrate callers incrementally.
- "State-index the protocol": move scattered runtime checks into one explicit transition table (state x operation -> next state).

### 4. Deliver: Report findings and recommendations
Default output must include:
1) Abstraction audit (table).
2) Cut list (prioritized).
3) Migration plan (phased + proof signals + rollback).
4) Patch suggestions (minimal incisions; file/command level; no implementation).

## Output Profiles
Use one profile per response.

- Full profile (default): use the complete format in `Output Format (default full profile)`.
- Quick profile (small audits): use only when both conditions hold:
  - Scope is narrow (<=3 abstractions or one subsystem), and
  - The user asked for concise/minimal output.

Quick profile sections (exact order):
**0) Scope + assumptions**
**1) Top Abstractions (mini-audit)**
**2) First Cut Recommendation**
**3) Minimal Migration + Rollback**
**4) Risks / unknowns**

Quick profile minimums:
- Still include T/V/D for each listed abstraction.
- Still cite repo-local evidence (or explicitly mark missing evidence).
- Still provide one deterministic proof signal.
- If interface evolution is in scope, include one compact state-transition sketch (table or bullets) before final cut recommendations.

## Output Format (default full profile)
Use these exact section headers in order. If evidence is missing, keep the header and write `Not enough repo evidence yet.` rather than omitting sections.

**0) Scope + assumptions**
- In-scope surfaces: ...
- Out-of-scope: ...
- Constraints discovered: ...

**1) Abstraction Audit (table)**
Include one row per abstraction.

| Abstraction | Where | Why it exists (hypothesis) | Agent-tax (T:0-3 + why) | Value (V:0-3 + evidence) | Delta (D=T-V) | Verdict | Replacement |
|---|---|---|---|---|---|---|---|
| ... | ... | ... | T:2 - ... | V:1 - ... | +1 | keep/wrap/slice/replace/delete | ... |

Notes:
- "Value" must cite repo-local proof: tests/docs/callsites/ops config.
- If you cannot cite evidence, score V:0.
- "Verdict" must be one of: keep | wrap | slice | replace | delete.

**2) Cut List (prioritized)**
- P0 (delete first): ...
- P1: ...
- P2: ...

Each item must include: expected simplification, blast radius, and fastest proof signal.

**3) Migration Plan (per cut item)**
For each P0/P1 item:
- Seam/boundary: ...
- Phase 1 (reversible): ...
- Phase 2 (switch traffic/callers): ...
- Phase 3 (delete old path): ...
- Proof signals: ... (tests/build/run)
- Rollback lever: ...

**4) Patch Suggestions (minimal incisions; no code)**
List concrete, reviewable edits:
- Files to add/modify/delete: ...
- Commands to run (deterministic): ...
- What "done" looks like (signal): ...

**5) Risks / limits**
- ...

## Replacement Patterns (Examples)
- React/SPA for a small static site -> HTML/CSS/JS, no build step.
- Headless CMS for small docs/marketing -> Git + Markdown (+ static site generator if truly needed).
- ORM for simple CRUD -> parameterized SQL queries.
- GraphQL for a single client -> REST/JSON endpoints.
- State management framework for a small UI -> local state with explicit event handlers.
- Heavy task runner -> `scripts/*` or `Makefile` with 3-5 canonical commands.
- Multi-layer config system -> one config file + a small loader.
- Scattered auth/runtime guards -> explicit session-state protocol map (Anonymous/Authed/etc.) + thin per-state adapters.
- Dynamic capability checks spread across services -> capability-state transition table + adapter selection keyed by capability state.

## Interaction-Evolving Interface Addendum
Use this when the system's interface changes as a result of interaction.

Detection checklist:
- The allowed operation set changes after specific responses/events.
- Current behavior relies on distributed `if authorized`, feature flag, or capability checks across many call sites.
- Clients must "guess and fail" at runtime instead of knowing legal next operations from state.

Recommendation policy:
- Preserve essential protocol evolution; reduce incidental machinery around it.
- Prefer explicit protocol boundaries:
  - `state x operation -> next_state`
  - allowed responses per operation
  - adapter rules (`act`) and state updates (`upd`) for integration points
- Cut targets first: duplicated wrappers, hidden indirection, multipath config, and non-deterministic orchestrators around the protocol.

Proof signals for this mode:
- Depth-bounded trace tests (at least to depth 3) over legal transitions.
- One negative test proving an invalid transition is rejected or unrepresentable.
- Compatibility check showing a fixed-interface simplification (if proposed) preserves observable traces.

## Real Trigger Phrases (from session prompts)
Use these phrases as natural-language routing cues for `$reduce`:
- "It just feels over-engineered for what I want. Is there a way you can see that we could start simpler and build things back up?"
- "I really want to reduce the size of the codebase before building it back up."
- "Only the minimal needed to support what is needed to remain."
- "How much could we simplify things?"
- "Brilliant or over-engineered?"

Weekly re-measure loop:
- Baseline and trend:
  - `seq skill-report --root ~/.codex/sessions --skill reduce --snippets 20`
- Prompt-cue hit sampling:
  - `seq query --root ~/.codex/sessions --spec '{"dataset":"messages","where":[{"field":"role","op":"eq","value":"user"},{"field":"text","op":"regex_any","value":["(?i)over-?engineered","(?i)start simpler","(?i)reduce the size of the codebase","(?i)minimal needed","(?i)simplify things"]}],"select":["timestamp","path","text"],"sort":["-timestamp"],"limit":50,"format":"jsonl"}'`
- After one week, compare cue-hit samples and update frontmatter trigger examples only if precision improves.

## Questions (Judgment Calls Only)
- Research first; do not ask for discoverable facts.
- Ask only judgment calls, prefer 1 question, max 3.
- Use `request_user_input` when available; otherwise ask in a short numbered block.

Good questions (examples):
- "Can we accept some short-term duplication to delete this framework (recommended: yes)?"
- "Is it acceptable to add a compatibility wrapper so external callers remain stable (recommended: yes)?"
- "Is infra allowed to change, or is this strictly code-level (recommended: code-level only)?"

## Handoffs
- If trade-offs remain unclear, invoke `$creative-problem-solver`.
- If implementation is requested, hand off to `$tk`.

## Pitfalls
- Generic advice without locations/evidence.
- Big-bang rewrites without seams, proof signals, and rollback levers.
- Removing abstractions that are carrying compliance/ops obligations (without a replacement plan).