Functionality Complexity Tradeoff

Functionality pruner

Two stages, in both modes: a necessity gate (does the problem this code addresses occur in this context?), then a worth ledger (does the value justify the cost?). Complexity itself is measured by structural-simplification; the upstream principles (YAGNI, scope control, proportionality) live in architecture-guidelines.

Core Directives

1. Necessity precedes worth. Code guarding against an architecturally impossible state has no product value for that failure mode: skip the worth ledger and emit OBSOLETE unless the code is the canonical executable invariant (§1c).
2. Separate the ledger. Value and cost are distinct axes. Score each independently; never collapse into a single number.
3. Cost compounds, value decays. Value is realized per use; cost accrues on every future change, test run, review, and incident. Evaluate over the feature's expected lifetime.
4. The default is No. If worth is not clearly positive, reject or minimize. YAGNI is the null hypothesis.
5. Build and audit share a model. A feature that would fail as a proposal today should fail as existing code today.
6. Remove over refactor, refactor over rewrite. Negative worth or a failed necessity gate prefers safe removal or deprecation to elaborate justification. Removal still follows migration, rollback, and compatibility constraints.
7. Outcome evidence informs worth; it is not the verdict. Consume current linked outcome evidence when available. Completion, deployment, or adoption alone cannot prove downstream value, and no hypothesis state automatically dictates a worth decision.

1. The Necessity Gate

Confirm the problem exists in this stack before scoring V and C. If it does not, the worth ledger does not apply: emit OBSOLETE in retrospective mode, or DROP with a necessity-failure rationale in prospective mode, and apply §7b's safety constraints before removing code. Example: a monorepo single-page application deployed as one artifact cannot run client and server at different versions, so its "client version check" has no V for that failure mode — not low V. Worth scoring would misclassify it as low-V / low-C DEFER or KEEP; the necessity gate catches it.

1a. Categories of non-problem-solving code

1b. Detection heuristics

Run these before scoring V or C. A high-confidence positive routes to OBSOLETE or DROP, subject to the exceptions in §1c and §8e.

[!IMPORTANT] The invariant audit is the highest-yield necessity check. Most non-problem-solving code defends against violations of invariants the surrounding stack already guarantees. Enumerate those invariants before reading the code, then walk the branches with the list in hand.

1c. Necessity findings that are not deletions

[!WARNING] Some "impossible-state" code documents an invariant rather than enforcing one — an assert version_match meant to fail loudly if a future contributor changes the deployment topology. That has small but real value as machine-checkable documentation. If the code is the canonical record of an invariant nothing else captures, SIMPLIFY (downgrade to a comment, an ADR reference, a build-time check, or a test) rather than OBSOLETE.

Inverse failure mode (§8e): some complexity that resembles cargo-culting is load-bearing because the simple version was measured to be too slow, too unsafe, or too fragile. Read the original rationale before voting OBSOLETE on anything that merely looks like a non-problem.

1d. Necessity vs. low worth

Record the distinction so a later audit does not reintroduce the same code: "it cost more than it returned" invites debate about thresholds; "client/server version skew cannot occur in a single-artifact deploy" closes the question.

1e. Obligation vs. mechanism

A subject can pass the necessity gate — the problem is real — while its grain is still inflated by mechanism nobody demanded. Before scoring worth, restate each requirement behind the subject in two parts:

• Obligation — the outcome, evidence, or restriction that must exist (a record with actor/time, a gate before a step, an actor limitation).
• Mechanism — the specific rights, roles, endpoints, record types, or protocols the requirement text or the implementation chose to satisfy it.

Mechanism the obligation does not force is a SIMPLIFY candidate even when the functionality itself is KEEP. Audit in two passes: first within the current requirements to establish the floor, then treat careful requirement edits as prospective candidates scored on this same ledger. Flag edits with real external trade-offs (consent models, public intake, protocol surfaces) as explicit product decisions rather than deciding them silently, and route changes of requirement meaning through requirements-grounding. Three floors are never negotiable: legal/regulatory obligations, separation-of-duties (second-person) controls, and external protocol surfaces others depend on.

