opencode-skills-collection 4.1.2 → 4.1.3

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.

package/bundled-skills/repo-native-refactor/references/semantic-risk.md

@@ -0,0 +1,187 @@
+# Semantic risk and mutation policy
+
+> Field note: when unsure between R2 and R3, I pick the higher band. Cheaper than a rollback.
+
+Risk measures the potential consequence of being wrong.
+
+Transformation safety measures confidence that a rewrite preserves meaning.
+
+They are related but separate.
+
+## R0 - mechanical
+
+Typical examples:
+
+- formatting;
+- import ordering;
+- provably unused imports;
+- obvious accidental separators;
+- deterministic syntax normalization.
+- deletion of a locally obvious comment that only restates syntax and carries no contract.
+
+Policy:
+
+Automatic mutation is acceptable when repository tooling establishes the transformation.
+
+## R1 - low structural risk
+
+Typical examples:
+
+- redundant local syntax;
+- provably dead local residue;
+- obvious no-op indirection.
+- comment or docstring cleanup whose meaning is fully established locally.
+
+Policy:
+
+Mutation is acceptable when scope is local and verification is straightforward.
+
+## R2 - contextual structural risk
+
+Typical examples:
+
+- renaming;
+- moving code;
+- extracting or inlining helpers;
+- reducing nesting;
+- consolidating duplication;
+- collapsing abstractions.
+- rewriting rationale, public documentation, test descriptions, or potentially consumed text.
+
+Policy:
+
+Inspect ownership and repository precedent first.
+
+Require a concrete maintainability or semantic benefit.
+
+Do not refactor merely because another form is prettier.
+
+## R3 - semantic risk
+
+Typical examples:
+
+- exception propagation;
+- fallbacks;
+- retries;
+- timeout;
+- caching;
+- serialization;
+- transaction ownership;
+- async lifecycle;
+- resource cleanup.
+- error or operational wording known to participate in application behavior.
+
+Policy:
+
+Never bulk-rewrite.
+
+Establish the preservation contract and meaningful behavioral verification.
+
+## R4 - critical boundary
+
+Typical examples:
+
+- authentication;
+- authorization;
+- permissions;
+- payment;
+- cryptography;
+- migrations;
+- destructive persistence;
+- concurrency-critical logic;
+- security enforcement.
+
+Policy:
+
+Maximum conservatism.
+
+When evidence is incomplete, preserve behavior and report the finding.
+
+## Transformation classes
+
+### Class A - proven mechanical
+
+May be applied unattended.
+
+The rewrite must have clear local equivalence or be an established project-tool transformation.
+
+### Class B - context sensitive
+
+Generate or consider a candidate change, then inspect and verify.
+
+Examples:
+
+- helper inline;
+- control-flow flattening;
+- rename;
+- abstraction removal;
+- context-sensitive comment or documentation changes.
+
+### Class C - semantic
+
+Requires reasoning about behavioral ownership.
+
+Examples:
+
+- changing `catch` behavior;
+- replacing fallbacks with exceptions;
+- changing retries;
+- changing transaction scope;
+- changing auth logic;
+- changing async error ownership.
+
+Never run Class C as a mass structural rewrite.
+
+## Prose risk
+
+Prose risk depends on its role, not its appearance.
+
+- Deleting a confirmed syntax restatement may be mechanical.
+- Rewriting a rationale requires repository and behavioral context.
+- Public API documentation may define a contract.
+- Error messages, logs, event fields, snapshots, stdout, and stderr may be observable behavior.
+- Comments around security, compatibility, transactions, concurrency, migrations, or lifecycle inherit the risk of the behavior they explain.
+
+Phrase matching can find candidates but cannot establish a transformation class.
+
+## Justification gate
+
+Before a significant R2+ mutation establish:
+
+**Observed problem:** What is wrong?
+
+**Consequence:** Why does it matter?
+
+**Owner:** Which layer should own the correction?
+
+**Repository evidence:** What supports that decision?
+
+**Minimal correction:** What is the smallest adequate repair?
+
+**Preservation:** What behavior must remain unchanged?
+
+**Verification:** How will the correction be checked?
+
+If the only justification is “cleaner”, “more elegant”, or “more senior”, do not perform a broad refactor.
+
+**Visible-text escalation:** if a structural change alters user- or contract-visible text
+(error messages, CLI output, logs, event fields, snapshots), escalate one band
+(R1-R2, R2-R3) and treat that text as an observable contract: preserve it exactly or
+update its consumers within scope. A green suite that asserts only exception types does
+not prove the text is safe to change.
+
+## Stop conditions
+
+Preserve rather than aggressively refactor when:
+
+- intended behavior cannot be established;
+- tests and implementation conflict without clear authority;
+- repository patterns conflict materially;
+- public contract consequences are unknown;
+- migration intent is unclear;
+- error ownership cannot be determined;
+- concurrency behavior lacks verification;
+- duplicate-looking implementations may represent independent domains;
+- unusual code may encode an unexplained historical constraint.
+
+A stop applies to the uncertain region, not necessarily the entire audit.

package/bundled-skills/repo-native-refactor/references/shared-contracts.md

