opencode-skills-collection 4.0.53 → 4.0.55

package/bundled-skills/sympy/references/detailed-guide.md

@@ -0,0 +1,439 @@
+# SymPy - Symbolic Mathematics in Python - Detailed Guide
+
+> This file contains the detailed procedure and reference material extracted from `SKILL.md` for focused loading. The root skill defines activation, examples, safety constraints, and limitations.
+
+## Overview
+
+SymPy is a Python library for symbolic mathematics that enables exact computation using mathematical symbols rather than numerical approximations. This skill provides comprehensive guidance for performing symbolic algebra, calculus, linear algebra, equation solving, physics calculations, and code generation using SymPy.
+
+
+## Core Capabilities
+
+### 1. Symbolic Computation Basics
+
+**Creating symbols and expressions:**
+```python
+from sympy import symbols, Symbol
+x, y, z = symbols('x y z')
+expr = x**2 + 2*x + 1
+
+# With assumptions
+x = symbols('x', real=True, positive=True)
+n = symbols('n', integer=True)
+```
+
+**Simplification and manipulation:**
+```python
+from sympy import simplify, expand, factor, cancel
+simplify(sin(x)**2 + cos(x)**2)  # Returns 1
+expand((x + 1)**3)  # x**3 + 3*x**2 + 3*x + 1
+factor(x**2 - 1)    # (x - 1)*(x + 1)
+```
+
+**For detailed basics:** See `references/core-capabilities.md`
+
+### 2. Calculus
+
+**Derivatives:**
+```python
+from sympy import diff
+diff(x**2, x)        # 2*x
+diff(x**4, x, 3)     # 24*x (third derivative)
+diff(x**2*y**3, x, y)  # 6*x*y**2 (partial derivatives)
+```
+
+**Integrals:**
+```python
+from sympy import integrate, oo
+integrate(x**2, x)              # x**3/3 (indefinite)
+integrate(x**2, (x, 0, 1))      # 1/3 (definite)
+integrate(exp(-x), (x, 0, oo))  # 1 (improper)
+```
+
+**Limits and Series:**
+```python
+from sympy import limit, series
+limit(sin(x)/x, x, 0)  # 1
+series(exp(x), x, 0, 6)  # 1 + x + x**2/2 + x**3/6 + x**4/24 + x**5/120 + O(x**6)
+```
+
+**For detailed calculus operations:** See `references/core-capabilities.md`
+
+### 3. Equation Solving
+
+**Algebraic equations:**
+```python
+from sympy import solveset, solve, Eq
+solveset(x**2 - 4, x)  # {-2, 2}
+solve(Eq(x**2, 4), x)  # [-2, 2]
+```
+
+**Systems of equations:**
+```python
+from sympy import linsolve, nonlinsolve
+linsolve([x + y - 2, x - y], x, y)  # {(1, 1)} (linear)
+nonlinsolve([x**2 + y - 2, x + y**2 - 3], x, y)  # (nonlinear)
+```
+
+**Differential equations:**
+```python
+from sympy import Function, dsolve, Derivative
+f = symbols('f', cls=Function)
+dsolve(Derivative(f(x), x) - f(x), f(x))  # Eq(f(x), C1*exp(x))
+```
+
+**For detailed solving methods:** See `references/core-capabilities.md`
+
+### 4. Matrices and Linear Algebra
+
+**Matrix creation and operations:**
+```python
+from sympy import Matrix, eye, zeros
+M = Matrix([[1, 2], [3, 4]])
+M_inv = M**-1  # Inverse
+M.det()        # Determinant
+M.T            # Transpose
+```
+
+**Eigenvalues and eigenvectors:**
+```python
+eigenvals = M.eigenvals()  # {eigenvalue: multiplicity}
+eigenvects = M.eigenvects()  # [(eigenval, mult, [eigenvectors])]
+P, D = M.diagonalize()  # M = P*D*P^-1
+```
+
+**Solving linear systems:**
+```python
+A = Matrix([[1, 2], [3, 4]])
+b = Matrix([5, 6])
+x = A.solve(b)  # Solve Ax = b
+```
+
+**For comprehensive linear algebra:** See `references/matrices-linear-algebra.md`
+
+### 5. Physics and Mechanics
+
+**Classical mechanics:**
+```python
+from sympy.physics.mechanics import dynamicsymbols, LagrangesMethod
+from sympy import symbols
+
+# Define system
+q = dynamicsymbols('q')
+m, g, l = symbols('m g l')
+
+# Lagrangian (T - V)
+L = m*(l*q.diff())**2/2 - m*g*l*(1 - cos(q))
+
+# Apply Lagrange's method
+LM = LagrangesMethod(L, [q])
+```
+
+**Vector analysis:**
+```python
+from sympy.physics.vector import ReferenceFrame, dot, cross
+N = ReferenceFrame('N')
+v1 = 3*N.x + 4*N.y
+v2 = 1*N.x + 2*N.z
+dot(v1, v2)  # Dot product
+cross(v1, v2)  # Cross product
+```
+
+**Quantum mechanics:**
+```python
+from sympy.physics.quantum import Ket, Bra, Commutator
+psi = Ket('psi')
+A = Operator('A')
+comm = Commutator(A, B).doit()
+```
+
+**For detailed physics capabilities:** See `references/physics-mechanics.md`
+
+### 6. Advanced Mathematics
+
+The skill includes comprehensive support for:
+
+- **Geometry:** 2D/3D analytic geometry, points, lines, circles, polygons, transformations
+- **Number Theory:** Primes, factorization, GCD/LCM, modular arithmetic, Diophantine equations
+- **Combinatorics:** Permutations, combinations, partitions, group theory
+- **Logic and Sets:** Boolean logic, set theory, finite and infinite sets
+- **Statistics:** Probability distributions, random variables, expectation, variance
+- **Special Functions:** Gamma, Bessel, orthogonal polynomials, hypergeometric functions
+- **Polynomials:** Polynomial algebra, roots, factorization, Groebner bases
+
+**For detailed advanced topics:** See `references/advanced-topics.md`
+
+### 7. Code Generation and Output
+
+**Convert to executable functions:**
+```python
+from sympy import lambdify
+import numpy as np
+
+expr = x**2 + 2*x + 1
+f = lambdify(x, expr, 'numpy')  # Create NumPy function
+x_vals = np.linspace(0, 10, 100)
+y_vals = f(x_vals)  # Fast numerical evaluation
+```
+
+**Generate C/Fortran code:**
+```python
+from sympy.utilities.codegen import codegen
+[(c_name, c_code), (h_name, h_header)] = codegen(
+    ('my_func', expr), 'C'
+)
+```
+
+**LaTeX output:**
+```python
+from sympy import latex
+latex_str = latex(expr)  # Convert to LaTeX for documents
+```
+
+**For comprehensive code generation:** See `references/code-generation-printing.md`
+
+
+## Working with SymPy: Best Practices
+
+### 1. Always Define Symbols First
+
+```python
+from sympy import symbols
+x, y, z = symbols('x y z')
+# Now x, y, z can be used in expressions
+```
+
+### 2. Use Assumptions for Better Simplification
+
+```python
+x = symbols('x', positive=True, real=True)
+sqrt(x**2)  # Returns x (not Abs(x)) due to positive assumption
+```
+
+Common assumptions: `real`, `positive`, `negative`, `integer`, `rational`, `complex`, `even`, `odd`
+
+### 3. Use Exact Arithmetic
+
+```python
+from sympy import Rational, S
+# Correct (exact):
+expr = Rational(1, 2) * x
+expr = S(1)/2 * x
+
+# Incorrect (floating-point):
+expr = 0.5 * x  # Creates approximate value
+```
+
+### 4. Numerical Evaluation When Needed
+
+```python
+from sympy import pi, sqrt
+result = sqrt(8) + pi
+result.evalf()    # 5.96371554103586
+result.evalf(50)  # 50 digits of precision
+```
+
+### 5. Convert to NumPy for Performance
+
+```python
+# Slow for many evaluations:
+for x_val in range(1000):
+    result = expr.subs(x, x_val).evalf()
+
+# Fast:
+f = lambdify(x, expr, 'numpy')
+results = f(np.arange(1000))
+```
+
+### 6. Use Appropriate Solvers
+
+- `solveset`: Algebraic equations (primary)
+- `linsolve`: Linear systems
+- `nonlinsolve`: Nonlinear systems
+- `dsolve`: Differential equations
+- `solve`: General purpose (legacy, but flexible)
+
+
+## Reference Files Structure
+
+This skill uses modular reference files for different capabilities:
+
+1. **`core-capabilities.md`**: Symbols, algebra, calculus, simplification, equation solving
+   - Load when: Basic symbolic computation, calculus, or solving equations
+
+2. **`matrices-linear-algebra.md`**: Matrix operations, eigenvalues, linear systems
+   - Load when: Working with matrices or linear algebra problems
+
+3. **`physics-mechanics.md`**: Classical mechanics, quantum mechanics, vectors, units
+   - Load when: Physics calculations or mechanics problems
+
+4. **`advanced-topics.md`**: Geometry, number theory, combinatorics, logic, statistics
+   - Load when: Advanced mathematical topics beyond basic algebra and calculus
+
+5. **`code-generation-printing.md`**: Lambdify, codegen, LaTeX output, printing
+   - Load when: Converting expressions to code or generating formatted output
+
+
+## Common Use Case Patterns
+
+### Pattern 1: Solve and Verify
+
+```python
+from sympy import symbols, solve, simplify
+x = symbols('x')
+
+# Solve equation
+equation = x**2 - 5*x + 6
+solutions = solve(equation, x)  # [2, 3]
+
+# Verify solutions
+for sol in solutions:
+    result = simplify(equation.subs(x, sol))
+    assert result == 0
+```
+
+### Pattern 2: Symbolic to Numeric Pipeline
+
+```python
+# 1. Define symbolic problem
+x, y = symbols('x y')
+expr = sin(x) + cos(y)
+
+# 2. Manipulate symbolically
+simplified = simplify(expr)
+derivative = diff(simplified, x)
+
+# 3. Convert to numerical function
+f = lambdify((x, y), derivative, 'numpy')
+
+# 4. Evaluate numerically
+results = f(x_data, y_data)
+```
+
+### Pattern 3: Document Mathematical Results
+
+```python
+# Compute result symbolically
+integral_expr = Integral(x**2, (x, 0, 1))
+result = integral_expr.doit()
+
+# Generate documentation
+print(f"LaTeX: {latex(integral_expr)} = {latex(result)}")
+print(f"Pretty: {pretty(integral_expr)} = {pretty(result)}")
+print(f"Numerical: {result.evalf()}")
+```
+
+
+## Integration with Scientific Workflows
+
+### With NumPy
+
+```python
+import numpy as np
+from sympy import symbols, lambdify
+
+x = symbols('x')
+expr = x**2 + 2*x + 1
+
+f = lambdify(x, expr, 'numpy')
+x_array = np.linspace(-5, 5, 100)
+y_array = f(x_array)
+```
+
+### With Matplotlib
+
+```python
+import matplotlib.pyplot as plt
+import numpy as np
+from sympy import symbols, lambdify, sin
+
+x = symbols('x')
+expr = sin(x) / x
+
+f = lambdify(x, expr, 'numpy')
+x_vals = np.linspace(-10, 10, 1000)
+y_vals = f(x_vals)
+
+plt.plot(x_vals, y_vals)
+plt.show()
+```
+
+### With SciPy
+
+```python
+from scipy.optimize import fsolve
+from sympy import symbols, lambdify
+
+# Define equation symbolically
+x = symbols('x')
+equation = x**3 - 2*x - 5
+
+# Convert to numerical function
+f = lambdify(x, equation, 'numpy')
+
+# Solve numerically with initial guess
+solution = fsolve(f, 2)
+```
+
+
+## Quick Reference: Most Common Functions
+
+```python
+# Symbols
+from sympy import symbols, Symbol
+x, y = symbols('x y')
+
+# Basic operations
+from sympy import simplify, expand, factor, collect, cancel
+from sympy import sqrt, exp, log, sin, cos, tan, pi, E, I, oo
+
+# Calculus
+from sympy import diff, integrate, limit, series, Derivative, Integral
+
+# Solving
+from sympy import solve, solveset, linsolve, nonlinsolve, dsolve
+
+# Matrices
+from sympy import Matrix, eye, zeros, ones, diag
+
+# Logic and sets
+from sympy import And, Or, Not, Implies, FiniteSet, Interval, Union
+
+# Output
+from sympy import latex, pprint, lambdify, init_printing
+
+# Utilities
+from sympy import evalf, N, nsimplify
+```
+
+
+## Troubleshooting Common Issues
+
+1. **"NameError: name 'x' is not defined"**
+   - Solution: Always define symbols using `symbols()` before use
+
+2. **Unexpected numerical results**
+   - Issue: Using floating-point numbers like `0.5` instead of `Rational(1, 2)`
+   - Solution: Use `Rational()` or `S()` for exact arithmetic
+
+3. **Slow performance in loops**
+   - Issue: Using `subs()` and `evalf()` repeatedly
+   - Solution: Use `lambdify()` to create a fast numerical function
+
+4. **"Can't solve this equation"**
+   - Try different solvers: `solve`, `solveset`, `nsolve` (numerical)
+   - Check if the equation is solvable algebraically
+   - Use numerical methods if no closed-form solution exists
+
+5. **Simplification not working as expected**
+   - Try different simplification functions: `simplify`, `factor`, `expand`, `trigsimp`
+   - Add assumptions to symbols (e.g., `positive=True`)
+   - Use `simplify(expr, force=True)` for aggressive simplification
+
+
+## Additional Resources
+
+- Official Documentation: https://docs.sympy.org/
+- Tutorial: https://docs.sympy.org/latest/tutorials/intro-tutorial/index.html
+- API Reference: https://docs.sympy.org/latest/reference/index.html
+- Examples: https://github.com/sympy/sympy/tree/master/examples

