ring-using-assert

name	ring:using-assert
description	Dual-mode skill for github.com/LerianStudio/lib-commons/v5/commons/assert — Lerian's production-grade runtime assertion package. Sweep Mode (primary): Dispatches 6 parallel explorer subagents to sweep any Lerian Go codebase for DIY invariant checks, zero-panic policy violations, hand-rolled domain predicates, missing metric initialization, and unstructured error-boundary logging. Generates tasks compatible with ring:dev-cycle for batched fixes. Reference Mode: Full API surface of commons/assert — asserter lifecycle, instance method semantics, complete domain predicate catalog (numeric, financial, transaction state machine, network, time), observability trident, AssertionError unwrapping, decision tree for panic-vs-assert-vs-error, testing patterns.
trigger	Sweep mode: - "Sweep the codebase for commons/assert opportunities" - "Audit this service for zero-panic policy compliance" - "Find panic()/log.Fatal violations" - "Replace DIY invariant checks with commons/assert" Reference mode: - "What's the signature for assert.DebitsEqualCredits?" - "How do I initialize assertion metrics?" - "Should I panic, assert, or return an error here?" - "How do I unwrap AssertionError in a Fiber error handler?"
skip_when	- Working on non-Go services - Working on frontend code - Target codebase is Ring itself
related	{"similar":["ring:using-lib-commons","ring:using-runtime"]}

ring:using-assert

Mode Selection

Request Shape	Mode
"Sweep / audit for assert opportunities"	Sweep
"Find panic()/log.Fatal() violations"	Sweep
"What's the signature for X?"	Reference
"Should I panic, assert, or return error?"	Reference

---

SWEEP MODE

4-phase sweep. Each phase has a hard gate — do not proceed until the current phase produces its artifact.

Phase 1: Version Reconnaissance   → assert-version-report.json
Phase 2: CHANGELOG Delta Analysis → assert-delta-report.json
Phase 3: Multi-Angle DIY Sweep    → 6 × assert-sweep-{N}-{angle}.json
Phase 4: Consolidated Report      → assert-sweep-report.md + assert-sweep-tasks.json

Phase 1: Version Reconnaissance

1. Read go.mod — extract pinned version of github.com/LerianStudio/lib-commons/vN
2. WebFetch https://api.github.com/repos/LerianStudio/lib-commons/releases/latest — extract tag_name
3. Classify drift: up-to-date / minor-drift / moderate-drift / major-upgrade / module-mismatch
4. Emit /tmp/assert-version-report.json: {pinned_version, latest_version, drift_classification, major_upgrade_required, module_path}

Phase 2: CHANGELOG Delta Analysis

1. WebFetch https://raw.githubusercontent.com/LerianStudio/lib-commons/main/CHANGELOG.md
2. Filter entries between pinned_version and latest_version that affect commons/assert
3. Classify: new-predicate / new-method / breaking-change / security-fix / bugfix
4. Emit /tmp/assert-delta-report.json

Phase 3: Multi-Angle DIY Sweep

Dispatch all 6 explorer angles in one parallel batch. Wait for all before Phase 4.

Per-explorer dispatch (subagent_type: ring:codebase-explorer):

## Target: <absolute path>
## Your Angle: <angle number + name>
## Severity Calibration / DIY Patterns / Replacement / Migration Complexity / Version Context
<verbatim from sub-files/sweep-angles.md for this angle>

## Output
Write to: /tmp/assert-sweep-{N}-{angle-slug}.json
Schema: { angle_number, angle_name, severity, migration_complexity,
  findings: [{file, line, diy_pattern, replacement, evidence_snippet, notes}],
  summary, requires_major_upgrade }
If no findings: write file with empty findings array.

Full angle specifications: sub-files/sweep-angles.md

The 6 angles cover:

1. panic() in non-test code (CRITICAL)
2. Defensive nil/empty checks without metric emission (HIGH)
3. Hand-rolled domain predicates duplicating assert.* (HIGH)
4. Missing InitAssertionMetrics at startup (HIGH)
5. Financial invariants in tests only, not production (CRITICAL)
6. AssertionError not unwrapped in error boundaries (MEDIUM)

Phase 4: Consolidated Report

Dispatch synthesizer to read all 6 explorer files and emit:

1. /tmp/assert-sweep-report.md — aggregate findings by severity
2. /tmp/assert-sweep-tasks.json — one task per DIY pattern cluster

Surface report path + task count; offer handoff to ring:dev-cycle.

---

REFERENCE MODE

Full API reference in sub-files/reference.md. Load sections relevant to your task.

Quick Navigation

#	Section	What you'll find
1	API Surface	Exported symbols, signatures
2	Asserter Lifecycle	Scoping, naming, anti-patterns
3	Instance Methods	That / NotNil / NotEmpty / NoError / Never / Halt
4	Domain Predicate Catalog	Numeric / financial / state-machine / network / time
5	Composition Pattern	Pure predicates + observable asserter
6	Observability Trident	Log + span event + metric on every failure
7	AssertionError Unwrapping	Error boundary patterns
8	Decision Tree	panic vs assert vs error
9	Testing Patterns	Proving assertions fire
10	Anti-Pattern Catalog	Six anti-patterns
11	Bootstrap Order	InitAssertionMetrics placement
12–14	Cross-references, Patterns, Breaking Changes	v4→v5 delta

Read sub-files/reference.md for full API detail.