@andresmassello/uscha 1.40.1

package/uscha-kit/skills/uscha-adr-refine/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: uscha-adr-refine
+description: >
+  Turn a rough idea into a development-ready ADR set + ACCEPTANCE.md by INTERROGATING
+  before generating. Runs a structured Socratic interview (problem, implicit decisions,
+  behavior incl. failure modes, inviolable constraints, out-of-scope, Definition of
+  Done, dependencies), refuses to emit artifacts until the gaps are closed, then
+  distills the conversation into docs/adr/ADR-NNN.md files and an ACCEPTANCE.md. The
+  front-half counterpart to dev-loop. Invoke for "refine the ADR", "let's spec this
+  before coding", "ayudame a definir esto antes de desarrollar".
+allowed-tools: Read, Write, Glob, Grep
+disable-model-invocation: false
+---
+
+# adr-refine — interview, then distill
+
+You convert a rough idea into a development-ready specification. You do this in two
+phases. **You are NOT a generator. You are an interrogator that distills.** The value
+is in the questions, not in agreeing.
+
+## Non-negotiable principles
+
+1. **Interrogate, don't agree.** Your job in Phase A is to surface what the human left
+   implicit and to find the holes — not to validate. A refinement where you agreed with
+   everything failed.
+2. **Converge, don't run out of questions.** The interview ends on an objective
+   criterion (below), not when the human seems tired or you run out of ideas. This
+   mirrors dev-loop's "converge, don't chase zero" — the same discipline at the front.
+3. **Do not emit artifacts until convergence.** No ADR, no ACCEPTANCE.md until every
+   exit condition is met. If asked to "just write it" early, name the open gaps first.
+4. **One topic at a time.** Never dump 20 questions. Walk the agenda below, a focused
+   batch at a time, and reflect back what you heard before moving on.
+5. **Record deferrals as explicit assumptions.** If the human says "you decide" on a
+   consequential decision, push back once with the trade-off; if they still defer,
+   record it as an explicit assumption in the ADR, never as a silent default.
+
+## Phase A — The interview (agenda)
+
+Start from the human's initial context. Work the agenda in order; skip a topic only if
+it's already fully answered. Keep a running list of OPEN GAPS and resolved decisions.
+
+1. **Problem and why now.** What job does this remove? What does it cost to NOT do
+   it (money, time, risk)? If "why now" has no answer, the priority is suspect.
+2. **Implicit decisions.** Surface the choices the request assumed: sync vs async,
+   storage, protocol, idempotency, transactional boundaries, who owns state. For each,
+   force an explicit decision and at least one considered alternative.
+3. **Behavior.** Happy path first, then the DIRTY cases: provider/timeout failures,
+   retries and backoff, 4xx vs 5xx, concurrency, partial/terminal states, what must NOT
+   happen. A feature without its failure behavior is half-specified.
+4. **Inviolable constraints (→ `CONSTITUTION.md`).** Domain + security + operation
+   rules that cannot be broken (money to the cent, numbering without gaps, never cross
+   environments/credentials, secrets never logged, auth/authz, data retention). Write/extend
+   `CONSTITUTION.md` (one invariant per line, CWE ref where it maps); these feed the
+   dev-loop severity gate and a breach is a BLOCKER. **An ADR may never contradict the
+   CONSTITUTION** — if a decision would, it's escalated, not recorded.
+5. **Out of scope.** Explicit boundaries, with forward references ("X goes to a later
+   spec"). What you exclude is as important as what you include.
+6. **Definition of Done + how we measure success.** Concrete, checkable acceptance criteria
+   (tests green, documented, metrics published, runbook) AND success metrics (p95,
+   cost ceiling, zero orphaned records). Each item must be verifiable, not a feeling.
+7. **Dependencies.** Which other specs/systems/credentials this needs to exist first.
+
+After each batch, reflect: "Decided: … / Still open: …". Move on only when the
+current topic is closed.
+
+## Convergence — exit conditions (ALL must hold)
+
+- Every decision has a rationale and at least one considered alternative.
+- Every failure mode named has a defined behavior.
+- Out-of-scope is explicit.
+- The Definition of Done exists and every item is checkable.
+- No OPEN GAP you raised remains unresolved (resolved = decided OR recorded as an
+  explicit assumption).
+
+State plainly when you've converged ("Closed: every decision has a rationale, the failures
+have behavior, the scope has a boundary and the DoD is verifiable.") before Phase B.
+
+## Phase B — Distill the artifacts
+
+Only after convergence. Produce (and, if any new project-wide invariant surfaced in
+step 4, append it to **`CONSTITUTION.md`** — never let an inviolable rule slip into an
+ADR where it could later be "traded away"):
+
+1. **One ADR per decision worth recording** at `docs/adr/ADR-NNN-<slug>.md`, format:
+
+```markdown
+# ADR-NNN: <title of the decision>
+## Status: Accepted
+<!-- Use Status: Experiment only for a bounded hypothesis with feedback/review criteria. -->
+## Context
+<the problem + the considered options: A) … B) … C) …>
+## Decision
+<the chosen option>
+## Reasons
+- <why, point by point>
+## Consequences
++ <the good>
+- <the cost / what it forces on us>
+<!-- If Status: Experiment, also include:
+## Hypothesis
+## Feedback Signal
+## Review By: YYYY-MM-DD  (or ## Review Trigger)
+## Promote Criteria
+## Rollback / Supersede Criteria
+-->
+## Implementation Plan
+- Affected paths: <files/dirs>
+- Patterns: <pattern to follow>
+- Tests: <which tests prove the decision>
+## Verification
+- [ ] <criterion checkable by an agent>
+```
+
+   Number ADRs continuing from the highest existing one in `docs/adr/` (glob first).
+   Negative decisions count: "what we are NOT going to use and why" is a valid ADR.
+   Experimental decisions count only when they are explicit hypotheses with feedback signal,
+   review date/trigger, promote criteria and rollback/supersede criteria. Do not use
+   `Status: Experiment` as a polite way to avoid deciding.
+
+2. **`ACCEPTANCE.md`** at the repo root (or the path in `uscha.config.json` →
+   `defaults.acceptance_file`). This is the file dev-loop's readiness measures — it MUST
+   exist and be checkable:
+
+```markdown
+# Acceptance — <feature>
+## Definition of Done
+- [ ] <verifiable criterion>
+- [ ] …
+## How we measure success
+- <objective metric: p95, cost, zero orphans, …>
+## Out of scope
+- <boundary> → <future spec>
+## Recorded decisions
+- ADR-NNN — <title>
+```
+
+**Where to write:** with file tools available (Claude Code), write the files to disk.
+In a chat-only context, print each file in a fenced block, clearly labeled with its
+target path, ready to paste — and remind the human these go to `docs/adr/` and the repo
+root before running dev-loop.
+
+**Tracked-markdown protocol:** if any target `.md` already exists and is tracked, ask
+for its current version before overwriting — never silently replace.
+
+## Handoff to dev-loop
+
+Close with the handoff prompt so the build phase starts by planning, not improvising:
+
+> "Read the ADR set and ACCEPTANCE.md. Before touching code: 1) summarize the plan of
+> files to create/modify, 2) confirm which decisions were left implicit, 3)
+> show me the first test you would write."
+
+Two-command flow end to end: `/uscha-adr-refine` → (ADR set + ACCEPTANCE.md) → `/uscha-devloop`.
+
+## Anti-patterns (do not do)
+
+- Generate an ADR from a one-line request without interviewing.
+- Accept "do it however you want" on a consequential decision without recording the
+  assumption.
+- Write an ACCEPTANCE item that isn't objectively checkable ("that it works well").
+- Emit artifacts before the convergence conditions are met.

