SMARTS

SMARTS is codeArbiter’s six-lens design-quality rubric for material engineering solution choices. It makes the reasons for a recommendation inspectable: the alternatives, six engineering lenses, the evidence behind each judgment, and the factors the rubric does not cover. It is useful when a change admits more than one plausible approach. It is not a numerical score that automatically selects the winner, and it is not a command: it runs inside the workflows that already shape, plan, fix and reconcile work.

SMARTS grants no approval. The surrounding lane determines who can make the decision. Interactive reconciliation needs an explicit user choice. A requested sprint makes reversible method decisions inside its existing scope, including close calls. Use SMARTS when a difficult trade-off warrants comparison; routine steps need no scoring exercise. Neither caller gains authority beyond the user’s actual request, and a strong recommendation never stands in for a decision the lane requires.

Three depths

Every evaluation uses the same lenses and verdicts; the workflow chooses how much of it to show.

• Scan — a lightweight six-lens fitness pass when a choice is material but does not need the full table. It names the material strengths, weaknesses, unknowns and decisive lenses.
• Comparison — the full option-by-option table. It appears when two or more materially plausible approaches exist, when you explicitly ask for a full SMARTS read, or when reconciliation or arbitration needs it. Asking for the full read changes the presentation only; it adds no command and no decision authority.
• Delegated decision — a requested sprint choosing a reversible in-scope method on your behalf and logging the reason in its sprint log.

Feature shaping compares approaches during brainstorming only when two or more are materially plausible, before one is recommended. A single credible approach gets one line that says why no alternative was credible, and no table; nobody invents a straw alternative to fill one. The comparison dispatches no grader or scout and does no bulk read of plans or decisions. A recommendation informs the lane’s existing decision owner and does not authorize anything by itself. The small lane scans only when a change has a material solution choice; otherwise it states SMARTS: no material solution choice and adds no table. Debugging uses no SMARTS at all: a fix compares remediation strategies only after the root cause is confirmed.

Context before verdicts

A verdict means something only at a stated context. Before judging a material choice, codeArbiter establishes just the context that makes the lenses meaningful: the decision itself, its scope and horizon, and scale, failure, trust-boundary or non-SMARTS constraints only when they could change a verdict. The context comes from existing project records, the active spec and your steering. It is scope-sized, fail-soft and creates no new project or configuration file.

Begin with recorded intent

Before sprint or specification-shaping scoring, the recorded-intent check asks whether the project has already answered the question. The source order is an explicit user decision in the current session, an unsuperseded decision-log entry, an accepted ADR, then the three project planning artifacts. Project context and recorded open/deferred questions constrain the comparison at their recorded level. Relevant indexes and headings come first; the check is not a bulk read of every project document.

There are three useful results. Answered means follow the highest-ranked decision and cite it. Constrains means carry that source into the affected comparison cells. Silent means no record answers the question, so proceed and identify that absence. A missing planning or decision directory alone is not a reason to stop this check.

A request to contradict recorded intent is different from silence. In an interactive lane it can require reconciliation or supersession. A sprint surfaces a real contradiction rather than running a mid-sprint reconcile session on its own. A recorded deferral whose re-evaluation trigger has occurred is reopened and surfaced, not quietly treated as permission to choose anew.

This Step 0 applies to sprint and brainstorming. The arbitration skill, grader and optional decision-challenger are explicitly exempt from that separate step: their work already compares the conflicting record under the arbitration authority order. That exception does not exempt them from the six-lens scoring rules.

The Six Lenses

Scalable asks whether growth fits the design without an architectural rewrite. A facility for millions of jobs is not automatically an advantage for a tightly bounded export. Maintainable asks whether future developers can understand and change the complete solution, including its operational dependencies. Available asks whether the capability is reachable when needed; this is not a demand that every project implement high availability.

Reliable concerns correct, predictable and durable outcomes when work fails or repeats. Availability and reliability can diverge: an endpoint can respond while returning an incorrect result. Testable asks whether meaningful success and failure behavior can be checked with repeatable tests. Securable asks whether the design can meet the project’s security controls without a retrofit. It is a design judgment, not a completed security review or bypass permission.

The same lenses apply to every option. The worked comparison below makes its assumptions visible so a reader can disagree with a premise rather than merely disputing an adjective.

