opencode-skills-collection 4.1.1 → 4.1.3

package/bundled-skills/repo-native-refactor/references/error-reliability.md

@@ -0,0 +1,117 @@
+# Error and reliability boundaries
+
+Error handling is about ownership, not visual cleanliness.
+
+Before changing an error path establish:
+
+1. where the failure originates;
+2. which layer understands its meaning;
+3. which layer can recover;
+4. which layer should add context;
+5. which layer should log;
+6. which layer decides whether the operation continues.
+
+## Swallowed errors
+
+An empty or minimal catch is suspicious when it destroys meaningful failure information.
+
+It may still be intentional for:
+
+- best-effort telemetry;
+- feature detection;
+- cleanup;
+- optional enrichment;
+- compatibility probing.
+
+Understand the owner before changing behavior.
+
+Never blindly convert:
+
+`catch {}`
+
+into:
+
+`log + throw`.
+
+That changes observable semantics.
+
+## Fallbacks
+
+An empty array, empty string, null, cached value, or default object may represent:
+
+- legitimate degradation;
+- product behavior;
+- backward compatibility;
+- masking of infrastructure failure.
+
+Determine which before removing it.
+
+## Logging
+
+Avoid duplicate logging across layers.
+
+The layer that has sufficient context and ownership should normally log.
+
+Lower-level code may enrich or propagate errors without logging when an outer boundary owns observability.
+
+Do not remove logs solely because console output resembles debug residue; CLI or system output may be contractual.
+
+Do not casually rewrite log templates, structured field names, event names, metric labels, or severity. Dashboards, alerts, parsers, support procedures, and tests may depend on them even when no static caller is visible.
+
+## Error and output wording
+
+Error messages, status text, stdout, and stderr are potentially observable behavior.
+
+Before rewording, check:
+
+- tests and snapshots;
+- callers that parse or display the text;
+- CLI and API compatibility expectations;
+- monitoring, support, or localization workflows;
+- whether the repository treats error codes or typed values as the stable contract instead.
+
+Improve wording only when the task permits it and the compatibility surface is understood. Do not replace precise domain language with generic claims such as "operation failed gracefully" or "an unexpected issue occurred".
+
+## Retry
+
+Before modifying retry logic determine:
+
+- which failures are retryable;
+- retry owner;
+- maximum attempts;
+- backoff;
+- jitter;
+- timeout;
+- idempotency;
+- side effects.
+
+Retries without idempotency analysis are high risk.
+
+## Timeout and cancellation
+
+Do not add or remove timeout/cancellation behavior without understanding:
+
+- caller expectations;
+- resource ownership;
+- cleanup;
+- nested timeout interactions.
+
+## Transactions
+
+Transaction scope is semantic.
+
+Moving calls inside or outside a transaction can change consistency and locking behavior even when code looks simpler.
+
+Treat transaction refactors as R3 or R4.
+
+## Partial failure
+
+Distributed or multi-step work may intentionally succeed partially.
+
+Do not force all-or-nothing behavior unless the domain contract requires it.
+
+## Reliability rule
+
+A cleaner-looking error path is not automatically a more correct one.
+
+Preserve operational semantics unless evidence justifies change.

package/bundled-skills/repo-native-refactor/references/finding-taxonomy.md