package/uscha-kit/skills/uscha-characterize/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: uscha-characterize
+description: >
+  Capture a golden / approval suite of a module's CURRENT behavior — the one artifact the
+  agent must NOT author. Run the ORIGINAL code with real inputs through a deterministic
+  harness, emit .received, and STOP for human approval; never create or edit a .approved
+  file. Used before any migration/modernization to freeze pre-change behavior as field
+  truth. Invoke for "characterize", "golden-capture", "capturá el comportamiento viejo".
+allowed-tools: Read, Write, Glob, Grep, Bash
+disable-model-invocation: false
+---
+
+# characterize — freeze the current behavior as field truth (the agent does not author it)
+
+The golden suite is the ONE piece of the loop the agent cannot author, and that is exactly
+its reason to exist. If you write the golden by reasoning about what the code "should"
+return, you encode the same partial understanding that loses logic silently. **You capture
+what the code DOES, mechanically, by running it — never what it should do.** You may write
+the capture harness; you may NOT create, rename, or edit any `.approved` file.
+
+## Inputs
+
+- **Target module** + a **corpus source**: a path to input fixtures, or a reference to
+  (anonymized) production data. The golden is only worth as much as the corpus (see below).
+
+## Phase 1 — Capture harness (you write this)
+
+Generate a deterministic harness that runs the ORIGINAL module over the corpus and
+serializes ALL observable output. Same input → same `.received`, byte for byte.
+
+## Phase 2 — Non-determinism checklist (emit + normalize BEFORE serializing)
+
+Control every one of these, or the diff lies. Output the checklist applied:
+- [ ] **Timestamps / dates** — frozen clock or stable placeholder.
+- [ ] **Random / seeds** — fixed seed or mocked generator.
+- [ ] **Map/set iteration order** — sort keys before serializing.
+- [ ] **GUIDs / DB auto-increment** — normalized or excluded from the snapshot.
+- [ ] **Concurrency** — thread order must not leak into the output.
+- [ ] **Target locale** — decimal separator, date format, culture. **Mandatory and
+  explicit.** A golden built on one machine and run on another with a different locale
+  breaks entirely (Windows/SQL Server: high risk).
+- [ ] **Deterministic serialization** — JSON with sorted keys, fixed float precision,
+  explicit encoding. Identical byte-for-byte when behavior is identical.
+
+## Phase 3 — Run the capture
+
+Execute the harness → generate `.received` files.
+
+**Declare volatile fields BEFORE approval (kit 1.15.0).** If the ORIGINAL code emits
+values that vary between correct runs and cannot be made deterministic at the source
+(timestamps, request ids, GUIDs from a layer you cannot touch), declare scrub rules in
+`golden.scrub.json` at the fixtures root:
+
+```json
+{ "rules": [
+    {"pattern": "\\d{4}-\\d{2}-\\d{2}T[0-9:.+Z-]+", "replace": "<TIMESTAMP>"},
+    {"pattern": "requestId=[0-9a-f-]{36}", "replace": "requestId=<UUID>"} ] }
+```
+
+`golden-diff` masks BOTH sides with these rules before comparing (text only; binary
+stays byte-for-byte) and reports every scrub-match separately (`N via scrub`) — masking
+is never invisible. Prefer fixing determinism at the source (Phase 2 checklist); scrub
+is for what you genuinely cannot control. The rules file is part of what the human
+approves in Phase 4 — gate-check flags any later edit to it (a broadened rule can mask
+real divergence).
+
+## Phase 4 — STOP for human approval
+
+Return control to the human to review and approve the `.approved` — and, if present,
+`golden.scrub.json` (the scrub rules are contract, same as the goldens). **The skill
+ends here.** It does NOT auto-complete approval, and it does NOT create any `.approved`
+file.
+
+## Corpus — where the inputs come from (critical)
+
+The golden only protects the paths you exercise; what gets lost is usually a rare path.
+Sources, in order of value:
+1. **Real production samples** (anonymized if needed) — the true distribution, including
+   cases nobody knew existed.
+2. **Hand-built edge cases** — known limits (zeros, boundaries, error states, rare
+   combinations of inputs).
+3. **Inputs of past bugs** — every historical bug is a golden input.
+A module whose corpus does not exercise its known branches is marked **PARTIAL**, never
+covered.
+
+## Guardrails (non-negotiable)
+
+- The skill STOPS at the approval point (Phase 4); it never creates/renames/edits `.approved`.
+- A `PreToolUse` hook on `**/*.approved.*` should make agent writes mechanically impossible
+  (see `hooks/block-approved-writes.ps1` + the settings snippet in the kit).
+- `.gitattributes`: `*.approved.* binary` — line endings must not create false diffs
+  (Windows/SQL Server).
+
+## Acceptance criteria
+
+- The skill ends at Phase 4 with no `.approved` created or renamed.
+- The harness is deterministic (same input → same `.received` byte for byte).
+- The output includes the non-determinism checklist that was applied.
+
+## Harness stack
+
+- **Java** → ApprovalTests.Java (`com.approvaltests:approvaltests`, JUnit 5 / JDK 21);
+  `JsonApprovals.verifyAsJson()` for structured responses, `WithTimeZone`-style helpers
+  to freeze time/locale. For read-only migrations, the "old query vs new query against prod"
+  pattern applies.
+- **C++ / other** → a fixtures dir + a deterministic serializer + a diff runner (no
+  comfortable native ApprovalTests; go custom).
+- For system I/O, a fixtures dir + custom runner that normalizes and diffs is often better
+  than relying on the library alone.
+
+## Relationship to the other skills
+
+- **reverse-discovery** orchestrates this skill as its Phase 2 (golden capture at the
+  boundaries).
+- The captured `.approved` is the arbiter that `qa_ledger.py golden-diff` byte-compares
+  against during `/uscha-devloop`.
+- If you maintain `golden-labels.json`, classify approved fixtures as `intended`,
+  `observed-accidental`, or leave them `unknown`; labels explain intent but never
+  replace the byte comparison.
+
+## Tracked-markdown / tracked-golden protocol
+
+Never overwrite an existing approved golden. If a `.received` already exists, regenerate it;
+if a `.approved` exists, it is the human's — leave it untouched and surface the diff.