genome-spy-python 0.1.0__tar.gz

genome_spy_python-0.1.0/.agents/skills/commit/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: commit
+description: Commit repository changes in small thematic chunks using conventional commits and concise changelog staging.
+---
+
+# Commit Workflow
+
+Prefer several small thematic commits over one broad commit.
+
+## Rules
+
+* Run `git status --short` first.
+* Use conventional commits: `<type>(<scope>): <description>`.
+* Split independently meaningful changes.
+* Keep implementation and its direct tests together when they form one change.
+* Leave unrelated user changes unstaged.
+* Do not amend, rewrite history, revert, force-push, or add co-author trailers unless explicitly requested.
+
+## Efficient Inspection
+
+Minimize token use.
+
+Use:
+
+```bash
+git status --short
+git diff --stat
+```
+
+Use targeted diffs only when needed:
+
+```bash
+git diff -- <files>
+```
+
+Do not read the full diff or re-review code by default.
+
+## Workflow
+
+1. Inspect `git status --short`.
+2. Group files into thematic commit slices.
+3. Use targeted diffs only when grouping is unclear.
+4. Stage one slice.
+5. Verify with `git diff --cached --stat`.
+6. Commit with a conventional commit message.
+7. Repeat for remaining slices.
+8. Run `git status --short` at the end.
+9. Update `CHANGELOG_STAGING.md` once if release-relevant changes were committed.
+10. Report commit hashes and remaining uncommitted files.
+
+## Commit Boundaries
+
+A commit should represent one independently understandable change.
+
+Split separate features, fixes, refactors, tooling/config changes, documentation, and unrelated test work.
+
+Usually keep together:
+
+* implementation and direct tests;
+* API/schema changes and required supporting code;
+* generated files and their source change.
+
+Do not split mechanically by file.
+
+When cleanly separable, prefer multiple commits.
+
+## Conventional Commits
+
+Common types:
+
+* `feat`
+* `fix`
+* `refactor`
+* `perf`
+* `test`
+* `docs`
+* `chore`
+* `build`
+* `ci`
+
+Examples:
+
+```text
+feat(parser): add strand-aware bigwig loading
+fix(cache): invalidate stale entries
+refactor(pipeline): simplify track dispatch
+```
+
+## Changelog Staging
+
+`CHANGELOG_STAGING.md` is for future release notes.
+
+Update it once per commit session only for release-relevant changes.
+
+* Read only the minimum needed context.
+* Add concise bullets under `Added`, `Changed`, `Fixed`, `Removed`, or `Performance`.
+* Prefer one resulting-change bullet over one bullet per commit.
+* Omit routine refactors, formatting, test-only work, and internal details unless release-relevant.
+* Avoid duplicates.
+
+## Default Rule
+
+> Prefer the smallest coherent commit representing one independently understandable change.
+
+Avoid unnecessary diff reading.

