| name | protocol-migration |
| description | Convert legacy/source.md into README.md using the repository template, using source.txt only as fallback and marking uncertainty with CHECK:. |
Use this skill when migrating a legacy protocol into this repository template.
Goal:
Convert legacy/source.md into README.md, using the existing README.md as the target template and structure.
Primary rule
Do not change protocol meaning.
Use legacy/source.md as the primary source when rewriting README.md.
Use legacy/source.txt only as a fallback when legacy/source.md looks malformed, incomplete, or unclear.
Use the PDF file in legacy/ as the final reference source of truth for tables, figures, layout-dependent content, and anything still ambiguous.
Treat image references in legacy/source.md and files in legacy/images/ as extracted protocol content, not decorative artifacts, until they have been reviewed.
If legacy/source.md and legacy/source.txt disagree, prefer legacy/source.md for general structure and prose, but use the original PDF as the final tie-breaker.
Migration behavior
When converting legacy protocol content into the repository template:
- Preserve all protocol content.
- Preserve all procedural content, warnings, notes, reagent names, quantities, timings, temperatures, and conditions, preserving their location.
- Do not change scientific meaning.
- Do not invent missing information.
- Do not invent missing values or steps.
- Do not delete any content from the source.
- Do not silently summarize, compress, or merge steps.
- Keep exact reagent names, quantities, temperatures, timings, and conditions unless only formatting is being normalized.
- Preserve exact reagent and equipment names unless only formatting is changing.
- Preserve the step order from the source unless the source clearly indicates otherwise.
- Do not delete repeated warnings or notes.
- If any text does not fit cleanly into the template, place it under
# Migration notes or ## Unplaced content.
- Mark uncertainty with
CHECK: instead of guessing.
Images, figures, and image-based tables
PDF-to-Markdown conversion may extract protocol-relevant content as images, especially tables, thermocycler programs, reagent layouts, flow diagrams, gel/example images, or figure panels.
Before drafting README.md, do a mandatory image/table pass. Do not finish the migration until every image reference in legacy/source.md and every file in legacy/images/ has been accounted for as converted, retained, omitted, or uncertain.
When migrating:
- Scan
legacy/source.md for image references such as , and inspect legacy/images/ for extracted images.
- For each extracted image, decide whether it is a table-like protocol artifact, another protocol-relevant visual, decorative/non-protocol content, or a duplicate.
- Keep images that contain protocol content needed to perform or interpret the protocol.
- Omit only clearly decorative images such as logos, icons, page chrome, ornamental separators, or duplicated images that add no protocol content.
- Convert image-based tables into Markdown tables when all headers, rows, values, units, grouping, and notes are legible and unambiguous. This is required; do not leave a legible image-based table as an image merely because the source was extracted as an image.
- Preserve row grouping and cycle counts from thermocycler/program tables. If Markdown cannot represent the original grouping cleanly, add a short note or use repeated values rather than losing meaning.
- Do not OCR or transcribe illegible values by guesswork. If any value, header, grouping, or placement is uncertain, keep the image and add
CHECK:.
- If an image contains non-tabular protocol content that cannot be safely converted to text, include the image in
README.md.
- Place converted tables or retained images at the same logical location as the source image, near the step or section they support.
- In
README.md, image paths must be valid from the repository root. Change extracted paths from images/<file> to legacy/images/<file> unless the image has deliberately been moved.
- Use descriptive alt text, for example
, not empty alt text.
- Mention in
# Migration notes which extracted images were converted to Markdown tables, which were retained as images, which were omitted as non-protocol/decorative, and which require CHECK:.
Allowed formatting normalization
You may normalize formatting only when the meaning is unchanged and unambiguous:
- Add a space between numbers and units.
- Standardize temperature formatting to
37 °C.
- Standardize volume units to
µL, mL, L, using the micro sign µ consistently.
- Standardize concentration units to
mM, µM, nM, % (w/v), etc., using the micro sign µ consistently.
- Standardize time units to full words:
seconds, minutes, hours.
- Standardize chemical names to match the source but with consistent formatting (e.g.
Tris-HCl instead of Tris HCl).
- Standardize pH formatting to
pH 7.4.
- Standardize chemical formulas with HTML subscripts, for example H2O to H2O. Similarly for other chemical formulas (e.g. MgCl2 to MgCl2).
- Do not use Unicode subscript characters such as
₂.
- Standardize
RNAseq or RNA-Seq to RNA-seq. Same for ChIP-seq, ATAC-seq, etc.
- Use numbered lists for procedural actions in sequence. For other non-procedural content, bullets are better. Note-like text such as Note, NB, Optional, Recommended, and Warning should use blockquote style such as
> **Note**.
- Normalize bullet formatting and markdown table formatting.
- Normalize heading structure to match the repository template.
- For reaction mixes and anything tabular, place them inside a table as in template.
- For image-based tables, convert to Markdown tables wherever this is legible and unambiguous; otherwise retain the image at the correct protocol location with
CHECK: explaining why it could not be safely converted.
- Normalize markdown headings, bullets, and tables.
- "Note" or "NOTE" or "NB" or "Optional" or "Recommended" or "Warning" are normalized to start with
> (example > **Note**) and are placed immediately after the step they refer to, or at the end of the protocol if they clearly refer to the whole protocol.
- Remove empty columns from tables.
- Synchronize
Contents with actual headings in the protocol.
Disallowed changes
- Do not infer omitted concentrations, times, temperatures, or volumes.
- Do not infer values for missing quantities.
- Do not try to calculate or infer values that are not explicitly stated.
- Do not convert
overnight, RT, briefly, room temperature or similar vague language into precise values.
- Do not replace vague language with precise values.
- Do not reorder steps unless the source clearly numbers them in that order.
- Do not remove duplicate-looking content unless it is truly identical and both copies are preserved in review notes.
- Do not rewrite scientific wording for style if that risks changing meaning.
- Do not fill in table cells with values that are missing from the source.
- Do not replace one reagent name with another.
- Do not remove repeated warnings or notes.
- Do not omit unmapped text.
- Do not omit protocol-relevant images, image-based tables, figures, diagrams, or visual instructions.
Output requirements
- edit
README.md
- use the template headings exactly
- use the template headings in
README.md
- keep all source content
- add
CHECK: markers for uncertainty
- use
CHECK: only for genuine unresolved uncertainty. If no uncertainty remains, do not mention CHECK: at all
- add
# Migration notes
- after drafting, add a short summary in
# Migration notes covering:
- formatting normalizations performed
- ambiguities and uncertainty flagged
- content placed in
## Unplaced content
- add
# Migration notes including:
- imported protocol metadata from
source-metadata.yml, using only the non-blank lines
- template_version from
template-metadata.yml
- ambiguous mappings
- normalized formatting changes
- extracted images converted to Markdown tables
- extracted images retained in
README.md
- extracted images omitted because they were decorative or duplicated non-protocol content
- extracted images that could not be confidently classified or converted, marked with
CHECK:
- content copied verbatim but not confidently placed
- keep
[](https://github.com/ulelab/protocol-template) at the top of the file
- remove the template instruction note
- delete the "Template repository: Click
Use this template to create a new protocol repo..." note
Verification
After drafting, verify the migration against the source:
- compare the migrated
README.md against legacy/source.md
- compare any malformed, incomplete, or ambiguous passages against
legacy/source.txt
- compare the migrated
README.md against the PDF in legacy/ for tables, figures, layout-dependent content, and any remaining ambiguity
- compare every protocol-relevant image reference in
legacy/source.md and every relevant file in legacy/images/ against the migrated README.md
- check that all protocol steps, notes, warnings, reagent names, quantities, temperatures, timings, and conditions are still present
- check that image-based tables were converted accurately or retained as images with valid
legacy/images/... paths
- check that no protocol-relevant figure, table image, diagram, gel/example image, or visual instruction was silently omitted
- check that no source content has been silently omitted, merged, or reordered without justification
- check any tables, layout-dependent content, or ambiguous sections against the PDF in
legacy/
- leave
CHECK: anywhere the mapping is uncertain rather than guessing
Verification checklist:
README.md still matches the scientific content of legacy/source.md- any malformed, incomplete, or ambiguous passages were cross-checked against
legacy/source.txt
- no protocol steps or warnings were omitted
- no values were invented or made more precise than in the source
- tables and layout-dependent content were checked against the PDF in
legacy/
- protocol-relevant extracted images were either converted to Markdown tables or retained at the correct location
- retained image links resolve from
README.md
- any uncertain mappings are marked with
CHECK:
- any meaningful normalization choices are noted in
# Migration notes
Prefer preserving meaning over making the output prettier.
