The nine skills of the method.

What it is. The human brings the idea, constraints, and reference material; the skill brings the shape: it questions until there is a shared shape for the system and writes the documents as it goes — it does not ask the human to design the system for it.

When. "discovery", "model this from an idea", "I only have the idea; I do not know how yet." When NOT to use it: a clearly shaped feature → uscha-adr-refine; an existing system to migrate → uscha-reverse-discovery.

Non-negotiable principles

• One question at a time, each with a recommended answer. The inversion that makes discovery work: the skill proposes (entities, endpoints, architecture, a default); the human confirms or corrects. Never a list of 20 questions.
• Explore before asking. If a reference document, the codebase, or a CONTEXT.md/docs/adr/ answers the question, read it first.
• Propose the shape. Core entities, the operations surface, and 2–3 architecture options with trade-offs; walk the design tree one branch at a time.
• Question, do not agree. Look for contradictions, vague terms, and missing failure modes. A discovery where the skill agreed with everything has failed.
• Lazy, inline files. Create a file only when there is something real to write; update it when the decision crystallizes — never batch them at the end.

Questioning agenda (in order; skip what the references already answer)

1. Purpose / value / why now — what work it eliminates and the cost of not doing it.
2. Domain model — the skill proposes core entities and relationships.
3. Operations surface / API — endpoints, contracts, idempotency, status codes.
4. Major decisions (→ ADR) — 2–3 options with trade-offs and a recommended default.
5. Behavior and messy cases — the happy path and THEN failures, retries, partial states, concurrency, and what must NOT happen.
6. Inviolable constraints (→ CONSTITUTION.md) — one invariant per line, mapping to a CWE where applicable; they feed the severity gate, and a violation is a BLOCKER, never a trade-off.
7. Out of scope — explicit boundaries with forward references.
8. Acceptance / DoD — concrete, checkable criteria + metrics.
9. Quality bar (→ config, 1.17.0) — "what quality level is ENOUGH and what is negotiable?" What is declared goes in uscha.config.json and reads as requirement (config); what is not declared remains the kit default (opinion) and is labelled that way. Declaring it means committing the config.
10. Risks and dependencies — for each HIGH-uncertainty risk (1.19.0): "does this warrant a time-boxed spike?" The spike runs on a spike/* branch, and its only legitimate output is an ADR with lessons learned — phase --require pr-ready rejects that branch, in the spirit of INV-GOLDEN-01.

Artifacts (lazy, as they crystallize)

What it is. The same interview applied to a KNOWN feature: the shape is already clear; it needs precision. It is not a generator: it is a questioner that distills. The value is in the questions, not in agreement. It is the front half of uscha-devloop.

When. "refine the ADR", "let's spec this before coding", "help me define this before development."

Non-negotiable principles

• Question, do not validateste — surface implicit assumptions and find the gaps.
• Converge, do not merely run out of questions — the interview ends by an OBJECTIVE criterion, not when the human seems tired. The same "converge, don't chase zero" discipline from uscha-devloop, at the front.
• No artifacts before convergence — when asked to "write it now," name the open gaps first.
• One topic at a time — focused batches, reflecting "Decided: … / Still open: …" before moving on.
• "You decide" is recorded — when consequential decisions are deferred, state the trade-off ONCE; if they insist, record it as an explicit ADR assumption, never a silent default.

Phase A — the interview (agenda)

1. Problem and why now — if "why now" has no answer, the priority is suspect.
2. Implicit decisions — sync/async, storage, protocol, idempotency, transactional boundaries, and state ownership; each with a considered alternative.
3. Behavior — the happy path, then the MESSY cases: timeouts, retries and backoff, 4xx vs 5xx, concurrency, and partial/terminal states. A feature without failure behavior is only half specified.
4. Inviolable constraints (→ CONSTITUTION.md) — an ADR must never contradict the CONSTITUTION: if a decision would do so, escalate it; do not record it.
5. Out of scope — what you exclude is as important as what you include.
6. DoD + success metrics — every item verifiable, not a feeling.
7. Dependencies — which specs/systems/credentials must exist first.

Phase B — distill (only after convergence)

• A ADR per decision worth recording, fixed format: Status · Context (options A/B/C) · Decision · Reasons · Consequences (+/−) · Implementation Plan · Verification. Numbering continues from the highest ADR. Negative decisions count: "what we will NOT use and why" is a valid ADR.
• ACCEPTANCE.md at the root (or the configured path): Definition of done · How we measure success · Out of scope · Recorded decisions. It is the file readiness measures.
• If a new invariant emerged, it goes in CONSTITUTION.md — never leave it in an ADR where it could later be "negotiated."

Explicit anti-patterns

• Generate an ADR from a one-line request without interviewing.
• Accept "do it however you want" without recording the assumption.
• Write an uncheckable criterion ("it works well").
• Emit artifacts before the conditions of convergence.

What it is. A disciplined development + QA cycle across one or more repositories, with every step recorded in a deterministic ledger (QA-LEDGER.json) and a hard stop at the human merge gate. Every metric comes from the ledger — never estimate from memory. Two levels: measured records (snapshots, ingest-gate, log-gate — parsed from real artifacts; able to block) and self-reported counts (log-step — narrative for the retrospective). A measured red always overrides a narrated green.

Who it is for / when NOT to use it. An operator driving ONE non-trivial change with risk. NOT for trivial work — a fix of a file runs build+test and it skips discovery/ADR/uscha-sysdoc (profile table in the playbook).

Non-negotiable principles

• Converge; do not chase zero. Only findings ≥ severity gate (default BLOCKER/CRITICAL/HIGH) block; the rest go to ISSUES-DEFERRED.md. Endlessly polishing Medium/Low findings is the failure mode this skill prevents.
• Tests are a guardrail, not the finish line. The test command runs after EVERY pass that changed code; a red suite stops the loop.
• Generating tests is not running tests. /improve test runs ONCE at the end against stabilized code — never inside the loop.
• Stop at the merge. The skill creates the PR and confirms CI; it does NOT merge.
• Tracked Markdown — request the current version before modifying it.
• The golden is not agent-authored. .approved = field truth approved by a HUMAN; the skill emits .received and stops (hook PreToolUse — INV-GOLDEN-01).

The phases

1. Setup — init --config uscha.config.json; each repository with its type (maven·flutter·python·node·go·rust·dotnet·cpp·gradle·swift). Profile E: also install the golden hook + .gitattributes.
2. Phase 0 — Plan (ADR-first). CONSTITUTION.md is read FIRST. Input: ADR set + ACCEPTANCE.md. Without acceptance criteria → stop and run adr-refine. The loop targets the plan, not "zero issues."
3. Phase 1 — Coverage gate → conditional characterization. snapshot --phase pre + check-coverage. Below the threshold → contract tests AT THE BOUNDARY (not internals), reviewed by the human. Migration → golden BEFORE touching anything; without an approved golden there is no build.
4. Phase 2 — Build. Conventional commits for each logical step. ADR discipline: consult before touching a governed area; proactively trigger new ADRs; link code↔ADR; never edit the SPEC/ADR to make the implementation look correct.
5. Phase 2b — Simplicity gate ("Reduce"). simplicity-check on the diff; OVERBUILT (exit 1) is BLOCKER: trim and rerun. Tests remain OUTSIDE the budget (1.11.0). Persist it with log-gate --kind simplicity.
6. Phase 2c — Waste gate ("Reuse-first", 1.26.0). waste-check: deterministic detection of Type-1/2 clones between the diff and the REPOSITORY — the duplication that simplicity-check cannot see (it scores the diff in isolation). Each flag names the file:line to reuse. Advisory by default; gates only with --gate or defaults.waste.gate. Basis: Lean muda (Poppendieck) + the 81% increase in duplication measured by GitClear.
7. Phase 3 — QA loop (per repository). Tools in qa_tools_order (code-review → judgment-day → improve); one pass through all tools is one cycle. After each pass: fixes ≥ gate, tests, log-step. In each pass that changed code: gate-check (did it weaken the safeguards? add a secret? — 1.12.0) and golden-diff for migrations, persisted with log-gate. Find Bugs Once (1.16.0): with --fixed > 0, run regression-check — closing without a new test line = NARRATED (the failing test comes BEFORE the fix). Ingest the static gate with ingest-gate (normalized severities, fixed measured from the ID diff). Cycle close: converged + oscillation.
8. Phase 4 — Integration. The cross-repository layer with every repository mounted, logged under --repo integration. Green repositories do not imply green seams.
9. Phase 5 — Verify. Only now record final coverage; require the full suite to be green, snapshot --phase post.
10. Phase 5b — Rebuild test (optional, profile C+/E). Is the SPEC sufficient to regenerate the system? A previously passing test that fails against the regenerated system exposes behavior the SPEC left implicit. The divergence is a spec gap, not a code bug.
11. Phase 6 — PR. phase --require pr-ready PER REPOSITORY before opening it: status is COMPUTED from the ledger, never declared; exit 1 lists the missing facts. A spike/* never passes (1.19.0). PR, CI green, STOP — the human merges.
12. Phase 7 — Smoke list. A concrete manual checklist (real routes, endpoints, and device flows).
13. Phase 8 — Docs + retrospective. summary (+ --json for sys-doc; includes the first-time yield (FTY, 1.27.0): % of repositories that passed QA in the first cycle, without rework or escalation — an informative Lean metric that never gates) and the readiness KPI after EVERY task: acceptance MEASURED 30 · static 20 · adr 15 · coverage 15 · convergence 10 · integration 10; hard caps with labelled provenance (1.17.0); traceability AC-n (1.10.0); advisories stall / stop-signal (1.14.0). Single verdict (anti-ceremony, 1.25.0): by default the readiness is ONE screen — the verdict + one line --- gates: collapsed; --verbose expands dimensions and per-repository detail. A meta-invariant in the CONSTITUTION governs that future gates remain quiet by default and collapse into readiness.

What it is. Captures the golden/approval suite for a module's CURRENT behavior — the only loop artifact the agent cannot author — precisely why it exists. If the agent wrote the golden by reasoning about what the code "should" return, it would encode the same partial reading that silently loses logic. Capture what the code DOES, mechanically, by running it.

When. "characterize", "golden-capture", "capture the old behavior" — before any migration. uscha-devloop triggers it in Phase 1 (profile E); uscha-reverse-discovery orchestrates it as Phase 2.

Division of authorship: the agent CAN write the harness of captures; it CANNOT create, rename, or edit any .approved.

Protocol

1. Capture harness (written by the agent): deterministic; runs the ORIGINAL module against the corpus and serializes ALL observable output. Same input → same .received, byte a byte.
2. Non-determinism checklist (issued as applied): frozen timestamps · fixed seeds · sorted maps/sets · normalized GUIDs/auto-increment values · concurrency with deterministic ordering · explicit, mandatory target locale (a golden created on a machine with another locale can break completely; Windows/SQL Server: risk high) · deterministic serialization (sorted keys, fixed float precision, explicit encoding).
3. Run the captures → .received. Declare volatile fields BEFORE approval (1.15.0): anything that varies across correct runs and cannot be made deterministic at the source is declared in golden.scrub.json; golden-diff masks BOTH sides (text only) and reports every scrub match SEPARATELY — masking is never invisible. gate-check flags every later edit to the file.
4. STOP for human approval. The human reviews and approves the .approved — and golden.scrub.json if exists (the scrub rules are contractual). The skill ends here.

Harness stack: Java → ApprovalTests.Java (JUnit 5, JsonApprovals.verifyAsJson()); C++/other → fixture directory + deterministic serializer + runner custom. Relationship: the .approved captured is the arbiter that golden-diff compares byte for byte during uscha-devloop.

What it is. The inverso of discovery: the system already runs and its behavior observable IS the verdad. It invents nothing — it characterizes what already exists as facts.

When. "reverse-discovery", "migrate/modernize this system", "characterize the old system before touching it".

Protocol

1. Map (fact). Only static analysis → SYSTEM-MAP.md: each endpoint/operation/topic public with its contract · dependency graph (cycles and hubs flagged) · module candidates (an observation of the CURRENT layout, NOT a proposal for the new one). Everything traceable to code; no "this seems to…".
2. Characterize (fact). The golden in the boundaries, delegating to the skill uscha-characterize (or following its contract inline if it is not installed). Insufficient corpus = PARTIAL.
3. Summary (facts, without opinion). DISCOVERY-SUMMARY.md: the map + the coverage report of the golden (what boundaries are approved, which PARTIAL and why). The base of facts that the human reads for write the migration SPEC. No editorializing.

What it does NOT do (work of the human)

• Write the SPEC of the old behavior — the golden IS the executable spec.
• Write ADRs of the implicit decisions in the old system.
• Decide the NEW structure (module boundaries, shared kernel, sync vs events) — decisions forward → adr-refine.

Complete migration flow: reverse-discovery (facts) → the human writes the SPEC + uscha-adr-refine (forward partitioning decisions) → uscha-devloop (restructures with golden-diff green throughout) → readiness + human gate.

What it is. Generates ONE .html self-contained, navigable file (PowerPoint-style keyboard + click controls) that documents a system through two switchable tracks: business/CEO (what does, value, risk posture, status — without code, framed in money/time/reliability) and technical (architecture, modules, contracts, QA, coverage, deferred).

When. "document this system", "make the system deck" — on request from uscha-devloop Phase 8 (is a report, not part of the verified build).

Structure (10 slides)

1. Title — system, purpose in one line, date, run id.
2. Track switcher — Business ⇄ Technical (default Business).
3. [C] What does — plain language, the work it eliminates.
4. [C] Value and status — facts, work in flight, risk posture.
5. [C] Quality of a glance — coverage, tests, resolved issues. No jargon.
6. [T] Architecture — SVG inline: repos as boxes, flow as arrows, external systems distinguished.
7. [T] Contracts / interfaces — the seams between repositories/modules.
8. [T] Results QA — table by tool (reported/fixed/%fixed/deferred/suppressed), coverage by repo, tests/kLOC, escalations.
9. [T] Deferred issues — summary HONEST of ISSUES-DEFERRED.md.
10. Smoke checklist — the manual verification steps.

Constraints of build

• A single .html with all inline — works from disk and is deployable as-is.
• Without localStorage/sessionStorage (sandboxes) — navigation state in JS variables.
• Navigation: arrows, prev/next, index of dots, Esc = grid overview, counter visible.
• Hand-built SVG diagrams with currentColor/variables CSS — no raster images or external libraries.
• Dark control-room, clean business track; accessible (semantic headings, aria-labels, AA contrast, printable).

Output: docs/system-deck.html (or the path chosen by the human); present the path and the first 2–3 things to inspect — do not paste the HTML into chat.

What it is. Scores the change against RUBRIC.md — VERSIONED qualitative criteria (conventions, API ergonomics, soundness of the error handling, quality of docs) with weights, anchors, negative criteria and threshold. The skill is a THIN Claude Code adapter: the core is agnostic — the neutral prompt (templates/rubric-grader-prompt.md, runs in Codex/Gemini CLI/Cursor/curl/ a human) + the JSON contract that rubric-ingest validates (kit 1.23.0).

When. "grade the rubric", "evaluate the rubric" — and uscha-devloop it runs in Phase 3b when a rubric exists.

Protocol

1. Validate structure first (facts block): spec-check --rubric RUBRIC.md — zero criteria, duplicate IDs, or an invalid threshold = exit 1.
2. Grade with ISOLATED context: read ONLY diff + rubric (never the reasoning of the maker); when in doubt, fail — optimistic bias is the failure mode this layer counters.
3. Evidence-or-nothing: every verdict affecting the score cites file:line or the engine discards it as unsupported.
4. Ingest: rubric-ingest --repo X --report reports/rubric-grade.json — weighted score vs threshold, persists rubric:grade in the ledger.

What it is. A self-contained, read-only status view: readiness, subscores, the phase path, invariants, QA loops, and a time-lapse. The skill wires; it does not calculate. Every number comes from the ledger.

When. "mirador", "status view", "bird's-eye", "project dashboard". Without QA-LEDGER.json, there is no state to display: warn and stop.

Non-negotiable contract

• Truth-pass. qa_ledger.py dashboard --json aggregates only existing state. A missing source produces null/[]; the template degrades and never invents data.
• Data separation. Execution policy is routing metadata, not a score. Optional telemetry is vendor-reported and lives in a separate strip; it never enters readiness.
• Read-only. It runs no gates and never modifies the ledger. readiness --record belongs to the loop, not this skill.
• Generated artifact. It replaces only the block between /*MIRADOR_DATA_START*/ and /*MIRADOR_DATA_END*/ in the template and writes mirador.html.