genome_spy_python-0.1.0/.agents/skills/proper-code-review/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: proper-code-review
+description: Review code changes for correctness, simplicity, readability, maintainability, architectural fit, and meaningful system-level performance. Use when asked to review a diff, implementation, branch, or recent code changes.
+---
+
+# Code Review
+
+Review the current changes as a senior engineer.
+
+Optimize for correctness and low total lifecycle complexity. Prefer simple, readable, maintainable implementations that fit the existing repository and are sufficiently performant for realistic workloads.
+
+Prefer a few high-confidence findings over exhaustive commentary.
+
+## Core Principles
+
+* Correctness comes first.
+* Prefer the simplest adequate solution (the KISS principle).
+* Optimize for local reasoning and localized change.
+* Avoid duplicated knowledge and parallel mechanisms.
+* Reuse existing repository concepts when appropriate.
+* Avoid speculative abstraction and extensibility.
+* Require concrete justification for added complexity.
+* Judge performance at the system level, not only locally.
+* Do not manufacture findings.
+
+Complexity must pay for itself through a concrete benefit such as correctness, meaningful reuse, change locality, real variation, necessary scalability, or material performance.
+
+## Review Method
+
+### 1. Understand the change
+
+Read the diff first.
+
+Determine:
+
+* what problem the change solves;
+* what behavior changes;
+* which interfaces, invariants, state, or architectural concepts are affected.
+
+Inspect only enough surrounding repository context to answer concrete review questions.
+
+When relevant:
+
+* inspect callers before claiming breakage;
+* inspect tests for intended behavior and invariants;
+* search for existing mechanisms before proposing new ones;
+* inspect analogous implementations when evaluating duplication or architectural fit;
+* inspect the broader execution path when evaluating performance.
+
+Do not attempt to understand the entire repository.
+
+### 2. Verify before judging
+
+Treat potential findings as hypotheses.
+
+Before reporting a concern, verify it against the repository when possible.
+
+Examples:
+
+* locate the duplicated representation before claiming duplicated knowledge;
+* inspect callers before claiming API incompatibility;
+* search for existing abstractions before proposing a new one;
+* establish performance significance before criticizing or recommending optimization.
+
+Do not present assumptions as facts.
+
+### 3. Review correctness
+
+Look for concrete:
+
+* behavioral bugs and regressions;
+* broken invariants;
+* invalid assumptions;
+* relevant edge cases;
+* unsafe mutation or state transitions;
+* error-handling or resource-lifecycle problems;
+* concurrency issues;
+* unintended compatibility changes.
+
+Passing tests are evidence, not proof.
+
+Use `references/correctness.md` when deeper analysis is useful.
+
+### 4. Review design
+
+Evaluate simplicity, readability, maintainability, cohesion, coupling, abstraction, change locality, blast radius, and architectural fit together.
+
+Ask:
+
+* Could this be simpler? The KISS principle!
+* Can it be understood and changed locally?
+* Does one conceptual change require synchronized edits?
+* Has unnecessary machinery been introduced?
+* Does this duplicate an existing repository mechanism?
+* Does an abstraction represent real shared semantics?
+* Is the solution proportional to the problem?
+* YAGNI principle ("You Aren't Gonna Need It")
+
+Prefer straightforward implementations when additional cleverness provides little concrete benefit.
+
+Use `references/design.md` when deeper analysis is useful.
+
+### 5. Review performance
+
+Look for meaningful issues involving:
+
+* algorithmic complexity;
+* repeated expensive work;
+* I/O;
+* memory and copying;
+* serialization or data movement;
+* CPU/GPU synchronization;
+* realistic scaling.
+
+Judge optimizations by end-to-end impact.
+
+Do not accept meaningful complexity for negligible local gains.
+
+Use `references/performance.md` when performance is relevant.
+
+### 6. Validate findings
+
+Before reporting each finding, ask:
+
+* Is the problem concrete?
+* Is the consequence meaningful?
+* Does the evidence support it?
+* Is the recommendation proportionate?
+* Does the proposed fix reduce total complexity?
+
+Remove speculative, cosmetic, generic, or low-value comments.
+
+Prefer no finding over a weak finding.
+
+## Output
+
+Report findings in descending order of practical impact.
+
+For each finding:
+
+### `[Severity] Short problem statement`
+
+**Location:** Smallest useful code region.
+
+**Problem:** What is wrong.
+
+**Impact:** Why it matters here.
+
+**Recommendation:** Smallest reasonable fix.
+
+Use:
+
+* **Critical** — correctness, data loss, security, or severe failure.
+* **Important** — substantial behavioral, architectural, maintainability, performance, or scalability issue.
+* **Minor** — worthwhile simplification or readability improvement.
+
+Normally omit stylistic nits.
+
+Combine findings with the same root cause.
+
+State uncertainty explicitly.
+
+Do not include generic best-practice advice, speculative future concerns, praise for unaffected code, or alternative architectures merely because they are possible.
+
+If no meaningful issues remain, say that no significant issues were found.

genome_spy_python-0.1.0/.agents/skills/proper-code-review/references/correctness.md

