| name | duckhts-rewrite-porting |
| description | Guides exact-compatible rewrites and ports of existing genomics tools into DuckHTS, with pinned upstream validation, attribution, phased scope, and rewrites.bio-style discipline. Use when implementing or maintaining compatibility layers such as mosdepth-, bcftools-, or WisecondorX-aligned behavior in duckhts. |
DuckHTS Rewrite and Porting
Use this skill when DuckHTS is porting, rewriting, or emulating behavior from an existing genomics tool.
Typical cases:
duckhts_mosdepth(...)bcftools_liftoverbcftools_scorebcftools_munge_row- WisecondorX-style streaming dedup logic
This skill exists because compatibility rewrites are not ordinary feature work. They need pinned targets, explicit validation, and visible attribution.
Core rule
Do not build “something inspired by X” when the repo goal is “rewrite X behavior for a declared scope”.
Follow rewrites.bio-style discipline:
- credit the original authors
- emulate exactly for the declared scope
- pin upstream version/commit
- validate continuously against upstream
- state scope and exclusions explicitly
- expand in phases
Mandatory first reads
AGENTS.md- the relevant
design/*.md file
.sync/ mirror for the upstream tool, when present- existing SQL and tinytest coverage
- any validation scripts already in the repo
If the task touches mosdepth behavior, read:
design/duckhts_mosdepth.md
If the task touches WisecondorX-style dedup behavior, also read any referenced notes/scripts and the repo guidance pointing to RWisecondorX/AGENTS.md.
Rewrite checklist
Before implementing, record:
- upstream tool name
- exact upstream version
- pinned tag or commit
- local validation date
- compatibility scope for v1
- explicitly deferred features
- exact output/semantic contract that must match
- validation commands or scripts
Source priority
Use sources in this order:
.sync/ mirror in the repo, when present- pinned upstream checkout/source files
- official upstream docs and issues
- secondary blogs/posts only after source review
Do not substitute memory for upstream source.
Implementation strategy
Think big, work small.
- design the full compatibility target
- implement a narrow, testable slice
- validate against upstream
- add regression tests for mismatches found
- extend scope incrementally
Compatibility work should prefer:
- explicit helper functions
- isolated compatibility-specific code paths
- validation scripts that compare to upstream
- feature gating by declared scope instead of half-working generalization
What must not happen
Do not:
- silently change output formats while claiming compatibility
- claim compatibility with an unpinned upstream version
- replace exact validation with “seems similar” checks
- bury attribution or citation requirements
- mix compatibility-specific behavior into unrelated generic APIs unless the design explicitly requires it
Testing requirements
Every compatibility rewrite needs:
- SQL conformance tests in
test/sql/
- R wrapper/package tests in
r/Rduckhts/inst/tinytest/
- upstream comparison or conformance validation where applicable
If exact byte identity is not required, document what equivalence means.
Documentation requirements
Public docs should include:
- explicit upstream credit
- citation guidance where scientifically relevant
- exact version/commit validated against
- exact scope of compatibility
- explicit statement of deferred/unsupported features
- AI assistance disclosure if repo guidance requires it
Related skills
References