One bounded example · two materially different options

Where should a saved-search export run?

Illustrative project: 50 saved searches per request, an existing application endpoint, no job infrastructure, and an approved synchronous response. These assumptions are not measurements.

Recorded intent first: The accepted synchronous-response decision already answers the execution-mode choice. This comparison explains the tradeoffs; it cannot reopen that decision by scoring alone.

01Scalable

Does growth fit the stated demand?

Existing request path

Adequate.

Assumed 50-search bound fits the current endpoint design; no throughput benchmark is claimed.

New queue and worker

Strong.

Independent workers isolate export capacity, beyond the stated requirement.

02Maintainable

Who must understand and change the whole path?

Existing request path

Strong.

One service owns serialization and delivery; existing deployment and rollback remain.

New queue and worker

Weak.

Adds queue, worker, job status and retry ownership to a project without job infrastructure.

03Available

What must be reachable to deliver the result?

Existing request path

Adequate.

Export is reachable while the application is available; it shares the application failure boundary.

New queue and worker

Weak.

Successful delivery also needs the new queue, worker and result retrieval path.

04Reliable

What can fail, duplicate, or be lost?

Existing request path

Adequate.

One response avoids persisted job state; interrupted requests still need an explicit retry contract.

New queue and worker

Weak.

Duplicate delivery, job recovery and retention policies are not yet specified.

05Testable

Which failure modes can be checked deterministically?

Existing request path

Strong.

Existing request tests can check empty results, quoting and failure responses in one process.

New queue and worker

Weak.

Adds queue, worker and polling integration cases without an existing test harness.

06Securable

Can the design satisfy the named security posture?

Existing request path

Adequate.

Uses the existing authorization boundary; CSV injection and export permission still require review.

New queue and worker

Weak.

Job-result authorization, storage access and retention introduce new unreviewed boundaries.

Illustrative recommendation · strong: Retain the existing request path for this illustrative scope. Maintainable and Testable align; the unrequested scaling capability does not justify a new system.

Cost, deadline, team experience, vendor lock-in and political acceptability stay outside the six lenses. No sums, automatic approval or performance guarantee follow from these cells.

Inspect the scoring contract

Verdicts and Strength

Each cell begins with Strong, Adequate, Weak, Indifferent or Unknown. The canonical format caps the cell at 25 words and its justification at 20. The justification names an option property, project constraint or failure mode; “best practice” is not evidence. The rubric rejects hedging adverbs: genuine uncertainty is an Unknown, not a softened adjective.

Unknown is not Indifferent

The two verdicts answer different questions. Indifferent is a finding: the evidence shows the lens does not distinguish the options at the stated context, so every option takes it. In a single-option scan it means the lens is not material to this choice. Unknown is an admission: the evidence needed to judge the lens is missing, contradictory or not yet established.

Every Unknown names its missing observation and states whether it is decision-critical, meaning that observation could change which option is selected. An Unknown is never neutral and never quietly becomes Indifferent, Adequate or a pass. A decision-critical Unknown blocks a strong recommendation, blocks selecting the option that carries it, and is surfaced before any irreversible or authority-bearing choice. A non-critical Unknown can stand only when the output names the missing observation and why it does not control the decision. An Unknown cannot bypass a hard gate or manufacture authority.

Recommendation strength is a separate field: strong when dominant lenses align cleanly, non-SMARTS factors confirm and no option carries a decision-critical Unknown; moderate for a qualified or single-lens advantage; and tied when no preferred option emerges. There is no weak recommendation level. Counting Strong cells or converting labels into invented numbers would lose the project’s actual priorities. When lenses conflict, an explicit current or approved-spec priority comes first, then a recorded project priority, then precedent labelled as precedent; with none of those, a tie stays tied.

Cost, time-to-market, team-skill fit, vendor lock-in and political acceptability are non-SMARTS considerations. They must remain visible alongside the table when relevant. A technically attractive option can still be the wrong business choice. In the example, an established synchronous-response decision must be respected before any new queue is considered.

Where it runs

Two callers · distinct authority

Who may choose after the comparison?

These are decision handoffs, not a complete execution map. Command labels use Claude Code spelling. Shared scoring does not make the callers interchangeable.

