Residual Complexity Justification Template¶
Template — instantiates Essential-Accidental Complexity Triage
A template for recording why a complexity source remains and when it should be revisited.
Residual Complexity Justification Template is a fixed form for answering one question about every piece of complexity a triage chooses not to remove: why does this remain, and under what condition should we look again? Its defining trait is that it is a standing record format, not an activity — it is the reusable structure that captures, per retained complexity source, the reason it stays (a binding constraint, an accepted trade-off, or an unresolved unknown) and the revisit trigger that should reopen the decision. It exists so that "we decided to keep this" leaves a durable, inspectable trail instead of evaporating into folklore that the next team must reverse-engineer.
Example¶
A medical-device firmware team has just finished a simplification pass and is left with three complexity sources they deliberately kept. Rather than let those decisions vanish, they fill out one justification record each. The dual redundant sensor-reading path is recorded with reason "binding — a safety standard requires independent confirmation of a critical reading," linked to the specific regulatory clause, with revisit trigger "only if the governing standard is revised." The hand-tuned calibration table is recorded as an "accepted trade-off — a cleaner model exists but is unvalidated on older hardware," with revisit trigger "when the last pre-2019 unit is retired from the field." The puzzling startup delay that nobody could explain during the audit is recorded as "unresolved — origin unknown, removal risk unquantified, held," with revisit trigger "next time the boot sequence is touched, investigate before shipping." Each record names an owner and a date. A year later, when a new engineer wonders why the startup delay is there, the answer is a document, not a shrug — and the trigger tells them exactly what to check before touching it.
How it works¶
- One record per retained source. Every complexity source the triage keeps gets its own filled template; nothing stays "just because" without an entry.
- Force a reason of a named kind. The reason field must resolve to a binding constraint, an accepted trade-off, or an unresolved unknown — three lanes that route the source correctly downstream.
- Attach a revisit trigger. Each record states the concrete condition that should reopen the decision, so retention is provisional and time-bounded, not permanent by default.
- Assign owner and date. The record is stamped so accountability and staleness are visible, and a held unknown is not quietly forgotten.
Tuning parameters¶
- Reason taxonomy — how many kinds of "why it stays" the template admits; more categories capture nuance but make the form heavier to fill and harder to aggregate.
- Trigger specificity — whether the revisit condition must be concrete and checkable or may be a vague "someday"; concrete triggers actually fire, but demanding them slows record-keeping.
- Evidence linkage — whether a "binding" reason must cite the constraint (a clause, a contract, a failure case); required links make the record auditable but cost effort.
- Review cadence — how often open records are swept for fired triggers or staleness; frequent sweeps keep the ledger honest but consume attention.
When it helps, and when it misleads¶
Its strength is institutional memory: the most expensive complexity to manage is the kind no one remembers the reason for, and a standard justification record turns each retention into a defended, revisitable decision — so the next team inherits reasons and triggers instead of fear. Its lineage is the same discipline behind recording an architecture decision at the moment it is made, so the "why" survives the people who made it.[1]
Its failure mode is ritual: a template can be filled with hollow justifications ("kept for compatibility" with no cited consumer) that launder a lack of decision into the appearance of one, and a "binding" reason asserted without evidence is just deferral dressed as diligence. The classic misuse is a revisit trigger set to "someday" — a record that can never fire and so makes the retention permanent while looking provisional. The guarding discipline is to require a concrete, checkable trigger and a cited reason for any "binding" claim, and to sweep the open records periodically so fired triggers actually reopen the decision.
How it implements the components¶
residual_complexity_rationale— the template is the standard record of why each retained complexity source stays; it is this component's canonical format.irreducible_constraint_register— records whose reason is "binding" reference the constraint that forces retention, contributing entries to the durable constraint register.uncertainty_hold_bucket— sources retained as "unresolved" are captured as explicit held unknowns with a trigger to investigate, rather than dropped.
It does not estimate the payoff of removing anything (removal_payoff_estimate) — that is refactoring_paydown_plan; nor does it surface or inventory the burdens in the first place (approach_induced_burden_inventory) — that is complexity_attribution_workshop.
Related¶
- Instantiates: Essential-Accidental Complexity Triage — the template is the archetype's memory: the durable justification for everything the triage chose to keep.
- Consumes: essential_accidental_complexity_audit — its essential, mixed, and unresolved verdicts are the retained sources this template documents.
- Sibling mechanisms: complexity_attribution_workshop · domain_invariant_review · legacy_constraint_map · interface_surface_reduction_review · dependency_simplification_map · complexity_budget_gate · refactoring_paydown_plan · simplification_regression_suite
Editorial Notes¶
Form Classification¶
Form family: Record, Log & Register
Rationale: Residual Complexity Justification Template operates by creates and preserves one accountable justification record for every retained source of complexity. That concrete deployed or enacted form is Record, Log & Register under the frozen taxonomy.
Nearest alternative: Interface, Display & Cue — Although Interface, Display & Cue can support this mechanism, the frozen evidence makes its operative form the act that creates and preserves one accountable justification record for every retained source of complexity; the alternative is therefore secondary rather than defining.
Review outcome: Adjudicated after independent review; medium confidence.
Origin Attribution¶
Primary origin: Engineering & Design
Origin pattern: Cross-disciplinary synthesis
Present-day reach: Multi-domain
Rationale: Engineering architecture descriptions record major decisions, limitations, rejected alternatives, tradeoffs, and rationale so later maintainers can understand and revisit accepted complexity.
Related originating lineages:
- Computer Science & Software Engineering — computer_science contributes software, workflow, data-structure, and automation practice to the mechanism’s formative or independently convergent form; that contribution does not displace the primary engineering_design lineage.
- Organizational & Management Science — organizational_management contributes ownership, portfolio review, coordination, and operational governance to the mechanism’s formative or independently convergent form; that contribution does not displace the primary engineering_design lineage.
Review resolution: The blind reviewers disagreed on primary lineage; authoritative research supports engineering_design over the competing primary. Engineering architecture descriptions record major decisions, limitations, rejected alternatives, tradeoffs, and rationale so later maintainers can understand and revisit accepted complexity. The cited NASA Software Engineering Handbook: Architectural Decisions and Rationale provides direct evidence for that defining form. Alternates are retained only where they contributed an independent formative tradition, while domain_reach=multi_domain records later transfer separately from historical origin.
Review outcome: Researched adjudication after independent review; high confidence.
Sources consulted:
References¶
[1] An Architecture Decision Record (popularized by Michael Nygard, 2011) captures a significant decision, its context, and its consequences at the moment it is made. This template applies the same idea narrowly to complexity that is kept: it records the reason and the conditions under which the decision should be revisited, so retention never becomes unexplained inheritance. withdrawn registry ↩