@@ -0,0 +1,181 @@
+# Finding taxonomy
+
+A finding is evidence that deserves investigation. It is not automatically a defect.
+
+Before mutating code, establish:
+
+**Observed pattern, then actual consequence, then owning layer, then repository evidence, then appropriate correction.**
+
+A scanner match, generic style preference, complexity number, or resemblance to common AI-generated code is insufficient by itself.
+
+## 1. Repository conformity
+
+Look for changes that introduce a second way to solve a problem the repository already solves coherently.
+
+Examples include parallel:
+
+- validation systems;
+- error models;
+- persistence access paths;
+- logging conventions;
+- configuration mechanisms;
+- helper ecosystems;
+- domain models.
+
+Diagnosis requires comparing semantics and ownership, not just names.
+
+A different implementation is acceptable when its domain, lifecycle, boundary, or invariants genuinely differ.
+
+## 2. Domain semantic erosion
+
+Look for lost or weakened domain meaning.
+
+Signals include generic names at domain-significant scope, loosely typed business states, business rules hidden inside technical transformations, or domain concepts flattened into generic payloads.
+
+Restore terminology only from repository or task evidence.
+
+Do not invent more sophisticated-sounding vocabulary.
+
+Short generic locals in tiny scopes are not automatically problematic.
+
+## 3. Architectural fragmentation
+
+Look for:
+
+- responsibilities placed outside their natural owner;
+- feature logic split across unnecessary technical layers;
+- accidental service/factory/adapter chains;
+- oversized orchestration functions;
+- abstractions with no present policy or boundary value;
+- local solutions that bypass established architecture.
+
+Do not judge architecture from file count alone.
+
+A thin abstraction may legitimately encode dependency direction, ownership, compatibility, policy, or test boundaries.
+
+## 4. Reinvention and duplication
+
+Distinguish:
+
+**same syntax**
+
+from
+
+**same concept**.
+
+Code should normally be consolidated only when implementations share:
+
+- ownership;
+- invariants;
+- semantic purpose;
+- expected reasons to change.
+
+Two similar blocks in different domains may intentionally remain separate.
+
+## 5. Error semantics
+
+Look for:
+
+- swallowed errors;
+- fake success;
+- universal empty fallbacks;
+- lost context;
+- logging at multiple ownership layers;
+- retry at the wrong layer;
+- infrastructure failure converted into misleading domain data.
+
+Determine the error owner before changing propagation.
+
+“Fail loudly” is not a universal rule.
+
+## 6. Type and schema integrity
+
+Investigate:
+
+- unchecked external data;
+- unsafe type suppression;
+- unexplained assertions;
+- loose object/dict structures crossing domain boundaries;
+- mismatch between runtime validation and static types;
+- duplicated incompatible schemas.
+
+Escape hatches are findings, not automatic defects.
+
+A local assertion at a known third-party boundary may be intentional.
+
+## 7. Testing integrity
+
+Look for:
+
+- implementation logic copied into expected values;
+- mocks that replace the behavior being tested;
+- tests coupled to private implementation unnecessarily;
+- assertions weakened to accommodate a change;
+- regression cases removed;
+- meaningless tests created for apparent coverage.
+
+A passing test is useful evidence only to the extent that the test independently constrains behavior.
+
+## 8. Security and reliability
+
+Inspect relevant changes for:
+
+- missing authorization;
+- insecure defaults;
+- lost validation;
+- unbounded retry;
+- missing timeout;
+- incorrect cleanup;
+- broken idempotency;
+- partial-failure handling;
+- unsafe concurrency;
+- transaction leaks;
+- secrets exposed to logs.
+
+Treat these areas as high semantic risk.
+
+## 9. Repository prose and communication integrity
+
+Inspect comments, docstrings, test descriptions, errors, logs, command output, and user-facing strings according to their distinct roles.
+
+Look for:
+
+- narration that restates syntax or execution order;
+- inflated or generic claims without a concrete invariant;
+- documentation that repeats names and types but adds no contract;
+- stale prose that contradicts behavior;
+- domain language flattened into generic wording;
+- valuable rationale buried inside lengthy explanation;
+- observable strings reworded as if they were internal comments.
+
+Prose that resembles common AI output is a finding, not proof that it is wrong. Resolve the repository's local prose conventions, then decide whether to delete, preserve, tighten, correct, or report it.
+
+Do not use phrase blacklists, comment quotas, or AI-detector scores as mutation authority. Read [repository-native prose](repository-prose.md) when prose is material to the cleanup.
+
+## 10. Operational quality
+
+Look for:
+
+- temporary debug output;
+- incorrect log ownership;
+- missing structured context;
+- accidental config drift;
+- speculative environment flags;
+- divergent metrics/tracing conventions;
+- output changes that consumers may observe.
+
+Remember that output can be a contract.
+
+## 11. Change discipline
+
+Look for:
+
+- unrelated cleanup;
+- mass formatting;
+- opportunistic renaming;
+- dependency churn;
+- broad modernization;
+- multiple unrelated architectural changes in one diff;
+- generated artifacts edited outside normal workflow.
+
+A technically “better” change can still be a worse patch if it becomes harder to review, revert, or reason about.

package/bundled-skills/repo-native-refactor/references/refactor-examples.md

