uscha.dev
how it works

Three flows, one rule: the human judges, the engine measures

uscha has a front for new systems and a front for existing ones. Both end at the same place — a human verdict the engine can check. These three diagrams show the greenfield flow, the brownfield flow, and the curation mechanism (kit 1.64–1.65) where a single human decision is the only judgment in the loop.

1 · greenfield

Discovery — you bring the idea, the method proposes the shape

The skill explores first, then asks one question at a time — each with a recommended answer. You confirm or correct; you never author the shape from a blank page. The package is written to the repo as decisions crystallize.

until it converges Idea + reference material optional: docs, URLs, existing code Explore before asking read refs & code first Propose the shape one question at a time, each with a recommended answer HUMAN DECISION Confirm or correct ARTIFACTS · IN THE REPO SPEC · ADRs · ACCEPTANCE CONTEXT · DOMAIN-MODEL · RISKS → /uscha-devloop build + measured QA loop
artifact human decision skill / engine step
2 · brownfield

Reverse Discovery — extract facts, then quarantine the claims

The running system's behavior is the truth. The skill extracts facts (map, golden), then authors candidates in quarantine — never specs. The old rule "never author an inferred spec" was renegotiated in ADR-009: you may author candidates, you may never promote them without a verdict.

re-check until 0 Existing system observable behavior = ground truth Map — facts SYSTEM-MAP · boundaries · deps HUMAN APPROVES · INV-GOLDEN-01 Characterize → golden .received → STOP → .approved CANDIDATES · QUARANTINE discovery/*.md · evidence + confidence MEASURED GATE · subcmd 34 curation-check exit 2 malformed · 1 unjudged · 0 ok HUMAN VERDICT preserve · fix · undefined one candidate at a time BEHAVIOR-LEDGER.md + ADR append-only, git-verified Summary → human writes SPEC from JUDGED candidates only
artifact measured gate human decision skill step
3 · the new · 1.64–1.65

Curation — one human verdict, everything else measured

This is the differentiator. A candidate is machine-validated; a candidate with no verdict blocks the PR, naming itself (INV-CURATION-01). The single human decision splits into three buckets. A fix declares its expected divergence, which the golden oracle then checks. roundtrip reports traceability by id — advisory, never a gate.

CANDIDATE · discovery/*.md evidence.type · refs · confidence MEASURED validate frontmatter + refs refs resolve · confined to repo · inference⇒low GATE · subcmd 34 curation-check no verdict → blocks pr-ready, naming the candidate THE ONLY HUMAN DECISION IN THE LOOP HUMAN VERDICT preserve  ·  fix  ·  undefined preserve promote as-is fix promote + declared divergence undefined excluded ORACLE · golden-diff golden.divergences.json declared+diverges=ok · declared+identical=RED roundtrip (subcmd 35) · advisory · traceable by id · exit 0 always
candidate / artifact measured gate the human verdict advisory

Every node above maps to a real subcommand or invariant in qa_ledger.py (kit 1.65.0). What is deliberately not here: semantic matching and code generation — both out of scope (ADR-011) until they can be measured.

Take the course → Read the paper → ← Back to home