bio-genome-engineering-hdr-template-design

What this skill does

## Version Compatibility

Reference examples tested with: BioPython 1.83+, primer3-py 2.0+.

Before using code patterns, verify installed versions match. If versions differ:
- Python: `pip show <package>` then `help(module.function)` to check signatures

If code throws ImportError, AttributeError, or TypeError, introspect the installed package and adapt the example to match the actual API rather than retrying.

primer3-py designs PRIMERS (use `primer3.bindings.design_primers(seq_args, global_args)`; the camelCase `designPrimers` is deprecated since 1.0.0), not homology arms -- arm extraction and codon-aware blocking are the skill's own BioPython code. Design arms and guide against the **actual cell line's sequence**, not GRCh38 -- a SNP in an arm reduces annealing and a SNP in the PAM/seed can mean the guide does not cut.

# HDR Template Design

**"Design a donor for my CRISPR knock-in"** -> Decide the format by edit size and whether the cell cycles, size the arms, confirm a guide cuts within ~10 bp of the edit, and add a codon-checked blocking mutation so the corrected allele cannot be re-cut.
- Python: arm extraction + codon-aware PAM/seed blocking with `Bio.Seq`; `primer3.bindings.design_primers()` for arm-amplification and junction-validation primers
- Decision: format/route by cell type (cycling vs post-mitotic) and insert size

## The Single Most Important Modern Insight -- HDR is the minority pathway, and a donor without a blocking mutation is a self-destructing one

A Cas9 double-strand break is repaired by whichever pathway wins a kinetic race, and in most cells the winner is **classical NHEJ** (fast, all cell-cycle phases). MMEJ (microhomology, S/G2) and **HDR (template-dependent, S/G2 only)** are minority players, so **unenhanced HDR knock-in is typically single-digit to low-double-digit percent -- that is normal, not a failure.** The donor is not "the sequence to insert"; it is the toolkit for tilting a race NHEJ is structurally favored to win. The corollary, and the field's most expensive misread: **a donor with perfect arms but no blocking mutation gets its successful edit erased** -- the corrected allele still has an intact protospacer + PAM, so Cas9 re-cuts it and NHEJ scars it, and the indel reads out as "HDR failed" (indistinguishable from low HDR). So when someone reports "low HDR, lots of indels," the first question is not "how long are the arms?" -- it is **"does the donor disrupt the PAM or seed?"** A blocking mutation is mandatory and must be codon-checked; without it the readout is re-cutting, not HDR.

## The Pathway Competition (everything follows from this)

| Pathway | Cell cycle | Template | Signature | Relevance |
|---------|-----------|----------|-----------|-----------|
| **c-NHEJ** | all phases (dominant) | none | indels | the competitor; the engine HITI exploits |
| **MMEJ / alt-EJ** (Pol theta) | S/G2 | 5-25 bp microhomology | microhomology-flanked deletions | the PITCh route |
| **HDR / HR** | **S/G2 only** | sister chromatid or **exogenous donor** | precise, scarless | the classic knock-in route; minority |
| SSA | S/G2 | repeats | deletion between repeats | nuisance |

End resection (cell-cycle-gated, licensed in S/G2; 53BP1-RIF1 protects ends/pro-NHEJ, BRCA1 antagonizes it/pro-HDR) decides the fork. Consequences: **post-mitotic cells barely do HDR** -> for neurons/muscle/in-vivo tissue, HITI/HMEJ (NHEJ-based) is the *correct first choice*, not a fallback. Timing RNP+donor delivery into S/G2 raises HDR (Lin 2014, up to ~38% in HEK293T) -- the donor is necessary but the cell-cycle state gates it.

## Donor Format Decision

| Format | Insert | Arms | Best for | Caveat |
|--------|--------|------|----------|--------|
| **ssODN** | <= ~50 bp edits | ~30-60 nt each (total ~120-200 nt) | point mutations, small tags, loxP | synthesis ceiling ~200 nt; strand choice contested |
| **long ssDNA (Easi-CRISPR)** | ~0.2-2 kb | ~50-100 nt | cassettes, floxed/conditional alleles, zygote KI | **less toxic & less random integration than dsDNA**; harder to make |
| dsDNA (PCR/linear) | ~0.1-1.5 kb | ~200-800 bp | medium cassettes | **dsDNA is toxic** (innate sensing) + random integration |
| plasmid / HMEJ | up to several kb | ~500-2000 bp | large insertions, conditional alleles | backbone integration risk; slowest |
| **AAV6** | <= ~4.5 kb (ITR-to-ITR, arms included) | ~400 bp-1 kb | hard-to-transfect primary cells (HSPC, T, iPSC), in vivo | manufacturing cost; cargo cap is a hard wall |

