Hello Bioinformatics lovers,

Tommy here.

Last week Claude Code offered to rename every FASTQ from a 1.2 TB SHARE-seq run with symlinks. I hit reject and asked why.

I’ve run bcl2fastq many times, and I know what a symlink is. Those two basics changed how the run went.

btw, to help me create the content you find valuable, please take 2 min to complete this short survey on google form.

The error

We converted BCL to FASTQ with bcl2fastq and started the SHARE-seq pipeline. The first QC step failed its naming check:

No fastq with matched naming format detected

The pipeline expected S1_R1_001.fastq.gz. bcl2fastq had written Undetermined_S0.

Claude Code proposed four symlinks named S1, one each for R1, R2, I1 and I2. That costs almost nothing compared with rewriting 1.2 TB.

To me, Undetermined meant trouble. Those are reads that matched no sample index, which usually points to a bad sample sheet or a flipped i5. So I asked why.

Undetermined was the plan

In SHARE-seq, the I1 read is 99 bp. It holds three 8-bp cell barcodes from three rounds of split-pool barcoding, separated by linkers. bcl2fastq sorts reads by a fixed list of sample indexes.

It can’t sort them across 96 × 96 × 96 = 884,736 barcode combinations. So our sample sheet listed no samples, and every read went to Undetermined by design.

The pipeline does the demultiplexing itself from the I1 and I2 FASTQs:

• The i5 index splits modality: P1.01 to P1.08 for ATAC, P1.09 to P1.16 for RNA.
• The I1 barcodes split cells.

One file set holding both modalities is the intended input.

Make the agent show its evidence

When I asked, Claude Code checked the data:

• 64.7% of reads matched all four barcodes exactly.
• All 16 P1 indexes were present.
• R1.001 to R1.095 matched our plate wells.

A good “why” gets you numbers from your own data.

Fix the source

The symlinks were harmless. A symlink is a new name pointing to the same bytes, so they were safe for the 1.2 TB already on disk. I still didn’t want a symlink step in every future run.

So I suggested having bcl2fastq write the S1 name itself. The fix is a sample sheet with one sample and no index columns.

Every read goes to that sample, and out comes A23NVVVLT3_S1_R1/2_001.fastq.gz plus the I1 and I2 files.

bcl2fastq --sample-sheet SampleSheet.allReads.csv \
--create-fastq-for-index-reads --no-lane-splitting ...

What the basics bought me

My bcl2fastq experience made Undetermined look wrong. My hunch was off, but asking made Claude Code show its evidence, and I learned how SHARE-seq gets demultiplexed. My symlink knowledge let me judge the workaround myself, and that pushed us to fix the sample sheet.

Without those basics, I’d have clicked approve.

The run would have worked and I’d have learned nothing. AI amplifies the foundation you bring.

Try this

• Run bcl2fastq by hand once.
• Know what ln -s does.
• When output looks off, ask why before you approve.
• Make the agent show evidence from your data.

When did you last reject an AI suggestion, and what did asking why teach you? Hit reply. I read every one.

Tommy aka crazyhottommy

PS:

If you want to learn Bioinformatics, there are four ways that I can help:

1. My free YouTube Chatomics channel, make sure you subscribe to it.
2. I have many resources collected on my github here.
3. I have been writing blog posts for over 10 years https://divingintogeneticsandgenomics.com/​
4. Lastly, publish everyday on Linkedin https://www.linkedin.com/in/%F0%9F%8E%AF-ming-tommy-tang-40650014/recent-activity/all/ Follow me there!

Stay awesome!