Typical yields: an actor condition encoded as a dedicated right or role where a membership attribute or workflow-state gate satisfies the same acceptance criterion; a person-split where the obligation only demands recorded evidence before the next step; one endpoint per read projection of an aggregate the caller already fetches.

2. The Worth Model

Once necessity passes, worth is the relation between Value (V) delivered and Cost (C) imposed over lifetime L. Both sides are multi-dimensional.

Value axes

Aggregate product value ≈ U × F × R × I. If any axis is zero, ordinary product value is zero; external floors, keystone cost, and safety exceptions are handled separately in §8.

[!IMPORTANT] A feature loved by 2% of users, used once a year, with a trivial workaround, has near-zero total value no matter how elegant it is. Score honestly — especially R and F, which are routinely inflated.

Cost axes

Structural cost is delegated to structural-simplification: the Subsystem-kinds Δ, Dependency-edges Δ, Max-chain-depth Δ, Subsystem-count Δ (ΔD, ΔK, ΔP, Δn in its Reporting Vocabulary) introduced (prospective) or already present (retrospective). This skill adds three ongoing-cost axes that structure alone does not capture:

Aggregate cost ≈ (ΔD + ΔK + ΔP + Δn) + (M + X + E) × L

The worth inequality

Copy code
Worth > 0   ⇔   V × L   >   C_structural + (M + X + E) × L

For short-lived code, the structural footprint dominates. For long-lived code, M + X + E dominates. Most production features are long-lived; plan for the ongoing term.

[!WARNING] Evolution tax (E) is the most-underestimated axis because it is invisible in the current code review. It shows up later, as the PR that "should have been small but touched twelve files."

3. Two Modes

The model is the same; the inputs differ.

3a. Prospective — evaluating proposed functionality

Applied to tickets, specs, PRDs, loose ideas, or PR scope before implementation. All inputs are estimates; record confidence explicitly.

1. State the functionality in one sentence: "This allows [who] to [do what] so that [outcome]."
2. Run the necessity gate (§1): the failure mode must be reachable in the target stack and not already owned by another layer. A prospective necessity failure is rare but consequential: it stops a build that would have produced dead code on day one.
3. Score V axes with evidence: user interviews, request tickets, analytics of the workaround, competitor behavior. Opinions are not evidence and cannot support a high-confidence build decision. Cite linked outcome hypotheses when present; before release they express expected value, not observed impact.
4. Score C axes against a concrete implementation sketch: files touched, new abstractions or dependencies introduced, tests required, failure modes created.
5. Apply the Decision Protocol (§6). Verdicts are prospective (§7a).

3b. Retrospective — auditing existing functionality

Applied to code, subsystems, features, capabilities, or flags that already exist. Inputs are observable; bias toward measurement over judgment.

1. Define the boundary: files, symbols, entry points, feature flags, routes, or callers.
2. Run the necessity gate (§1): walk the §1b heuristics before any worth scoring. A positive finding short-circuits the rest of the audit to OBSOLETE.
3. Score V from usage data:
   • Telemetry hits per time window, per user cohort.
   • Reach: unique users or flows that enter this code path.
   • Irreplaceability: does an alternative path exist? Do users already use it?
   • If V cannot be measured, that itself is a finding — instrument, identify an external floor (§8c), or keep confidence Low.
   • Consume current outcome-evidence records from requirements-traceability. Preserve the canonical hypothesis version, cohort, threshold, window, and guardrails. stale or inconclusive evidence cannot support High value confidence; rejected evidence lowers the supported value claim but does not by itself prove zero value.
