diff --git a/.agents/skills/protocol-migration/SKILL.md b/.agents/skills/protocol-migration/SKILL.md
index fc2d684..975ef47 100644
--- a/.agents/skills/protocol-migration/SKILL.md
+++ b/.agents/skills/protocol-migration/SKILL.md
@@ -57,24 +57,18 @@ When migrating:
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`).
+- Use full-word time units: `seconds`, `minutes`, `hours`.
+- Use standard units and spacing, for example `37 °C`, `10 µL`, `1 mM`, `100 nM`.
- 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).
+- Standardize chemical names without changing meaning, for example `Tris-HCl` instead of `Tris HCl`.
+- Standardize chemical formulas with HTML subscripts, for example H2O to H2O and 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.
+- Standardize names such as `RNAseq` or `RNA-Seq` to `RNA-seq`, and similarly for `ChIP-seq`, `ATAC-seq`, and related names.
+- Use numbered lists for procedural actions in sequence, bullets for non-procedural lists, and tables for reaction mixes or other tabular content.
+- Normalize note-like labels such as Note, NB, Optional, Recommended, and Warning to blockquote style, for example `> **Note:**`.
+- Normalize headings, bullets, Markdown tables, and `Contents` links to match the repository template.
+- Convert image-based tables to Markdown tables when legible and unambiguous; otherwise retain the image with `CHECK:`.
- Remove empty columns from tables.
-- Synchronize `Contents` with actual headings in the protocol.
## Disallowed changes
- Do not infer omitted concentrations, times, temperatures, or volumes.
@@ -92,30 +86,23 @@ You may normalize formatting only when the meaning is unchanged and unambiguous:
- 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:
+- Only edit `README.md`.
+- Use the template headings exactly.
+- Keep all source content.
+- Keep the Ule Lab Protocol Template attribution badge at the top of the file, but do not add or preserve a template release-version badge.
+- Remove the template instruction note and the "Template repository: Click `Use this template`..." note.
+- Add `CHECK:` markers only for genuine unresolved uncertainty.
+- Add an `# Migration notes` section covering:
+ - imported protocol metadata from `source-metadata.yml`, using only non-blank lines
+ - `template_version` from `template-metadata.yml`
- 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:`
+ - extracted images that could not be confidently classified or converted
- 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:
diff --git a/.claude/skills/protocol-migration/SKILL.md b/.claude/skills/protocol-migration/SKILL.md
index fc2d684..975ef47 100644
--- a/.claude/skills/protocol-migration/SKILL.md
+++ b/.claude/skills/protocol-migration/SKILL.md
@@ -57,24 +57,18 @@ When migrating:
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`).
+- Use full-word time units: `seconds`, `minutes`, `hours`.
+- Use standard units and spacing, for example `37 °C`, `10 µL`, `1 mM`, `100 nM`.
- 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).
+- Standardize chemical names without changing meaning, for example `Tris-HCl` instead of `Tris HCl`.
+- Standardize chemical formulas with HTML subscripts, for example H2O to H2O and 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.
+- Standardize names such as `RNAseq` or `RNA-Seq` to `RNA-seq`, and similarly for `ChIP-seq`, `ATAC-seq`, and related names.
+- Use numbered lists for procedural actions in sequence, bullets for non-procedural lists, and tables for reaction mixes or other tabular content.
+- Normalize note-like labels such as Note, NB, Optional, Recommended, and Warning to blockquote style, for example `> **Note:**`.
+- Normalize headings, bullets, Markdown tables, and `Contents` links to match the repository template.
+- Convert image-based tables to Markdown tables when legible and unambiguous; otherwise retain the image with `CHECK:`.
- Remove empty columns from tables.
-- Synchronize `Contents` with actual headings in the protocol.
## Disallowed changes
- Do not infer omitted concentrations, times, temperatures, or volumes.
@@ -92,30 +86,23 @@ You may normalize formatting only when the meaning is unchanged and unambiguous:
- 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:
+- Only edit `README.md`.
+- Use the template headings exactly.
+- Keep all source content.
+- Keep the Ule Lab Protocol Template attribution badge at the top of the file, but do not add or preserve a template release-version badge.
+- Remove the template instruction note and the "Template repository: Click `Use this template`..." note.
+- Add `CHECK:` markers only for genuine unresolved uncertainty.
+- Add an `# Migration notes` section covering:
+ - imported protocol metadata from `source-metadata.yml`, using only non-blank lines
+ - `template_version` from `template-metadata.yml`
- 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:`
+ - extracted images that could not be confidently classified or converted
- 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:
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 2bf6589..d84b620 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -49,24 +49,18 @@ When migrating:
## 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`).
+- Use full-word time units: `seconds`, `minutes`, `hours`.
+- Use standard units and spacing, for example `37 °C`, `10 µL`, `1 mM`, `100 nM`.
- 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).
+- Standardize chemical names without changing meaning, for example `Tris-HCl` instead of `Tris HCl`.
+- Standardize chemical formulas with HTML subscripts, for example H2O to H2O and 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.
+- Standardize names such as `RNAseq` or `RNA-Seq` to `RNA-seq`, and similarly for `ChIP-seq`, `ATAC-seq`, and related names.
+- Use numbered lists for procedural actions in sequence, bullets for non-procedural lists, and tables for reaction mixes or other tabular content.
+- Normalize note-like labels such as Note, NB, Optional, Recommended, and Warning to blockquote style, for example `> **Note:**`.
+- Normalize headings, bullets, Markdown tables, and `Contents` links to match the repository template.
+- Convert image-based tables to Markdown tables when legible and unambiguous; otherwise retain the image with `CHECK:`.
- Remove empty columns from tables.
-- Synchronize `Contents` with actual headings in the protocol.
## Disallowed changes
- Do not infer omitted concentrations, times, temperatures, or volumes.
@@ -85,27 +79,23 @@ You may normalize formatting only when the meaning is unchanged and unambiguous:
## Output requirements
When drafting a migrated protocol:
+- Only 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 an `# Migration notes` section listing:
+- Keep the Ule Lab Protocol Template attribution badge at the top of the file, but do not add or preserve a template release-version badge.
+- Remove the template instruction note and the "Template repository: Click `Use this template`..." note.
+- Add `CHECK:` markers only for genuine unresolved uncertainty.
+- Add an `# Migration notes` section covering:
+ - imported protocol metadata from `source-metadata.yml`, using only non-blank lines
+ - `template_version` from `template-metadata.yml`
- formatting normalizations performed
- ambiguities and uncertainty flagged
- content placed in `## Unplaced content`
- - 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.
-- Delete the "Template repository: Click `Use this template` to create a new protocol repo..." note.
-- Remove the template instruction note.
+ - 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
+ - content copied verbatim but not confidently placed
## Verification
After drafting, verify the migration against the source:
diff --git a/.github/workflows/pdf_header.tex b/.github/workflows/pdf_header.tex
index 43fea5c..864636c 100644
--- a/.github/workflows/pdf_header.tex
+++ b/.github/workflows/pdf_header.tex
@@ -30,11 +30,20 @@
\pagestyle{fancy}
\fancyhf{}
+\setlength{\headheight}{14pt}
-\fancyhead[L]{\small\href{\repoURL}{\nolinkurl{\repoURL}}}
-\fancyhead[R]{\small\textbf{Commit:} \href{\commitURL}{\githash}\ \textbar\ \texttt{\gitactor}}
+\fancyhead[L]{%
+ \begin{minipage}[t]{0.54\textwidth}
+ \raggedright\scriptsize\href{\repoURL}{\nolinkurl{\repoURL}}
+ \end{minipage}%
+}
+\fancyhead[R]{%
+ \begin{minipage}[t]{0.44\textwidth}
+ \raggedleft\scriptsize\textbf{Commit:} \href{\commitURL}{\githash}\ \textbar\ \texttt{\gitactor}
+ \end{minipage}%
+}
\fancyfoot[C]{\thepage}
\renewcommand{\headrulewidth}{0.4pt}
-\renewcommand{\footrulewidth}{0pt}
\ No newline at end of file
+\renewcommand{\footrulewidth}{0pt}
diff --git a/.github/workflows/readme-to-pdf.yml b/.github/workflows/readme-to-pdf.yml
index 5e6b89f..905c6fb 100644
--- a/.github/workflows/readme-to-pdf.yml
+++ b/.github/workflows/readme-to-pdf.yml
@@ -113,6 +113,11 @@ jobs:
-e 's/`\[X\]`/\\FAILstatus{}/g' \
README._pdf.md > README._pdf.tmp && mv README._pdf.tmp README._pdf.md
+ - name: Render HTML subscripts for PDF only
+ run: |
+ set -euo pipefail
+ sed -E 's|([^<]+)|\\textsubscript{\1}|g' README._pdf.md > README._pdf.tmp && mv README._pdf.tmp README._pdf.md
+
- name: Create PDF metadata definitions
run: |
set -euo pipefail
diff --git a/.github/workflows/validate-protocol.yml b/.github/workflows/validate-protocol.yml
index 2406a3d..a45b745 100644
--- a/.github/workflows/validate-protocol.yml
+++ b/.github/workflows/validate-protocol.yml
@@ -74,11 +74,23 @@ jobs:
python -m unittest discover -s tests -p 'test_*.py'
- name: Run content validation
+ id: content_validation
if: steps.validation_gate.outputs.should_validate == 'true'
+ continue-on-error: true
run: |
python scripts/validate_protocol_content.py README.md
- name: Run style validation
+ id: style_validation
if: steps.validation_gate.outputs.should_validate == 'true'
+ continue-on-error: true
run: |
python scripts/validate_protocol_style.py README.md
+
+ - name: Fail if README validation failed
+ if: ${{ steps.validation_gate.outputs.should_validate == 'true' && (steps.content_validation.outcome != 'success' || steps.style_validation.outcome != 'success') }}
+ run: |
+ echo "README validation failed."
+ echo "Content validation outcome: ${{ steps.content_validation.outcome }}"
+ echo "Style validation outcome: ${{ steps.style_validation.outcome }}"
+ exit 1
diff --git a/README.md b/README.md
index f3fe486..f2d3e8f 100644
--- a/README.md
+++ b/README.md
@@ -1,5 +1,4 @@
[](https://github.com/ulelab/protocol-template)
-[](https://github.com/ulelab/protocol-template/releases)
> Template repository: Click `Use this template` to create a new protocol repo. Template docs are in [docs/USING_THIS_TEMPLATE.md](https://github.com/ulelab/protocol-template/blob/main/docs/USING_THIS_TEMPLATE.md)
# TODO: Protocol title
diff --git a/docs/PROMPT.md b/docs/PROMPT.md
index 50eee0a..015ce6d 100644
--- a/docs/PROMPT.md
+++ b/docs/PROMPT.md
@@ -9,7 +9,7 @@ Apply those instructions even if you are not GitHub Copilot.
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 after checking the generated text sources.
+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.
@@ -51,26 +51,21 @@ When migrating:
- 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
-Normalize formatting only when the meaning is unchanged and unambiguous:
-
-- add a space between numbers and units
-- use `seconds`, `minutes`, `hours`
-- use `µL`, `mL`, `L`
-- use `37 °C` style temperature formatting
-- standardize concentration units to `mM`, `µM`, `nM`, `% (w/v)`, etc., using the micro sign `µ` consistently
-- standardize pH formatting to `pH 7.4`
-- standardize chemical names to match the source but with consistent formatting, for example `Tris-HCl` instead of `Tris HCl`
-- standardize chemical formulas with HTML subscripts, for example H2O to H2O and MgCl2 to MgCl2
-- do not use Unicode subscript characters such as `₂`
-- standardize `RNAseq` or `RNA-Seq` to `RNA-seq`, and similarly for `ChIP-seq`, `ATAC-seq`, and related names
-- 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 bullets, headings, and markdown tables to match the repository template
-- use tables for reaction mixes and other tabular content
-- convert image-based tables 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 note-like text such as Note, NB, Optional, Recommended, and Warning to blockquote style, for example `> **Note**`
-- place note-like text immediately after the step it refers to, or at the end of the protocol if it clearly refers to the whole protocol
-- remove empty columns from tables
-- synchronize `Contents` with the actual headings in the protocol
+You may normalize formatting only when the meaning is unchanged and unambiguous:
+
+- Add a space between numbers and units.
+- Use full-word time units: `seconds`, `minutes`, `hours`.
+- Use standard units and spacing, for example `37 °C`, `10 µL`, `1 mM`, `100 nM`.
+- Standardize pH formatting to `pH 7.4`.
+- Standardize chemical names without changing meaning, for example `Tris-HCl` instead of `Tris HCl`.
+- Standardize chemical formulas with HTML subscripts, for example H2O to H2O and MgCl2 to MgCl2.
+- Do not use Unicode subscript characters such as `₂`.
+- Standardize names such as `RNAseq` or `RNA-Seq` to `RNA-seq`, and similarly for `ChIP-seq`, `ATAC-seq`, and related names.
+- Use numbered lists for procedural actions in sequence, bullets for non-procedural lists, and tables for reaction mixes or other tabular content.
+- Normalize note-like labels such as Note, NB, Optional, Recommended, and Warning to blockquote style, for example `> **Note:**`.
+- Normalize headings, bullets, Markdown tables, and `Contents` links to match the repository template.
+- Convert image-based tables to Markdown tables when legible and unambiguous; otherwise retain the image with `CHECK:`.
+- Remove empty columns from tables.
## Disallowed changes
- do not infer omitted concentrations, times, temperatures, or volumes
@@ -90,28 +85,21 @@ Normalize formatting only when the meaning is unchanged and unambiguous:
## Output requirements
- Only 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 an `# Migration notes` section.
-- After drafting, add a short summary in `# Migration notes` covering:
+- Keep the Ule Lab Protocol Template attribution badge at the top of the file, but do not add or preserve a template release-version badge.
+- Remove the template instruction note and the "Template repository: Click `Use this template`..." note.
+- Add `CHECK:` markers only for genuine unresolved uncertainty.
+- Add an `# Migration notes` section covering:
+ - imported protocol metadata from `source-metadata.yml`, using only non-blank lines
+ - `template_version` from `template-metadata.yml`
- formatting normalizations performed
- ambiguities and uncertainty flagged
- content placed in `## Unplaced content`
-- Include the following in `# Migration notes`:
- - 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:`
+ - extracted images that could not be confidently classified or converted
- 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:
diff --git a/docs/USING_THIS_TEMPLATE.md b/docs/USING_THIS_TEMPLATE.md
index b7ab309..8949e5d 100644
--- a/docs/USING_THIS_TEMPLATE.md
+++ b/docs/USING_THIS_TEMPLATE.md
@@ -32,7 +32,10 @@ If you are new to GitHub, start with this short [GitHub Hello World tutorial](ht
- [Make changes to an existing protocol](#make-changes-to-an-existing-protocol)
- [Use the protocol in the lab](#use-the-protocol-in-the-lab)
- [Release a protocol](#release-a-protocol)
+- [Tips for making the most of the template](#tips-for-making-the-most-of-the-template)
- [Citation information](#citation-information)
+- [Maintainer and contributor notes (template maintainers only)](#maintainer-and-contributor-notes)
+
---
# Create a new protocol repository
@@ -51,6 +54,10 @@ You now have your own copy of the template.
The structure of the template is:
```md
.
+├── .agents
+│ └── skills/protocol-migration/ # Codex migration skill
+├── .claude
+│ └── skills/protocol-migration/ # Claude Code migration skill
├── .github
│ ├── workflows/ # Automation for validations and PDF generation
│ └── copilot-instructions.md # AI-assisted migration instructions
@@ -99,7 +106,7 @@ The main file you must edit for protocol content is `README.md`. **Do not rename
10. The validation GitHub Actions workflow (`validate-protocol-README`) will automatically run on that pull request when `README.md` has changed. It runs a content check for the required title, status line, status legend, key headings, unresolved placeholders, and placeholder step names, plus a style check for unit formatting. If checks fail, fix them before merging into `main`.
11. Ask for a reviewer where possible.
-> **Review scope**: Before opening the pull request, check the changed files. For a routine protocol edit, only `README.md` or `CODEOWNERS` should change. This does not apply to the one-time legacy PDF import workflow, where files in `legacy/` may also be created or updated. If any other files changed, remove those changes or explain clearly why they are needed.
+> **Review scope**: Before opening the pull request, check the changed files. For a routine protocol edit, expected changes are `README.md`, `CODEOWNERS`, and optionally `legacy/source-metadata.yml` when provenance is updated. This does not apply to the one-time legacy PDF import workflow, where files in `legacy/` may also be created or updated. If any other files changed, remove those changes or explain clearly why they are needed.
> **Note**: Always check accuracy and make sure required sections, such as protocol status and the status legend, are present.
@@ -175,7 +182,7 @@ At minimum, make sure your protocol includes:
- a status legend row containing `[OK]`, `[?]`, and `[X]`
- a short description (`# About`)
- contents (`## Contents`)
-- a materials section (`# ... Materials`)
+- a top-level materials section, optionally numbered, for example `# Materials` or `# 7. Materials`
> **Note**: These are mandatory items for validation.
@@ -283,15 +290,10 @@ If you want to adapt or improve an existing protocol on GitHub:
10. If the PDF is not generated within a few minutes (you may need to refresh the page), go to the GitHub **Actions** tab, manually run the `README-to-pdf` workflow, and select your working branch in the **Use workflow from** branch menu.
11. PDF generation creates another commit, usually with a message like `Update .pdf`.
12. Before making any further local changes after pushing, run `git pull`. GitHub Actions may have added a new commit on your branch.
-13. If you have questions about a protocol, or want to propose a change, open a GitHub Issue using the `Protocol issues` template and assign relevant people.
-14. If you are developing a protocol as a team, you can use a GitHub Project.
-15. Use Issues to track optimisation ideas or questions.
-16. Add images, gels, notes or links to code or data to the relevant Issue.
-17. Close the Issue when the question is resolved.
-18. This helps keep a record of what has already been tried.
-19. If your change should become part of the main protocol, open a pull request to `main` and request review from relevant people.
-20. Before requesting review, check the changed files. For a routine protocol edit, only `README.md` or `CODEOWNERS` should change. For a legacy PDF import, files in `legacy/` may also be created or updated. If any other files changed, remove those changes or explain clearly why they are needed.
-21. Do not merge into `main` without review, unless you are the only person using that protocol.
+13. For issue tracking, Projects, branches, commits, pull requests, and Slack notifications, follow [Tips for making the most of the template](#tips-for-making-the-most-of-the-template).
+14. If your change should become part of the main protocol, open a pull request to `main` and request review from relevant people.
+15. Before requesting review, check the changed files. For a routine protocol edit, expected changes are `README.md`, `CODEOWNERS`, and optionally `legacy/source-metadata.yml` when provenance is updated. For a legacy PDF import, files in `legacy/` may also be created or updated. If any other files changed, remove those changes or explain clearly why they are needed.
+16. Do not merge into `main` without review, unless you are the only person using that protocol.
---
@@ -329,10 +331,62 @@ Before using a protocol in the lab, check all of the following:
# Release a protocol
-Once a protocol has been added and confirmed to be working — that is, its status is 🟢 `[OK]` and this is clearly marked at the top of the file, create the first release: `1.0.0`.
-> **Recommended**: Link releases to Zenodo if you want each protocol version to have a citable DOI.
+Once a protocol has been added and confirmed to be working, create the first release: `1.0.0`.
+
+Before releasing:
+
+1. Confirm the protocol status is 🟢 `[OK]`.
+2. Confirm validation passes on `main`.
+3. Confirm the generated PDF is current and the PDF header commit SHA matches the protocol commit you intend to release.
+4. Create a GitHub release and tag, starting with `1.0.0`.
+5. Link the release to Zenodo if you want a citable DOI.
+6. Tell maintainers listed in `CODEOWNERS` and relevant protocol users when a new version is released.
+
+Further changes can then be released using semantic versioning.
+
+---
+
+# Tips for making the most of the template
+
+Use the repository as both the current protocol and the record of how the protocol changed.
+
+### Issues and Projects
+
+- Open one GitHub Issue per problem, optimisation, question, or protocol aspect. Use the `Protocol issues` template.
+- Keep issues modular: if the discussion splits into a separate problem, open a separate issue and link it. If an issue is complex, open sub-issues.
+- Link issues to a GitHub Project when work is shared, ongoing, or has multiple follow-up steps.
+- Add useful evidence directly to the issue: images, gels, follow-up results, notes, links to analysis repositories, database records, sample sheets, or source data.
+- Close the issue when the result is incorporated into `README.md`, rejected with a clear reason, or moved to a new issue. Add comments to explain the reason and to discuss an issue.
+
+### Branches, commits, and pull requests
+
+- Create a branch for each meaningful feature, fix, or experimental optimisation round. Use the appropriate base branch; it does not always need to be `main`.
+- Keep commits small and descriptive.
+- Mention related issues in commit messages or pull requests, for example `refs #12` while investigating or `closes #12` when the change resolves the issue.
+- In pull requests, request reviewers, tag relevant people, and invite discussion before merging changes that affect how people run or interpret the protocol.
+
+### Slack integration
+
+If your team uses Slack, you can connect a protocol repository to a Slack channel with the [GitHub integration for Slack](https://github.com/integrations/slack). In the relevant Slack channel:
+
+```text
+/invite @github
+/github signin
+/github subscribe owner/repo
+```
+
+Replace `owner/repo` with the protocol repository, for example `ulelab/protocol-rnaseq`.
+
+You can set what type of notifications you want updates for on Slack by specifying the type of subscription:
+
+Examples:
+```text
+/github subscribe owner/repo issues pulls reviews comments
+/github subscribe owner/repo workflows
+/github unsubscribe owner/repo commits
+```
-Further changes can then be released using semantic versioning. Ensure maintainers listed in `CODEOWNERS` and other protocol developers and users are involved or aware if a new version release is planned.
+Use Slack notifications to keep the channel aware of issues, pull requests, reviews, and workflow status. Tune subscriptions if the channel becomes noisy.
---
@@ -356,3 +410,54 @@ Template citation:
Ira A. Iosub. `protocol-template`, DOI: https://doi.org/10.5281/zenodo.20148013
The template citation metadata is stored in `docs/template-metadata.yml`.
+
+---
+
+# Maintainer and contributor notes
+
+> **Template maintainers only:** This section is for people maintaining `ulelab/protocol-template` itself. It is not part of the normal protocol-author workflow; most users can stop at [Citation information](#citation-information).
+
+> **Note:** The template `README.md` intentionally contains placeholders, so content validation may fail in this template repository. Protocol repositories created from the template should pass content validation after the placeholders are replaced.
+
+## When to change this template
+
+Change this repository only when the change should apply to future protocol repositories or to the shared template machinery.
+
+> **Important:** Existing protocol repositories do not automatically inherit changes made here after they were created from the template. If a template change is important for existing protocol repositories, communicate it separately or apply it to those repositories directly.
+
+Good reasons to change the template include:
+
+- improving the default protocol structure in `README.md`
+- clarifying the user guide
+- changing validation or style-fix rules
+- improving legacy PDF migration support
+- adjusting PDF rendering
+- updating shared issue, pull request, or ownership defaults
+- updating template metadata, licensing, notices, or release information
+
+For a one-off correction to a single protocol, change that protocol repository instead.
+
+## Keep the user experience lightweight
+
+The template should make the common path obvious: create a repository, edit `README.md`, validate, review, and use the generated PDF.
+
+- Do not add new required user steps unless they prevent a real recurring failure.
+- Prefer improving existing workflows, scripts, or docs over adding new files.
+- Keep maintainer rationale out of the main protocol-author path.
+- Keep generated or temporary files out of the template unless users need them as examples or defaults.
+- Avoid broad rewrites when a small, tested change fixes the problem.
+
+## Change checklist
+
+Before merging template changes:
+
+1. For Markdown-only documentation changes, at least inspect the rendered Markdown or diff carefully.
+2. For PDF rendering changes, generate or inspect the PDF produced by the `README-to-pdf` workflow.
+3. For workflow changes, check triggers, permissions, branch behavior, generated commits, and whether users need to run `git pull` afterwards.
+4. For migration behavior changes, keep `docs/PROMPT.md`, `.github/copilot-instructions.md`, `.agents/skills/protocol-migration/SKILL.md`, and `.claude/skills/protocol-migration/SKILL.md` consistent.
+5. For validator or fixer changes, add or update exact regression tests for the intended behavior and important false positives.
+6. Update this guide if applicable.
+
+## Releases
+
+Use template releases for meaningful template changes. Update `docs/template-metadata.yml` when the template version, citation metadata, or release metadata changes.
diff --git a/protocol-template.pdf b/protocol-template.pdf
index c46ee2e..50efa19 100644
Binary files a/protocol-template.pdf and b/protocol-template.pdf differ
diff --git a/scripts/fix_protocol_style.py b/scripts/fix_protocol_style.py
index fd4beb8..35a50c8 100644
--- a/scripts/fix_protocol_style.py
+++ b/scripts/fix_protocol_style.py
@@ -19,11 +19,10 @@
rf"\b(?P{NUMBER_RE})(?P\s*)(?PuL|ul|UL|uM|UM|ug|μL|μM|μg)\b"
)
UNIT_RE = re.compile(
- rf"\b(?P{NUMBER_RE})(?P\s*)(?PµL|mL|ml|ML|L|l|µg|mg|g|kg|ng|mM|µM|nM|M|μL|μM|μg)\b"
+ rf"\b(?P{NUMBER_RE})(?P\s*)(?PµL|mL|ml|ML|L|l|µg|mg|g|kg|ng|mM|µM|nM|M)\b"
)
TIME_RE = re.compile(
- rf"\b(?P{NUMBER_RE})(?P\s*)(?Pseconds?|second|minutes?|minute|hours?|hour|secs?|sec|mins?|min|hrs?|hr|s|h)\b",
- re.IGNORECASE,
+ rf"\b(?P{NUMBER_RE})(?P\s*)(?P(?i:seconds?|minutes?|hours?|secs?|mins?|hrs?)|s|h)\b",
)
CHEMICAL_FORMULA_RE = re.compile(r"\b(?P(?:[A-Z][a-z]?\d*){2,})\b")
UNICODE_SUBSCRIPT_RE = re.compile(r"\b(?P[A-Za-z₀₁₂₃₄₅₆₇₈₉]+)\b")
@@ -70,6 +69,9 @@
"hours": "hour",
}
UNICODE_SUBSCRIPT_MAP = str.maketrans("₀₁₂₃₄₅₆₇₈₉", "0123456789")
+LITERAL_CHEMICAL_FORMULAS = {
+ "ddH2O": "ddH2O",
+}
NOTE_LABEL_RE = re.compile(
r"^(?P\s*)(?P