/ca:reconcile

Interactive reconciliation

Which competing position should govern?

1. 1 · Command → skill

   Locate and compare

   decision-variance selects full or named scope, locates the required exact sources and indexes relevant decisions plus scaffold evidence. Report-only returns without decision capture; missing inputs remain visible.

2. 2 · Skill · optional agents

   Recommend with evidence

   The skill classifies variances and applies SMARTS. Large passes may use scout and grader; an optional decision-challenger does not decide for you.

3. 3 · Human decision

   Choose explicitly

   Report-only returns before this step. In reconciliation, the user resolves remaining variances; an already-selected concrete choice is not requested again. A strong recommendation is not decision authority.

4. 4 · Skill return

   Append and recommend

   In reconciliation, append the attributed choice immediately without rewriting history. Recommend downstream work; do not edit project artifacts or code to make the variance disappear.

Endpoint: A read-only report, or a recorded user choice in reconciliation, with downstream recommendations. Replacement ADR authoring and implementation remain separately directed.

Inspect this caller’s contract

/ca:sprint

Autonomous execution

How can authorized work proceed within its boundary?

1. 1 · User intent

   Establish the scope

   Maintain the specification and plan under existing authorization. Ask only about consequential missing choices and honor explicit review pauses.

2. 2 · Recorded-intent check

   Preserve settled choices

   Read relevant decisions and constraints. Follow applicable choices; surface a genuine conflict without repeating an answered question.

3. 3 · Skill → task execution

   Decide within scope

   Use SMARTS for difficult trade-offs when helpful. Maintain methods within the agreed outcome, reuse current evidence, and repair affected failures.

4. 4 · Retained evidence

   Log and hand off

   Record material decisions and meaningful uncertainty. Preserve actual security controls, user stops, host permissions and delivery boundaries.

Endpoint: Authorized work proceeds to the PR handoff, not an autonomous merge. The log records reasoning; it does not grant additional authority.

Inspect this caller’s contract

During reconciliation, prior decisions provide a Precedent: line with relevant IDs and the observed lens pattern. Thin history cannot support an invented precedent, and precedent never outranks an explicit higher-authority decision. A strong recommendation remains a recommendation until the user makes or explicitly accepts the choice.

During a sprint, moderate and tied in-scope choices do not create new routine human checkpoints. The sprint breaks a tie using its stated priorities and the existing conflict hierarchy. It logs low confidence for moderate/tied choices and high for strong choices. An answered recorded-intent choice is logged with high confidence and its citation. Confidence is not a probability estimate or a verification result. Security boundaries, irreversible actions, overrides, missing user authority, conflicting accepted decisions and merge remain actual stop boundaries.

Maintain methods within the agreed outcome

Update implementation steps, verification runners and task decomposition through the existing typed plan writer when they remain within the authorized outcome. Record the reason, preserve stable references and user stops, and inspect concurrent work before changing an active task. Ordinary method maintenance needs no separate artifact approval or method grant.

Reuse checks and review conclusions while their relevant source, requirements and inputs still match. Recheck affected evidence after a material change, and keep new failures visible. A changed receipt or session alone does not restart review. A different product outcome, spending outside the agreed limit or an irreversible action still belongs to the actual decision owner.

Audit a Verdict

Start with the evidence that could change the outcome. Are the options materially different, or is one a deliberately weak alternative? Does each cell refer to the actual scale, deployment boundary and failure behavior? Which lens is decisive, and is that priority stated in project records? Keep unknown facts visible and ask for the missing observation rather than inventing a confident cell.

Next identify the caller and recorded outcome. Sprint reasoning belongs in .codearbiter/sprint-log.md, with intent and confidence. Interactive arbitration decisions belong in .codearbiter/decisions/decision-log.md, with user attribution. Its Artifact-section-hash binds the cited source artifact section, not the log entry’s own prose or the whole codebase. A changed hash signals changed referenced text; it does not decide that the recorded choice is wrong.

A useful completion check is to explain the choice, its strongest counterargument, its source, and the specific authority needed for the next action. Use Run an autonomous sprint for execution, ADRs and the decision log for durable choices, and Auditability for the later evidence packet. The exact comparison and arbitration rules remain in the grader and decision-variance references.