4. Score C from current observable state:
   • Structural: measure D, K, P, n per structural-simplification.
   • M: dedicated tests, doc pages, recent commit churn, dependency drift.
   • X: bug ticket history, incident postmortems, security/perf hotspot reports.
   • E: count of PRs / design docs where this feature caused scope expansion, workarounds, or delays.
5. Apply the Decision Protocol (§6). Verdicts are retrospective (§7b).

[!NOTE] A retrospective audit with no telemetry available should first return an instrumentation task, not a verdict — unless the necessity gate has already produced a finding: you cannot measure usage of a code path that cannot be triggered. Deleting a feature merely because you cannot see it being used is survivorship bias in reverse; removing it because the failure mode it guards against cannot occur is structural reasoning.

4. Heuristic Checks

Fast worth signals — usage silence, workaround in the wild, single caller, flag defaulted off, orphan test, churn hotspot, churn × complexity, defect clustering, bug-fix-to-feature ratio, blocked PRs, documentation rot — and the axis each one moves. The necessity heuristics in §1b run first. Read references/worth-signals.md when scoring V or C in retrospective mode, and run churn × complexity before any subjective judgment.

5. Forcing Questions

Four interrogations — necessity, value, cost, counterfactual — each exposing a common failure mode. Answers MUST be written, not implicit. Read references/forcing-questions.md and answer the necessity questions before any value scoring. A removal cost in 12 months that exceeds the build cost today is a one-way door: apply §8 before committing.

6. Decision Protocol

1. Run the necessity gate (§1). On failure, emit per §1 and skip the remaining steps.
2. Score V axes (U, F, R, I) on a 0–3 scale with one-line evidence per axis. When outcome evidence exists, cite its hypothesis ID, state, freshness, and observation identity; do not replace its threshold or guardrails with a more favorable interpretation.
3. Score C axes:
   • Delegate D, K, P, n to structural-simplification (deltas for prospective; absolute measured values for retrospective).
   • Score M, X, E on 0–3 with one-line evidence per axis.
4. Record confidence (Low / Medium / High) for each side independently.
5. Compare across both ledgers without summing.
6. Classify using the Worth Matrix (§6a) and apply the confidence gate (§6b).
7. Emit the Output Contract (§9).

6a. The Worth Matrix

The first verdict in a cell is prospective (accept / reject), the second retrospective (keep / simplify / delete). Necessity failures bypass the matrix.

6b. Confidence gate

A verdict carries the confidence of its weakest input. If either V or C confidence is Low:

• Prospective → default to DEFER. Gather evidence before committing to high-cost action.
• Retrospective → default to QUARANTINE. Add instrumentation, revisit after N weeks with measured data.

Do not commit to irreversible verdicts (BUILD, DELETE) on low-confidence estimates. OBSOLETE is exempt from the confidence gate when the necessity finding is itself High confidence — a structural impossibility does not become more or less impossible with more data.

An unmeasured, inconclusive, or stale outcome assessment keeps the affected value claim Low unless independent current evidence supports it. supported may raise confidence only within the measured cohort, window, and guardrails. Authoritative floors in §8c remain source-driven and do not require an empirical outcome hypothesis.

7. Verdicts

7a. Prospective verdicts

7b. Retrospective verdicts

[!WARNING] "Interesting", "clever", and "elegant" are not verdicts. Cleverness imposes cost but rarely contributes measurable value. If a reviewer's rationale reduces to "it's nice that we have this," require value evidence before KEEP. If it reduces to "it's defensive — just in case," apply the necessity gate before defaulting to KEEP.

8. Asymmetric Trade-offs