Heuristics: point/small edit -> ssODN; 0.2-2 kb -> **lssDNA over dsDNA** (cleaner) for animal/zygote work; large cassette -> plasmid/HMEJ (lines) or **AAV6+RNP** (primary cells); **post-mitotic -> HITI**.

## Homology Arms, Edit-to-Cut Distance, and the Blocking Mutation (the most-botched trio)

- **Arm length:** ssODN ~30-60 nt each (more does not help, costs synthesis); dsDNA/plasmid ~500-800 bp sweet spot. Match the **actual cell-line sequence**, not the reference.
- **Edit-to-cut distance drives guide choice:** HDR incorporation falls sharply with distance, so place the cut **within ~10 bp of the edit** (Paquet 2016). The guide and donor are a *joint* design -- a "great" guide cutting 25 bp away is worse than a mediocre one cutting 3 bp away. **If no guide cuts within ~10 bp, HDR is the wrong tool** -> reconsider base/prime editing.
- **Blocking mutation (mandatory, codon-checked):** disrupt the **PAM** synonymously (preferred -- change a G in the NGG at a wobble position); if the PAM has no synonymous option, introduce **silent seed-region** mutations (PAM-proximal ~10-12 nt; PAM-distal mismatches are tolerated and do not block). The blocking edit must sit within the ~10 bp incorporation window (which is also where it blocks best). Paquet 2016 (CORRECT) raises per-allele accuracy ~10-fold and allows zygosity control by distance.

## ssODN Strand & Asymmetry (an over-cited rule) + the reliable win

Richardson 2016 proposed an ssODN **complementary to the non-target strand**, **asymmetric with the longer arm PAM-proximal (~91 nt) and the shorter PAM-distal (~36 nt)**. Subsequent systematic work could **not** reproduce this as universal: the optimal strand flips by locus and the asymmetric advantage often vanishes once both arms are >=30 nt. Treat it as a **prior to test, not a law** -- generate both strands and symmetric+asymmetric variants and test them. By contrast, **phosphorothioate (PS) end-protection (2-3 terminal bases each end)** is a near-universal cheap win (exonuclease resistance) -- encode these at opposite confidence levels.

## MMEJ / Homology-Independent Routes (when HDR is the wrong tool)

- **PITCh / CRIS-PITCh (MMEJ, Nakade 2014):** ~5-25 bp microhomologies instead of long arms; Pol theta joins donor to genome. Appeal is purely donor-construction convenience (microhomologies are primer overhangs); cost is error-prone junctions.
- **HITI (Suzuki 2016):** **homology-INDEPENDENT, NHEJ-based -> works in non-dividing cells.** The donor carries the same Cas9 target site(s) in **reverse orientation** flanking the insert; wrong-orientation insertions reconstitute the site and get re-cut/ejected, right-orientation insertions destroy it and lock in. Junctions can carry small indels.
- **HMEJ (Yao 2017):** ~800 bp arms PLUS flanking gRNA sites that linearize the donor in vivo; higher KI than HR/NHEJ/MMEJ in some contexts but ties/loses in others (mESC, N2a) -- test at the target locus.

| Situation | Route |
|-----------|-------|
| Point/small edit, cycling cells | ssODN + HDR (with blocking mutation) |
| Medium/large cassette, cycling line | HDR (lssDNA/plasmid) or HMEJ |
| Large cassette, primary cells (HSPC/T/iPSC) | AAV6 donor + RNP + HDR |
| Clean zygote/animal KI, <=2 kb | lssDNA Easi-CRISPR + HDR |
| Trivial donor construction wanted | PITCh (MMEJ) |
| **Non-dividing / post-mitotic / in vivo** | **HITI** (or HMEJ) |
| Edit far from any cut / single base | -> base-editing-design or prime-editing-design (donor-free) |

## HDR En