@@ -0,0 +1,48 @@
+# Shared contracts
+
+These rules apply to repository development and review.
+
+## 1. Strict contract adherence (canonical wording)
+
+Preserve documented or demonstrably consumed public contracts across public interfaces,
+exported parameters, module constants, return types, errors, and serialization.
+
+- A requested behavior change may authorize a contract change only when that consequence
+  is clear from the task or from an authorized evolution. Then update affected callers,
+  tests, and living documentation within scope.
+- Otherwise preserve exact declared types. For example, never substitute or wrap an exposed
+  primitive `str` path contract with `pathlib.Path` or custom wrapper objects merely for
+  internal convenience or preference.
+- Internal intermediate representations may use appropriate helpers, provided all exposed
+  public contracts and types remain exact.
+
+## 2. Evidence hierarchy (canonical order)
+
+Use to guide investigation, not to auto-resolve material contradictions:
+
+1. User requirements and explicitly authorized scope.
+2. Documented architecture and repository guidelines.
+3. Observable public contracts and persisted schemas.
+4. Healthy sibling code within the same domain and runtime boundary.
+5. Relevant tests, schemas, callers, and dependencies.
+6. Dominant local conventions.
+7. Language and runtime idioms.
+8. Conservative, idiomatic defaults.
+
+Never treat a temporary workaround, buggy sibling, or accidental pattern as precedent.
+Never rewrite history or rubber-stamp code with stale notes. Reconcile before mutating
+the affected contract.
+
+## 3. Verification final-state rule (canonical)
+
+- Record baseline failures as: (1) pre-existing outside scope, (2) in-scope to fix,
+  (3) regressions from current changes, (4) environment errors.
+- Verify the final code state. Never use pre-cleanup results to certify modified code.
+- Never claim a check ran when it did not. Distinguish verified behavior,
+  inspection-only conclusions, and unverified assumptions.
+
+## 4. Shared judgment tests (canonical)
+
+Two questions that both skills use when the text alone under-determines the answer.
+
+A pattern counts as healthy precedent only if three things hold: code outside its original author consumes it, it does not contradict docs or contracts, and you would copy it into a new domain without apology. Popularity proves nothing; a workaround with tests and docs still fails. When two domains overlap, the owner is whoever owns the failure (who gets paged, who fixes the bug, whose reason to change fires first). Consolidate toward that owner, or leave both alone.

package/bundled-skills/repo-native-refactor/references/testing-integrity.md

@@ -0,0 +1,103 @@
+# Testing integrity
+
+Tests are evidence.
+
+They are not automatically truth.
+
+The audit must consider both:
+
+**implementation quality**
+
+and
+
+**test quality**.
+
+## Evidence confidence
+
+### High confidence
+
+Examples:
+
+- contract tests;
+- integration tests;
+- independent expected values;
+- observable end-to-end behavior;
+- regression tests tied to an externally visible failure.
+
+### Medium confidence
+
+Examples:
+
+- meaningful unit tests around public behavior;
+- isolated business-rule tests with independent fixtures.
+
+### Low confidence
+
+Examples:
+
+- expectations copied from implementation logic;
+- excessive implementation mocking;
+- tests of private structure;
+- snapshots with little semantic meaning;
+- tests asserting only that mocks were called.
+
+Higher semantic risk requires stronger evidence.
+
+If R3/R4 code has weak test evidence, reduce refactor aggressiveness.
+
+## Test-slop patterns
+
+### Tautological expectations
+
+Bad pattern:
+
+implementation computes X using formula F; test independently reproduces formula F and compares both.
+
+The test may repeat the same mistake.
+
+Prefer independent business examples or externally defined expected outcomes.
+
+### Mock theatre
+
+Mocking is not inherently bad.
+
+The problem occurs when nearly every dependency is replaced and the test validates only the configured mocks rather than meaningful behavior.
+
+Mock external or expensive boundaries when appropriate.
+
+Do not mock away the behavior being audited.
+
+### Test weakening
+
+Never make a refactor pass by:
+
+- deleting a regression case;
+- changing a precise assertion into a vague one;
+- disabling a test;
+- expanding tolerances without domain justification.
+
+If behavior intentionally changes, update tests because the contract changed, and report that behavioral change explicitly.
+
+### Implementation coupling
+
+Refactoring internals should not require widespread test rewrites when public behavior is unchanged unless repository conventions intentionally test internal units.
+
+Large test churn during a behavior-preserving refactor is a warning sign.
+
+### Test prose
+
+Test names should describe meaningful behavior using the repository's vocabulary. Do not lengthen them into narrative specifications merely to appear thorough, and do not shorten them until the behavior under test becomes ambiguous.
+
+Assertion messages, expected errors, snapshots, and golden output may constrain observable wording. Do not update them solely to accommodate stylistic rewording. If the contract intentionally changes, report it and retain independent behavioral evidence.
+
+## Verification strategy
+
+Prefer the smallest validation set that meaningfully constrains the change, then expand when risk requires it.
+
+Mechanical cleanup may need type/lint/unit checks.
+
+Structural changes may require focused unit and integration checks.
+
+Semantic and critical-boundary changes may require contract, integration, security, or end-to-end verification.
+
+Do not claim verification beyond what was actually run.