package/bundled-skills/systematic-debugging/CREATION-LOG.md

@@ -1,5 +1,8 @@
 # Creation Log: Systematic Debugging Skill
 
+Historical illustrative material. Its scenario and reported outcomes are not a live user request, current verification result, or authorization to execute actions. Follow the current SKILL.md and actual task constraints.
+
+
 Reference example of extracting, structuring, and bulletproofing a critical skill.
 
 ## Source Material

package/bundled-skills/systematic-debugging/SKILL.md

@@ -12,7 +12,7 @@ date_added: "2026-02-27"
 
 Random fixes waste time and create new bugs. Quick patches mask underlying issues.
 
-**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+**Core principle:** Investigate before guessing and separate a verified repair from a temporary mitigation. During an incident, an authorized rollback or containment action may restore service while root-cause work continues.
 
 **Violating the letter of this process is violating the spirit of debugging.**
 
@@ -22,7 +22,7 @@ Random fixes waste time and create new bugs. Quick patches mask underlying issue
 NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
 ```
 
-If you haven't completed Phase 1, you cannot propose fixes.
+Start with the observable failure and the smallest useful evidence check. Label any emergency mitigation explicitly and preserve evidence for the later root-cause investigation.
 
 ## When to Use
 Use for ANY technical issue:
@@ -78,8 +78,8 @@ You MUST complete each phase before proceeding to the next.
    **BEFORE proposing fixes, add diagnostic instrumentation:**
    ```
    For EACH component boundary:
-     - Log what data enters component
-     - Log what data exits component
+     - Record allowed field names, sizes, statuses and correlation IDs
+     - Redact secrets and private payloads before logging
      - Verify environment/config propagation
      - Check state at each layer
 
@@ -90,24 +90,18 @@ You MUST complete each phase before proceeding to the next.
 
    **Example (multi-layer system):**
    ```bash
-   # Layer 1: Workflow
-   echo "=== Secrets available in workflow: ==="
-   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
-
-   # Layer 2: Build script
-   echo "=== Env vars in build script: ==="
-   env | grep IDENTITY || echo "IDENTITY not in environment"
-
-   # Layer 3: Signing script
-   echo "=== Keychain state: ==="
-   security list-keychains
-   security find-identity -v
-
-   # Layer 4: Actual signing
-   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   # In each relevant process, report presence only; never dump secret values.
+   if [ -n "${IDENTITY:-}" ]; then
+     echo 'IDENTITY is set'
+   else
+     echo 'IDENTITY is absent or empty'
+   fi
+
+   # Read-only validation of an already-built artifact, when available.
+   codesign --verify --verbose=2 "$APP"
    ```
 
-   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
+   **Interpretation:** Compare presence checks at the actual workflow/build boundaries. Artifact verification does not itself prove that the correct signing identity propagated.
 
 5. **Trace Data Flow**
 