@@ -0,0 +1,77 @@
+# Refactor Examples by Risk Band (R0–R4)
+
+Read this when `SKILL.md` Workflow steps 3–4 flag a candidate finding. Each band shows a minimal good vs bad intervention. Do not mutate on style alone. Each good example cites a concrete consequence.
+
+## R0 - Mechanical (formatter-provable)
+
+Bad: hand-reformat churn across 40 files in a feature diff.
+```diff
+- x=1
++ x = 1   # + 200 unrelated lines
+```
+Good: run repo formatter only on touched lines, zero semantic diff. Consequence avoided: review noise.
+
+## R1 - Low Structural (local residue)
+
+Bad: leave `import os` unused + `print(debug)` in shipped diff.
+```python
+import os  # unused
+print("here", x)
+```
+Good:
+```diff
+-import os
+-print("here", x)
+```
+Verify: affected unit test still passes. Consequence: dead weight + log leak.
+
+## R2 - Contextual Structural (predicate extraction)
+
+Bad: two callers implement divergent checks for the same owned validation policy:
+```python
+if not tenant or not tenant.strip(): raise ValueError
+# ... 30 lines later in another module ...
+if tenant is None or tenant == "": raise ValueError
+```
+Good: single affirmative predicate, same ownership/invariants:
+```python
+def _is_valid_tenant(v) -> bool:
+    return isinstance(v, str) and bool(v.strip())
+```
+Consolidate only when shared ownership + same reason to change. Keep small local duplication if abstraction adds coupling. Consequence: divergent policy.
+
+## R3 - Semantic (retry / serialization / transactions)
+
+Bad: blanket retry hiding infra failure:
+```python
+for _ in range(5):
+    try: return publish(ev)
+    except Exception: continue
+```
+Good: idempotency-aware, bounded, owner-logged:
+```python
+for attempt in range(3):
+    try:
+        return publish(ev, idempotency_key=ev.id)
+    except TransientError:
+        if attempt == 2:
+            raise
+        log.warning(
+            "publish retry",
+            extra={"attempt": attempt + 1},
+        )
+```
+Retry only transient failures; propagate the final failure after exhaustion and
+non-transient errors immediately. Follow the repository's existing backoff and timeout
+policy. Verify eventual success, exhausted retries, and a non-retryable failure.
+Never mass-rewrite R3 without explicit instruction + verified tests.
+
+## R4 - Critical Boundary (auth / migration / durability)
+
+Bad: mutate contract in place without preserving last-valid state.
+Good: preserve + report, do not guess:
+```python
+# preserve LEDGER_FILE: str contract, stage replacement, fsync, atomic rename
+# if intent/ownership/migration semantics unclear, stop and report
+```
+Maximum conservatism. Missing evidence means preserve plus a completion report `Needs review`.

package/bundled-skills/repo-native-refactor/references/repository-prose.md