Five cases where the Worth Matrix alone gives the wrong answer: 8a optionality premium (a named, probable next feature; speculative optionality fails YAGNI), 8b irreversibility tax (public API, persisted schema, wire format: raise the required V one tier or require High confidence), 8c regulatory / contractual / accessibility floor (fixed-high U once the external requirement is mapped to this code path), 8d keystone cost (local C that holds global complexity down; measure the whole-system deltas before DELETE or SIMPLIFY), and 8e hot-path performance or safety (measured, load-bearing complexity; the inverse of the necessity gate, told apart by whether the original rationale's premises still hold). Read references/asymmetric-tradeoffs.md whenever the matrix returns NEGOTIATE, a floor may apply, or complexity looks load-bearing.

9. Output Contract

Every application of this skill MUST produce a coder-facing decision record, concrete enough to choose the next edit, test, telemetry task, or rejection:

Copy code
Subject:        <feature / subsystem / ticket / path under review>
Mode:           Prospective | Retrospective
Necessity:      Pass | Fail
Necessity note: <if Fail: which §1a category, which invariant violated /
                 prerequisite missing / premise lapsed; one line.
                 If Pass and non-trivial: brief note on what made it pass.>
V scores:       U=<0-3>  F=<0-3>  R=<0-3>  I=<0-3>       (1-line evidence each; OMIT if Necessity=Fail)
C scores:       Subsystem-kinds Δ=<±n>  Dependency-edges Δ=<±n>
                Max-chain-depth Δ=<±n>  Subsystem-count Δ=<±n>   (prospective: deltas; retrospective: measured absolutes; OMIT if Necessity=Fail)
                M=<0-3>  X=<0-3>  E=<0-3>                 (1-line evidence each; OMIT if Necessity=Fail)
Confidence V:   Low | Medium | High                       (OMIT if Necessity=Fail)
Confidence C:   Low | Medium | High                       (OMIT if Necessity=Fail)
Outcome evidence: <hypothesis IDs, states, freshness, observation links, or none / not applicable>
Decision:       <BUILD | BUILD-minimal | NEGOTIATE | DEFER | DROP | KEEP | SIMPLIFY | QUARANTINE | DEPRECATE | DELETE | OBSOLETE>
Rationale:      <2–4 sentences tying scores → decision, or necessity finding → OBSOLETE>
Next action:    <build minimal increment, delete path, add telemetry, write test, update lint rule, or stop>
Verification:   <command / telemetry / caller check / Not run + reason>
Minimal alt:    <smallest increment preserving most V, if applicable>
Revisit when:   <measurable trigger or calendar date>

[!IMPORTANT] Revisit when is non-optional for DEFER, QUARANTINE, BUILD-minimal, and DEPRECATE. Every such decision MUST have a measurable trigger (usage threshold, date, dependency version, adjacent feature shipping) or it will rot into a permanent maybe. OBSOLETE needs none: its trigger is a change in the stack's invariants — the deployment topology splits, the type system loosens, the upstream guarantee is removed, or the lapsed dependency returns — which reopens the case automatically.

10. Common Patterns

A lookup of recurring subjects — impossible-state guards, duplicated defenses, transplanted patterns, completed-launch flags, one-user abstractions, "just in case" flexibility, quarterly admin tools, legacy integrations of unknown usage, compliance paths, benchmarked optimizations — with the verdict each typically earns and the section that decides it. Read references/common-patterns.md to calibrate a verdict against precedent; the pattern never replaces the ledger.

11. Composition with Sibling Skills

• requirements-grounding owns outcome-hypothesis meaning, thresholds, cohorts, guardrails, and revisit intent; requirements-traceability owns measurement links, evidence state, and freshness for the exact hypothesis version. This skill consumes both and alone issues the functionality-worth verdict.
• structural-simplification owns the complexity measurement (D, K, P, n); cyclomatic, cognitive, and similar metrics enter the C side only through it and the churn × complexity heuristic.
• architecture-guidelines and the stack's own ADRs own the principles and the architectural invariants the necessity gate consumes as the basis for impossibility findings.
• continuous-improvement — verdicts that repeatedly contradict current practice or sibling skills signal a skill update, not case-by-case overrides. Repeated OBSOLETE findings in one area signal adding the relevant invariant to architecture-guidelines, so future contributors do not reintroduce the same non-problem-solving code.