@@ -178,7 +172,7 @@ You MUST complete each phase before proceeding to the next.
    - Automated test if possible
    - One-off test script if no framework
    - MUST have before fixing
-   - Use the `superpowers:test-driven-development` skill for writing proper failing tests
+   - Use `test-driven-development` for a focused behavioral regression when appropriate
 
 2. **Implement Single Fix**
    - Address the root cause identified
@@ -212,7 +206,7 @@ You MUST complete each phase before proceeding to the next.
 
    **Discuss with your human partner before attempting more fixes**
 
-   This is NOT a failed hypothesis - this is a wrong architecture.
+   Repeated failures are evidence to reassess assumptions and coupling; they do not prove that the architecture is wrong.
 
 ## Red Flags - STOP and Follow Process
 
@@ -275,7 +269,7 @@ If systematic investigation reveals issue is truly environmental, timing-depende
 3. Implement appropriate handling (retry, timeout, error message)
 4. Add monitoring/logging for future investigation
 
-**But:** 95% of "no root cause" cases are incomplete investigation.
+State the remaining uncertainty and the evidence that would distinguish an environmental failure from an implementation defect.
 
 ## Supporting Techniques
 
@@ -286,18 +280,20 @@ These techniques are part of systematic debugging and available in this director
 - **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
 
 **Related skills:**
-- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
-- **superpowers:verification-before-completion** - Verify fix worked before claiming success
+- **test-driven-development** - Focused behavioral regression
+- Use the current repository’s verification commands before claiming success
 
-## Real-World Impact
+## Worked example and expected result
 
-From debugging sessions:
-- Systematic approach: 15-30 minutes to fix
-- Random fixes approach: 2-3 hours of thrashing
-- First-time fix rate: 95% vs 40%
-- New bugs introduced: Near zero vs common
+Input: a build succeeds locally but fails in CI because a required identity is absent in the build subprocess. Record only whether it is set at each boundary, inspect how environment variables are forwarded, and change that propagation once. Re-run the failing build and validate the artifact separately. Expected: the subprocess receives the required configuration and the original failure disappears; logs contain no credential value.
+
+## Inputs and prerequisites
+
+A reproducible command or observed failure, exact revision/runtime, recent changes and access to an authorized test environment. The bundled historical case notes illustrate the technique; their reported counts are not fresh measurements or guarantees for this project.
 
 ## Limitations
-- Use this skill only when the task clearly matches the scope described above.
-- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
-- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.
+
+- Temporary mitigation and root-cause repair are different outcomes; record both when an incident requires immediate containment.
+- Logging can expose secrets or personal paths. Use allowlisted summaries and inspect captured artifacts before sharing.
+- The polluter helper runs the project’s test command and can execute project code; use an isolated fixture/checkout and verify the runner accepts a file argument.
+- The waiting examples require domain adapters and cannot make every race impossible. Reproduce the actual timeout/error path.

package/bundled-skills/systematic-debugging/condition-based-waiting.md

