Andres Massello Uscha · one page · v1.10.0

Uscha, distilled.

Uscha is a spec-driven, tool-agnostic methodology for development with LLM coding agents. Down-to-earth AI-assisted development: the AI executes, the human governs, the evidence decides. No ceremony where it isn't earned, rigor where the stakes justify it (critical paths, migrations).

The rule that orders everything: gates that read FACTS block; those that GUESS over prose advise.

The loop

exit 1 · trim / fix SPEC + ACCEPTANCE /uscha-discovery dev-loop build + tests gates inline · log-gate human gate reads the diff · ALWAYS ship inside the gates: BLOCK · read FACTS golden-diff pit-check gate-check rebuild (COVERS) simplicity caps exit 1 · break the chain · objective, cheap ADVISE · guess over PROSE spec-check prose abstractions Heuristics over natural language: if it blocks, it fires false positives → the dev turns it off → dead gate. report, don't block (--strict to gate)
fact → blocks prose → advises path to production exit 1 returns to dev-loop

The 5 rules (the spine)

  1. No code without SPEC + ACCEPTANCE. If it's a vague idea, model it first — don't code it.
  2. The truth lives in files, not in the chat. SPEC/ADR/CONSTITUTION are read before touching code.
  3. The human approves the merge. Never auto-merge. Merge, deploy, schema, permissions, prod-config: always human, regardless of the agent's confidence.
  4. Tests ASSERT and the gate is not weakened. Coverage lies (mutation testing measures it); deleting tests or lowering/deleting thresholds = BLOCKER.
  5. Migrations: golden before touching. The old behavior is captured mechanically; the agent does not author the arbiter that judges it.

The gates: facts vs prose

GateWhat it reads
golden-diffbyte-comparison .received vs .approved; exit 0 CLEAN / 1 DIVERGE / 2 NOT-RUN (zero fixtures = NOT-RUN, never CLEAN)BLOCKS
pit-checkPIT XML (mutation testing = do the tests assert?) — scheduled/incremental tier, not inner-loop; a failing report is persisted via log-gateBLOCKS
gate-checkdiff structure (removed tests incl. whole-file deletions, disabled tests, lowered or deleted thresholds); suppressions, rewritten asserts & measured test-count drop = soft REVIEW (--strict gates)BLOCKS
rebuildCOVERS/DIVERGE; the one that exits 1 unless COVERSBLOCKS
readiness0-100 KPI, always exit 0; hard caps (tests red ≤35, BLOCKER/CRITICAL ≤65, unresolved escalation ≤75)REPORTS
simplicity-checknumeric budgets (+lines 400, net growth, files, nesting depth, largest hunk); a dim >1.5× budget floors OVERBUILTBLOCKS
simplicity · abstractionsabstraction count/density — deliberately unweighted (false positives on records/DTOs)ADVISES
spec-check · structuremissing out-of-scope section, absent/empty acceptance criteria — facts, exit 1BLOCKS
spec-check · proseheuristics over SPEC prose (vague terms, EARS, stack naming); --strict gates themADVISES

Block — read facts

Hard exit 1, break the chain. Objective, cheap, no opinion. The agent runs them inline in /uscha-devloop and persists each verdict with log-gate; a failing fact gate blocks convergence and caps readiness ≤65.

  • golden-diff · pit-check · gate-check
  • rebuild · simplicity budgets · spec-check structure

Advise — guess over prose

They report, they don't block (except --strict). A heuristic over natural language that blocks generates false positives → the dev disables it → dead gate.

  • spec-check prose (advisory)
  • simplicity abstractions

The developer's day-to-day

# the agent runs the fact gates INLINE in /uscha-devloop and persists them with log-gate
spec → code (agent) → /uscha-devloop gates inline:
   golden-diff · pit-check · gate-check · simplicity  # exit 0/1 → qa_ledger.py log-gate
→ readiness = 0-100 KPI (hard caps, always exit 0) → converge → STOP at the merge gate
→ the human READS the diff → ship
# spec-check prose and abstractions run as advisory: they inform, they don't block

Consistency is inferential, not a lint

What a regex can't judge (contradictory clauses? over-architected?) is NOT faked as deterministic: it goes to the non-correlated checker (a different agent family, or at least a different profile — process discipline, not enforced by code). Computational within the file; inferential cross-file.

Appendix: the full detail — history, sensors (Böckeler), anti gate-gaming (Osmani), golden testing, glossary and references — is in the long doc: uscha-claude-code-doc-EN.html. · Install: npx --yes @andresmassello/uscha@latest install · then npx … init in the repo (kit 1.50.0). · Governance: the AI executes, the methodology governs, the evidence decides, the human approves.