Flow

1. Resolve the engine and ledger. Use the first valid qa_ledger.py installation and the specified QA-LEDGER.json.
2. Render. mirador-render.py runs dashboard --json, merges sidecar telemetry when present, and injects const DATA into the template.
3. Open best-effort. Try to open mirador.html for the current platform, never fail in headless/CI, and always print the absolute path.
4. Optional second-screen view. mirador-watch.ps1/mirador-watch.sh re-renders every N seconds; the page refreshes without a server and changes only at measured checkpoints.

What it is. A one-line progress readout, rendered in chat, for surfaces where the statusline is not visible (Claude Desktop, Codex, plain terminals, CI logs). It reads the same MEASURED facts the statusline reads — derived phase, loop odometer, acceptance bar, tests, next criterion — and prints them in a compact block.

When. "uscha status", "/uscha-status", "where are we", "progress". Three zoom levels, each datum once: the push is the readiness line at every pass close (already exists); this is the pull; the mirador is the bird's-eye view.

Non-negotiable contract

• Read-only. It never runs readiness, tests, or gates. It renders already-persisted evidence (ledger["measured"], refreshed by uscha_progress.py) or honestly says there is none.
• Measured beats narrated. With no recorded measurement and only ACCEPTANCE checkboxes, it may show the count but labeled narrated, never passed off as measured.
• Truth-pass. A datum with no source shrinks the block; it never becomes "n/a" noise or an invented number.

Flow

1. Source, in order. Run uscha_progress.py if present (fast: parses JSON + one .md, never runs tests) and read .claude/uscha-progress.json; else read QA-LEDGER.json measured directly; no uscha.config.json means it is not a uscha project, and it says so.
2. One compact block. Label · derived phase ×loops · measured acceptance bar · tests · coverage · next → · per-repo odometer (multi-repo, with plateau ⚠) · roadmap · recorded with the timestamp and score/band of the last measurement.