@@ -0,0 +1,151 @@
+# Correctness Review
+
+Correctness review asks whether the change preserves the intended behavior of the system across realistic inputs, states, and failure conditions.
+
+Passing tests are evidence of correctness, not proof.
+
+## Understand the Contract
+
+Determine what the code is expected to guarantee.
+
+Consider:
+
+* input assumptions;
+* output guarantees;
+* state transitions;
+* API behavior;
+* ordering;
+* persistence;
+* error behavior;
+* compatibility;
+* important domain invariants.
+
+A correctness finding should identify a concrete way the intended contract can be violated.
+
+## Behavioral Changes
+
+Check whether the patch changes behavior beyond its stated purpose.
+
+Look for unintended changes to:
+
+* defaults;
+* return values or shapes;
+* ordering;
+* mutation;
+* exceptions;
+* serialization;
+* persistence;
+* handling of missing or invalid input;
+* behavior visible to callers.
+
+Small implementation changes can have large effects at module boundaries.
+
+## Edge Cases and Invariants
+
+Prioritize edge cases that are realistic for the domain and changed logic.
+
+Examples include:
+
+* empty or single-element inputs;
+* missing or malformed data;
+* duplicates;
+* boundary values;
+* partial failures;
+* large inputs where behavior changes.
+
+Identify invariants that must remain true, such as:
+
+* related collections remaining aligned;
+* identifiers remaining unique;
+* ordering being preserved;
+* cached state matching source state;
+* state transitions occurring in a valid order.
+
+Do not generate exhaustive theoretical edge cases without evidence that they matter.
+
+## State and Mutation
+
+Ask:
+
+* What state is mutated?
+* Is mutation expected by callers?
+* Can partial mutation remain after failure?
+* Is state shared across calls?
+* Can stale state survive?
+* Does aliasing versus copying matter?
+
+Pay particular attention when the change introduces shared state, caching, batching, or multiple representations of the same data.
+
+## Error and Resource Handling
+
+Look for:
+
+* swallowed exceptions;
+* overly broad exception handling;
+* failures converted into silently incorrect results;
+* lost error context;
+* retries that can duplicate side effects;
+* cleanup skipped on exceptions or early returns.
+
+When relevant, verify lifecycle handling for files, sockets, database connections, subprocesses, locks, temporary files, and accelerator resources.
+
+Do not recommend defensive error handling without a concrete failure mode.
+
+## Concurrency
+
+When the change involves threads, processes, asynchronous execution, or shared state, inspect:
+
+* races;
+* ordering assumptions;
+* atomicity;
+* cancellation;
+* shared mutation;
+* duplicated work;
+* deadlocks;
+* partial completion;
+* exception propagation.
+
+Do not flag concurrency merely because it is complex. Identify a concrete unsafe interaction.
+
+## Boundaries and Compatibility
+
+Pay attention where assumptions cross boundaries, such as:
+
+* parser → internal representation;
+* serializer → external format;
+* CPU → GPU;
+* synchronous → asynchronous execution;
+* library → application;
+* application → persistent storage.
+
+Check relevant types, shapes, units, coordinate systems, encoding, ownership, and lifetime.
+
+When interfaces change, inspect relevant consumers before claiming breakage.
+
+Do not demand backward compatibility unless the repository actually requires it.
+
+## Tests
+
+Use tests to understand intended behavior, invariants, and regression risk.
+
+Recommend a test when it protects an important contract, subtle behavior, edge case, or plausible regression.
+
+Do not request tests merely because code changed.
+
+Avoid tests that only duplicate implementation details.
+
+## Uncertainty
+
+Distinguish demonstrated bugs from risks that still require verification.
+
+State missing assumptions explicitly.
+
+Never present speculation as fact.
+
+## Default Rule
+
+Before reporting a correctness finding, answer:
+
+> Under what realistic condition does this implementation violate its intended contract?
+
+If that cannot be explained, the concern may be a design issue rather than a correctness bug.

genome_spy_python-0.1.0/.agents/skills/proper-code-review/references/design.md

