Measured development with LLM coding agents
Day 1 — Foundations + Discovery (new project)
Day 2 — Reverse-Discovery + Migration + Adoption (existing system)
Instructor: Andrés Massello · uscha.dev
Most teams using coding agents still operate in an open loop:
Human: "Check the QA errors."
The agent diagnosed, edited tests and production code in the same turn, ran the build and declared "design closed" — with zero human decision points.
The execution was competent.
The governance failed.
That is exactly the hole uscha closes.
"Gates that read FACTS block.
Those that GUESS over prose advise."
Central mechanism: a deterministic ledger that separates
what was measured from what was narrated.
Non-negotiable. Everything else derives from these.
The agent is not allowed to invent the definition of "done".
What and why. Constraints, non-goals, interfaces.
Concrete, testable criteria for "done".
If it is not in the repository, the method does not treat it as true.
The pipeline stops at the merge gate. No exceptions. The agent prepares and measures; the human decides.
A test that asserts nothing is not a test. The gate is never weakened so the agent can pass.
Current behavior is captured mechanically before changing anything. The agent never authors .approved files.
SPEC.md · ACCEPTANCE.mdADR/ — decisionsRUBRIC.mdA deterministic record of measurements, never of claims. Zero runtime dependencies. 11 language stacks.
The chat is ephemeral. The ledger is the source of truth.
Loops exist but are bounded. They escalate when they cannot converge.
Turns a vague idea into a complete, versioned SPEC + ACCEPTANCE package through structured interrogation.
A small, realistic service in a retail/payments context.
Starting point (vague idea):
"We need something that decides whether a refund is allowed based on purchase date, product category and customer tier."
We will walk the full measured trail from this idea to the first gated implementation.
Invoke /uscha-discovery with the vague idea.
The agent interrogates: time windows? categories? tier rules? edge cases? non-goals?
The human answers (or corrects).
The agent writes SPEC.md + ACCEPTANCE.md into the repository.
The human reviews and approves the package before any code.
No code has been written yet. The definition of "done" is already closed.
# Refund Policy Engine
Goal: Decide refund eligibility for a completed order.
Inputs: order_id, request_timestamp
Rules (initial):
- Standard: ≤ 30 days from purchase
- Premium tier: ≤ 60 days
- "Digital" category: never refundable after download
Non-goals: payment execution, inventory restock, UI
Constraints: pure decision function, deterministic, no side effects
1. Given a standard customer with a 15-day-old order → eligible = true
2. Given a standard customer with a 35-day-old order → eligible = false
3. Given a premium customer with a 45-day-old order → eligible = true
4. Given any Digital-category order after the download flag → eligible = false
5. The function is pure: same inputs always produce the same output
6. Every acceptance case is expressed as an automated test that asserts
These become the ledger's first real gates.
The agent can never close the story alone. Evidence + a human are required.
We turned a vague idea into versioned SPEC + ACCEPTANCE,
then ran the first measured development loop
that cannot close without evidence and human approval.
Tomorrow: the same rigor applied to existing systems.
Measured gates applied to systems that already exist
and already matter.
Freezes current behavior as a golden suite before any modification.
.received)The skill emits .received and STOPS. The agent is forbidden from authoring .approved files — only the human promotes the golden.
Extracts facts from an existing system when documentation is missing, stale or wrong.
Starting reality:
An existing module used in production for years. Sparse tests. Business rules live partly in code comments and tribal knowledge. The team wants to let coding agents improve it safely.
We will characterize → reverse-discover → add a measured improvement → keep the golden intact.
Select the module (or a critical set of functions).
Run /uscha-characterize.
The golden suite is generated from observed behavior (.received).
The human reviews and promotes the golden (or adjusts the inputs).
From this moment on, any deviation from the golden becomes visible evidence in the ledger.
Now we extract the real rules the code implements.
Observed facts (example):
- 10% discount if cart > $100
- Extra 5% if the customer is "gold"
- Digital products never receive the cart-value discount
- The discount is applied before tax
- Rounding: banker's rounding to 2 decimals
With these facts, the human writes the new SPEC if we decide to evolve the module.
.approved filesThis is how you let agents touch production systems without losing control.
Culture change > tool installation.
/uscha-characterize → produce the .received and promote the golden/uscha-reverse-discovery → extract the real rules/uscha-devloopnpx --yes @andresmassello/uscha@latest install --target claude
Measured beats narrated.
Facts block. Guesses advise.
Humans approve.
Day 1 — Discovery turned an idea into measured gates.
Day 2 — Reverse-discovery + characterization let us evolve existing systems without losing control.
Andrés Massello · uscha.dev · info@uscha.dev
Questions and discussion