loss-driven-development

Apply after any non-trivial implementation task — evaluates whether an ADR is warranted, writes to Atelier-ADR repo when yes, names the skip reason when no, and generates E2E tests for every new structural invariant so LDD has a loss signal. High bar: most tasks produce no ADR.

Loss-Driven Development (LDD) — Gradient Descent for Agents. Use whenever the user prefixes a message with 'LDD:' or mentions LDD, loss, gradient, SGD on code, drift, refinement loop, outer loop, inner loop, method evolution, or 'apply LDD'. Dispatcher for 14 sub-skills (reproducibility-first, root-cause-by-layer, loss-backprop-lens, e2e-driven-iteration, loop-driven-engineering, iterative-refinement, method-evolution, drift-detection, dialectical-cot, dialectical-reasoning, docs-as-definition-of-done, define-metric, architect-mode, bootstrap-userspace) loaded on demand from references/. Also triggers on: failing test, bug, error, flaky, symptom patch, design, architect, greenfield, refactor, polish, declaring done, ready to merge, release candidate, drift check.

Use at the start of any LDD session running under Claude Code — auto-installs a permanent statusline that shows the current LDD task, loop, iteration, loss, and a Unicode loss-curve sparkline at all times, without any user action or configuration. Idempotent, merge-safe, project-local. Silently no-ops on non-Claude-Code hosts. Fires once per session in parallel with `bootstrap-userspace`.

Use whenever the user prefixes a message with "LDD:" or mentions LDD, loss-driven development, loss, gradient, SGD on code, drift, refinement loop, outer loop, inner loop, method evolution, or "apply LDD". Bootstrap / entry-point skill that explains how to dispatch the other LDD skills and the trigger-phrase table they respond to.

The 5-phase design protocol that is active at thinking-levels L3 and L4. NOT a separate mode — it is the discipline the level preset pulls in. Opt-in via four paths — inline `LDD[level=L3]:` (or `LDD[level=L4]:`) prefix, the `/ldd-architect` command, trigger phrases like "design" / "architect" / "from scratch" / "greenfield", or the thinking-levels auto-dispatch landing at L3 / L4 (9-signal scorer; see `../using-ldd/SKILL.md` § Auto-dispatch: thinking-levels). Supports three creativity levels (`conservative` | `standard` | `inventive`) that change the loss function, not the amount of structure.

Use at the start of any LDD task when there is no existing `.ldd/trace.log` readable in the working directory — fires before any other LDD skill writes trace state. Detects the host's persistence capabilities (filesystem, artifact/canvas, conversation-history, memory-pointer, inline-only), picks the most durable tier silently without prompting the user, restores any prior trace state it finds, and announces the chosen store in the LDD trace block's `Store :` header line. Makes LDD portable across Claude Code, Claude Desktop, Codex, Gemini CLI, Cursor, ChatGPT, and any other host the LLM can introspect.

Use when the agent or the user wants to introduce a new measurable quantity as a first-class loss component — e.g., tracking cyclomatic complexity alongside test_pass_rate, or adding a domain-specific rubric to a reasoning chain. Forbids ad-hoc arithmetic on observations and forbids using a new metric as a load-bearing decision gate until calibration has passed. Extends LDD's loss framework to agent-defined objectives without touching LDD core.

Use at the start of any non-trivial engineering task (feature, bugfix touching more than one file, refactor with observable behavior change, incident response). Orchestrates LDD's four loops — inner (code), refinement (deliverable), outer (method), CoT (reasoning chain, v0.8.0) — with hard iteration budgets, dispatches the specialist skills at the right moments, and forbids declaring "done" without a synced doc-level mental model.

Use when deciding whether to edit code at all, how large the edit should be, or whether a "working" fix actually generalizes. Applies when iterating on a failing test/run, chasing a flake, committing a sequence of small patches, or tempted to ship on one data point. Frames code changes as gradient steps and forbids overfitting to a single sample or a single test.

Use when a reasoning task requires a multi-step Chain-of-Thought (CoT) AND the task is verifiable (grounded answer, testable code, derivable proof). Forbids greedy step-by-step commitment — every step in the chain goes through thesis/antithesis/synthesis BEFORE entering the chain, using memory-primed antitheses to attack the proposed step. Produces a calibrated predicted-correctness per step and per chain. Applies SGD-on-thoughts in the same way `dialectical-reasoning` applies SGD-on-actions.

Use when making any non-trivial recommendation, analysis, plan, design decision, code-review note, or architectural trade-off — before presenting to the user or acting. Forces a thesis / antithesis / synthesis pass so first-pass conclusions cannot ship without surviving their strongest counter-case.

Use at the start of every inner-loop iteration where the goal is to fix a bug / close a failing test / reach a green E2E. Forbids editing code without first running the E2E to capture a fresh loss signal, and forbids declaring "done" without the E2E passing. Makes the cycle "E2E → loss → 5-why-by-layer → fix → E2E" the only admissible rhythm.

Use when finishing any code change that modifies behavior, public API, CLI flags, config shape, defaults, error messages, or anything a reader-of-the-docs would model — before committing, pushing, or declaring "done." Forbids deferring doc updates to a follow-up commit, ticket, or "cleanup later."

Use periodically (weekly, at release candidates, before major version bumps) to scan a codebase for cumulative drift that no per-commit gate catches. Complements docs-as-definition-of-done, which prevents drift from being introduced per commit; this skill surfaces drift that already happened despite per-commit gates.

Use when a deliverable (document, diff, design, report, code module) is complete but "good enough, not great" and you want to improve it with a targeted re-iteration instead of starting over. Forbids re-running the task from scratch when refinement is more efficient. Operates on the y-axis (output) not the θ-axis (code or method).

Use when the same rubric violation, the same kind of symptom-patch, or the same escalation happens across 3+ distinct tasks — meaning the problem is in the method (skill, prompt, rubric), not in the tasks. Forces a disciplined outer-loop step: name the pattern, propose a skill/rubric change, measure Δloss before and after, roll back on regression.

Use when you have observed a failing test, a flaky run, a surprising log line, or any single-sample signal you are about to treat as a gradient. Forbids code edits based on one observation unless the log itself is unambiguous signal. Applies before invoking root-cause-by-layer or proposing any fix.

Use when encountering a bug, failing test, or unexpected behavior — especially under time pressure where try/except, retry loops, xfail, type-tolerance shims, "I'll clean up later," or compat-for-both-shapes feel like the fastest path. Forbids symptom patches until structural and conceptual origins are named.