@@ -61,16 +61,17 @@ Generic polling function:
 ```typescript
 async function waitFor<T>(
   condition: () => T | undefined | null | false,
-  description: string,
+  description = "condition",
   timeoutMs = 5000
 ): Promise<T> {
-  const startTime = Date.now();
+  if (!Number.isFinite(timeoutMs) || timeoutMs < 0) throw new Error("Invalid timeout");
+  const startTime = performance.now();
 
   while (true) {
     const result = condition();
-    if (result) return result;
+    if (result !== undefined && result !== null && result !== false) return result;
 
-    if (Date.now() - startTime > timeoutMs) {
+    if (performance.now() - startTime >= timeoutMs) {
       throw new Error(`Timeout waiting for ${description} after ${timeoutMs}ms`);
     }
 
@@ -108,8 +109,10 @@ await new Promise(r => setTimeout(r, 200));   // Then: wait for timed behavior
 
 ## Real-World Impact
 
-From debugging session (2025-10-03):
+Historical source report (2025-10-03), not re-executed by this skill:
 - Fixed 15 flaky tests across 3 files
 - Pass rate: 60% → 100%
 - Execution time: 40% faster
-- No more race conditions
+- The reported cases passed; other races remain possible
+
+The generic condition must be synchronous; an async predicate returns a Promise immediately and needs a separate awaited implementation. A polling deadline cannot interrupt a condition that blocks forever. The domain-specific TypeScript file imports external Lace types and is not standalone.

package/bundled-skills/systematic-debugging/defense-in-depth.md

@@ -4,12 +4,12 @@
 
 When you fix a bug caused by invalid data, adding validation at one place feels sufficient. But that single check can be bypassed by different code paths, refactoring, or mocks.
 
-**Core principle:** Validate at EVERY layer data passes through. Make the bug structurally impossible.
+**Core principle:** Validate at EVERY layer data passes through. Define and test a distinct invariant at each relevant boundary.
 
 ## Why Multiple Layers
 
 Single validation: "We fixed the bug"
-Multiple layers: "We made the bug impossible"
+Multiple layers: "Different failure paths now have explicit checks"
 
 Different layers catch different cases:
 - Entry validation catches most bugs
@@ -56,10 +56,12 @@ function initializeWorkspace(projectDir: string, sessionId: string) {
 async function gitInit(directory: string) {
   // In tests, refuse git init outside temp directories
   if (process.env.NODE_ENV === 'test') {
-    const normalized = normalize(resolve(directory));
-    const tmpDir = normalize(resolve(tmpdir()));
-
-    if (!normalized.startsWith(tmpDir)) {
+    // For an existing directory: compare real paths and path components.
+    // Import realpathSync from node:fs and relative/isAbsolute/sep from node:path.
+    const normalized = realpathSync(directory);
+    const tmpDir = realpathSync(tmpdir());
+    const child = relative(tmpDir, normalized);
+    if (!child || child === '..' || child.startsWith(`..${sep}`) || isAbsolute(child)) {
       throw new Error(
         `Refusing git init outside temp dir during tests: ${directory}`
       );
@@ -109,7 +111,7 @@ Bug: Empty `projectDir` caused `git init` in source code
 - Layer 3: `WorktreeManager` refuses git init outside tmpdir in tests
 - Layer 4: Stack trace logging before git init
 
-**Result:** All 1847 tests passed, bug impossible to reproduce
+**Historical reported result:** 1847 tests passed in the source case. This repository does not bundle that test suite; the count is not a current verification result.
 
 ## Key Insight
 
@@ -120,3 +122,7 @@ All four layers were necessary. During testing, each layer caught bugs the other
 - Debug logging identified structural misuse
 
 **Don't stop at one validation point.** Add checks at every layer.
+
+## Limits of path checks
+
+A string prefix such as `/tmp` also matches `/tmp-other`; use path components and account for links. A preflight realpath check does not prevent a concurrent path replacement. For mutation, bind the operation to a private owned fixture and use the platform’s appropriate descriptor/identity checks. `NODE_ENV` is configuration, not an authorization boundary.