@@ -0,0 +1,157 @@
+# Repository-native prose
+
+Source prose should carry information that code cannot express clearly and should sound normal for its repository. The objective is not to imitate a person or evade detection. It is to remove narration, inflation, and generic language while preserving contracts and rationale.
+
+## Resolve the local prose baseline
+
+Before changing prose, sample healthy code near the same owner, domain, and runtime boundary. Infer only what the sample supports:
+
+- which constructs are documented;
+- comment density and placement;
+- fragments versus complete sentences;
+- capitalization and punctuation;
+- docstring or API-documentation format;
+- domain terminology and abbreviations;
+- accepted tags such as `TODO`, `FIXME`, or issue references;
+- whether test names, logs, and errors follow stable templates.
+
+Prefer explicit repository configuration and documentation over inference. Do not treat newly introduced code, generated output, or a visibly inconsistent file as authoritative precedent.
+
+Classify the baseline as `observed`, `likely`, `conflicting`, or `unknown`. If conventions conflict, prefer the pattern closest in ownership and domain. If evidence remains weak, use the conservative fallback below rather than inventing a house style.
+
+## Distinguish prose surfaces
+
+Do not apply one cleanup policy to every string.
+
+### Internal comments
+
+Internal comments may be removed when they merely repeat code. They are valuable when they explain a non-obvious constraint, invariant, tradeoff, external-system behavior, or reason an apparently simpler implementation is unsafe.
+
+### Public documentation
+
+Docstrings, API comments, annotations, and generated-documentation sources may be contracts or required by repository tooling. Preserve required structure and describe observable behavior accurately. Do not remove documentation merely because names and types look self-explanatory.
+
+### Tests
+
+Test descriptions and assertion messages should express behavior in the repository's established vocabulary. Avoid tutorial-like narratives and verbose restatements of the fixture. Treat expected messages and snapshots as behavioral evidence, not casual prose.
+
+### Errors, logs, and command output
+
+Error text, log templates, structured field names, metrics, events, stdout, and stderr may be consumed by tests, dashboards, alerts, scripts, or external systems. Treat them as observable behavior until callers and repository evidence establish otherwise.
+
+### User-facing copy
+
+Do not rewrite product text as code cleanup. Change it only when the task authorizes copy changes or the current wording is an established defect within scope.
+
+## Decide: delete, preserve, tighten, correct, or report
+
+### Delete
+
+Delete prose that contributes no information beyond the code, including confirmed examples of:
+
+- execution narration such as "first", "next", or "finally";
+- comments that restate an assignment, branch, loop, guard, or function call;
+- headings that divide a short function into obvious stages;
+- implementation diary entries;
+- comments added only to label ordinary getters, setters, constructors, or data movement;
+- docstrings that repeat the symbol name and type information without adding a contract;
+- claims that code is clean, simple, robust, elegant, or maintainable.
+
+Prefer deletion over replacing a redundant long comment with a redundant short one.
+
+### Preserve
+
+Preserve still-relevant information about:
+
+- compatibility behavior;
+- external protocol irregularities;
+- security boundaries;
+- concurrency, ordering, transaction, or lifecycle constraints;
+- counterintuitive domain rules;
+- intentional degradation or best-effort behavior;
+- performance tradeoffs that are not apparent locally;
+- rationale supported by repository history or documentation.
+
+Awkward wording alone is not enough to delete important knowledge.
+
+### Tighten
+
+Tighten prose when it contains necessary information but is inflated, generic, or poorly aligned with local terminology. Keep the concrete constraint and remove ceremony.
+
+For example, replace:
+
+```text
+Gracefully handle the legacy response to ensure that the operation remains robust.
+```
+
+with a repository-appropriate form of:
+
+```text
+The v1 endpoint returns 200 with an empty body when the record is missing.
+```
+
+Do not add certainty that the evidence does not support.
+
+### Correct
+
+Correct stale or misleading prose only when behavior and intent are established. Update the smallest relevant surface. If correcting the prose exposes an actual behavioral defect, classify that code change separately.
+
+### Report
+
+Report rather than rewrite when a comment may encode history, a string may be consumed, or the intended contract is unclear. Uncertainty is not permission to normalize.
+
+## Comment necessity test
+
+Before retaining or adding a comment, ask:
+
+> If this prose disappeared, would a maintainer lose an important fact that the code, type system, tests, or nearby contract does not express clearly?
+
+If not, omit the comment. If yes, state the missing fact directly and at the narrowest useful location.
+
+## Candidate signals, not deletion rules
+
+The following patterns often deserve inspection:
+
+- "We need to", "This function", or "The following code";
+- "First", "Next", "Finally", or numbered step comments;
+- "Handle gracefully", "ensure correctness", or "properly validate" without a named invariant;
+- "robust", "seamless", "comprehensive", "elegant", or similar ungrounded claims;
+- banners and separators that create visual ceremony without structural meaning;
+- a comment before nearly every small block;
+- repeated `@param` or return prose that adds nothing beyond types;
+- comments explaining that code exists "for clarity" or "for maintainability";
+- comments that describe the implementation process rather than lasting system behavior.
+
+These are discovery hints only. Phrase matching, comment-count targets, and AI detectors cannot determine whether prose is correct or necessary.
+
+## Conservative fallback
+
+When the repository provides little reliable prose evidence:
+
+- prefer no comment when code is already clear;
+- explain why, a constraint, or external behavior rather than narrating what;
+- use concrete domain nouns and active phrasing;
+- keep one idea per comment;
+- place the explanation next to the boundary it qualifies;
+- avoid tutorial voice, self-dialogue, marketing language, and performative assurances;
+- do not add comments merely to signal craftsmanship;
+- do not invent tickets, incidents, owners, dates, or production history.
+- Never invent ticket, PR, or incident references. An inaccessible or unverified reference is not evidence of fabrication. Preserve existing references unless repository evidence establishes that they are incorrect or obsolete; report material uncertainty instead of deleting them.
+
+This fallback is deliberately modest. It must not become a universal style imposed over repository evidence.
+
+## Final prose review
+
+Inspect the final diff and ask:
+
+- Did any deleted comment contain a constraint not preserved elsewhere?
+- Did a rewrite become less precise while becoming shorter?
+- Did redundant prose survive only in paraphrased form?
+- Did comment density move toward relevant healthy code rather than an arbitrary target?
+- Did terminology match the owning domain?
+- Did any error, log, event, test expectation, or command output change without contract analysis?
+- Did the refactor fabricate rationale or history?
+- Is each added ticket, PR, or incident reference supported by a source?
+- Was any existing reference deleted merely because it could not be verified?
+
+Remove prose edits that cannot be justified by semantics or repository evidence.