@@ -0,0 +1,161 @@
+# Design Review
+
+Evaluate simplicity, readability, maintainability, abstraction, coupling, cohesion, change locality, and architectural fit together.
+
+The goal is low total cognitive and maintenance burden, not minimum line count or maximum reuse.
+
+## Core Rule
+
+Every added concept has a cost.
+
+Examples include:
+
+* classes and interfaces;
+* factories and registries;
+* wrappers and adapters;
+* callbacks and indirection;
+* configuration layers;
+* caching and shared state;
+* concurrency;
+* generic frameworks.
+
+Require that added complexity provides a concrete benefit such as:
+
+* correctness or invariant enforcement;
+* representing real variation;
+* removing duplicated domain knowledge;
+* improving change locality;
+* meaningful reuse;
+* isolating genuinely volatile behavior;
+* material performance or scalability.
+
+Be skeptical of complexity justified mainly by hypothetical future requirements.
+
+## Simplicity
+
+Prefer the least complicated implementation that adequately solves the current problem.
+
+When appropriate, prefer:
+
+* functions over classes when state or polymorphism is unnecessary;
+* direct control flow over indirection;
+* ordinary data structures over custom abstractions;
+* small named helpers when they reduce cognitive load;
+* existing repository mechanisms over new parallel systems.
+
+Do not equate simplicity with fewer lines, fewer functions, or no abstraction.
+
+An abstraction is useful when it reduces total reasoning and maintenance burden more than it adds conceptual or navigation cost.
+
+## Abstraction and Duplication
+
+Do not abstract merely because code looks similar.
+
+Ask:
+
+> Does this represent the same knowledge and therefore need to evolve together?
+
+If multiple locations must remain synchronized, centralizing that knowledge may improve maintainability.
+
+If pieces only look similar but may evolve independently, keeping them separate can be simpler.
+
+Distinguish:
+
+* **Useful abstraction** — represents real shared semantics or variation.
+* **Premature abstraction** — models hypothetical future variation.
+* **Wrong abstraction** — couples concepts that change for different reasons.
+
+A small amount of duplication can be preferable to the wrong abstraction.
+
+## Readability
+
+Code should make intent, control flow, assumptions, and state understandable without excessive mental simulation.
+
+Look for:
+
+* unclear intent;
+* deeply nested or hidden control flow;
+* non-obvious mutation;
+* excessive indirection;
+* functions mixing unrelated conceptual levels;
+* names that hide domain meaning.
+
+Extract helpers when they name meaningful operations, isolate tricky logic, or reduce cognitive load.
+
+Do not extract code solely because a function is long.
+
+Prefer comments that explain rationale, constraints, or domain knowledge rather than restating the implementation.
+
+## Maintainability and Change Locality
+
+Prefer designs where conceptual changes remain localized.
+
+Look for:
+
+* duplicated domain rules;
+* repeated mappings or configuration;
+* parallel conditionals that must remain synchronized;
+* equivalent state represented in multiple layers;
+* unclear ownership;
+* unnecessary knowledge of another component's internals.
+
+Ask:
+
+> How many places must change when this concept changes?
+
+Multiple edits are not automatically bad. The concern is multiple independent representations of the same knowledge.
+
+## Cohesion and Coupling
+
+Related behavior should live together.
+
+Ask whether a developer would naturally look for the behavior where it currently lives.
+
+Flag coupling when implementation details leak across boundaries or unrelated changes propagate through the system.
+
+Do not automatically respond with interfaces, dependency injection, or additional abstraction. Recommend new machinery only when it solves the concrete problem more simply.
+
+## Architectural Fit
+
+Review the change in repository context.
+
+Check whether it:
+
+* duplicates an existing utility or subsystem;
+* introduces a second mechanism for the same problem;
+* bypasses established ownership boundaries;
+* adds concepts disproportionate to surrounding code.
+
+Prefer existing patterns when they are adequate, but do not preserve a clearly harmful pattern merely for consistency.
+
+## Change Blast Radius
+
+Consider whether the breadth of the implementation is proportional to the conceptual change.
+
+Ask:
+
+> How much of the repository had to know about this change?
+
+Be concerned when a small conceptual change requires synchronized modifications across unrelated layers because the same concept is represented repeatedly.
+
+Do not penalize a large diff merely for being large.
+
+## Accretion
+
+Watch for systems that grow through repeated:
+
+* special cases;
+* flags;
+* compatibility branches;
+* wrappers;
+* alternate execution paths.
+
+Ask whether existing logic can be simplified, removed, or generalized instead of adding another layer.
+
+## Default Rule
+
+When multiple implementations are correct and sufficiently performant:
+
+> Prefer the implementation with the lowest total cognitive and maintenance burden.
+
+Complexity must justify itself.