package/bundled-skills/repo-native-refactor/references/repository-rehabilitation.md

@@ -0,0 +1,94 @@
+# Repository Rehabilitation
+
+Use this mode only when the authorized scope is codebase-wide or spans multiple coherent domains. Its purpose is consistent rehabilitation, not a single sweeping rewrite.
+
+## Survey before mutation
+
+Map the repository at the level needed to choose safe batches:
+
+- instruction and ownership boundaries;
+- applications, packages, modules, or domains;
+- public, persistence, network, security, and operational boundaries;
+- generated, vendored, migrated, snapshot, and golden artifacts;
+- build, type, lint, test, generation, and validation workflows;
+- areas with active user changes;
+- duplicated systems for errors, validation, configuration, persistence, or observability;
+- areas where repository conventions conflict.
+
+Do not review every file at equal depth. Begin with architecture signals, representative healthy paths, changed or high-churn areas when known, and boundaries that determine behavior.
+
+## Build a concise repository profile
+
+Record only decisions that will guide multiple batches:
+
+- ownership and dependency direction;
+- domain vocabulary;
+- type, schema, and validation boundaries;
+- error and result model;
+- persistence and transaction conventions;
+- async, retry, timeout, and cancellation ownership;
+- logging and observability conventions;
+- test strategy and trustworthy verification commands;
+- comment and documentation conventions;
+- dependency policy;
+- sensitive or excluded artifacts;
+- observed conflicts and unresolved uncertainty.
+
+Mark each convention `observed`, `likely`, `conflicting`, or `unknown`. Cite the repository evidence used to infer it. Keep the profile compact and task-local unless the user asks to add documentation to the repository.
+
+Do not infer standards from generated code, obvious outliers, or the code currently suspected of being low quality.
+
+## Choose calibration work
+
+Start with a representative, low-to-moderate-risk batch that has meaningful verification. Use it to test whether the repository profile produces a native result before applying it broadly.
+
+Avoid beginning with authentication, payments, migrations, destructive persistence, or concurrency-critical code unless those areas are the explicit task and have adequate evidence.
+
+## Batch by ownership
+
+A batch should normally share a domain, owner, runtime boundary, and verification path. It should be small enough that a maintainer can understand its purpose and inspect every changed line.
+
+For each batch:
+
+1. confirm scope and preservation contracts;
+2. refine only the relevant part of the repository profile;
+3. inventory and classify findings;
+4. apply the smallest justified corrections;
+5. run focused verification;
+6. inspect the diff and remove unjustified changes;
+7. record residual uncertainty before continuing.
+
+Do not mix unrelated naming, dependency, architecture, and formatting campaigns in one batch.
+
+## Update the profile carefully
+
+New evidence may refine the profile. It should not silently reverse decisions already used elsewhere.
+
+When a later domain follows a different valid convention, scope the convention to that domain instead of forcing global uniformity. When patterns genuinely conflict, preserve both until ownership or migration intent establishes a preferred direction.
+
+## Cross-batch review
+
+After the bounded passes, inspect the combined result for:
+
+- duplicated concepts left under different names;
+- accidental cross-domain coupling;
+- inconsistent error, validation, or schema boundaries;
+- prose or terminology that diverges between equivalent owners;
+- dependencies introduced only to support cleanup;
+- broad formatting noise;
+- verification gaps that compound across batches.
+
+Run repository-level validation only after focused checks are stable. A clean full-suite result does not excuse an incoherent or unreviewable combined diff.
+
+## Stop conditions
+
+Pause expansion into a region when:
+
+- its owner or intended behavior cannot be established;
+- its convention conflicts materially with the current profile;
+- meaningful verification is unavailable for high-risk behavior;
+- it contains unrelated active changes;
+- generated or historical workflow is unclear;
+- cleanup would require redesign beyond the authorized scope.
+
+Continue elsewhere when safe. Repository-wide authorization broadens coverage, not semantic permission.