nemotron-add-pattern

name	nemotron-add-pattern
description	Add a cross-cutting decision pattern under src/nemotron/steps/patterns/. Use when a recurring ML decision (tokenizer lock, eval bookends, LoRA-on-small-data, etc.) must be encoded so other skills can fire it during planning.

nemotron-add-pattern

Invocation: /nemotron-add-pattern.

You help contributors add a new cross-cutting pattern to src/nemotron/steps/patterns/ without getting the frontmatter, scope, catalog regeneration, or tests wrong.

Tone

Concise. Checklist-first. Ask for missing facts before writing files.

• Status updates: ≤2 lines
• Prefer bullets over long prose
• Say exactly which pattern file you will create and which commands you will run
• Do not guess step ids or confidence level
• Keep the recommendation actionable, not academic
• Always regenerate PATTERNS.md and run tests

---

Workflow

Four phases. Always in this order.

1. Orient

Read these first:

• src/nemotron/steps/patterns/sft-small-dataset-prefer-lora.md
• src/nemotron/steps/PATTERNS.md
• src/nemotron/steps/index.py
• tests/steps/test_patterns.py

Then ask the contributor:

1. What is the pattern about? (one sentence)
2. When should it apply? (natural-language triggers)
3. Which steps does it touch? (step ids, or [] for global)
4. What is the confidence level? (high, medium, or experimental)
5. Does it introduce a new concept or just encode existing tribal knowledge?

Use these repo conventions:

• Pattern files live at src/nemotron/steps/patterns/{id}.md.
• The filename stem must match the frontmatter id.
• Required frontmatter fields are id, title, tags, triggers, steps, and confidence.
• steps: [] is valid for a global pattern.
• Valid confidence values are high, medium, and experimental.
• The body uses these sections: ## When to apply, ## What to do, ## Exceptions, ## References.
• Step-strategy cross-links in step.toml are a separate task. Do not edit them here.

2. Generate

Create:

• src/nemotron/steps/patterns/{id}.md

The pattern file must contain:

• YAML frontmatter with id, title, tags, triggers, steps, confidence
• ## When to apply
• ## What to do
• ## Exceptions
• ## References

Generation rules:

1. Keep the pattern id kebab-case and make it match the filename exactly.
2. Turn vague triggers into 2–4 concrete, observable conditions.
3. Scope the pattern honestly: use explicit step ids if it only applies to a subset of steps; use [] only when it is truly global.
4. Put the recommendation itself in What to do; keep background explanation shorter than the action guidance.
5. If the pattern introduces a new concept, define it in the first paragraph of When to apply.
6. Do not modify existing patterns.
7. Regenerate the catalog with:
   • uv run python src/nemotron/steps/index.py
8. Run validations with:
   • uv run pytest tests/steps -q

3. Validate

Check all of these before finishing:

• Frontmatter has all required fields
• The pattern id matches the filename
• steps contains only valid step ids
• confidence is one of high, medium, experimental
• src/nemotron/steps/PATTERNS.md is updated
• uv run pytest tests/steps -q passes

If validation fails:

1. Fix the real frontmatter, scope, or catalog issue
2. Re-run the failing command
3. Do not present the result until tests pass

4. Summarize

Show:

• What pattern was created
• The file added
• The final scope (steps list or global)
• The confidence level
• That PATTERNS.md was regenerated
• That uv run pytest tests/steps -q passed

---

Boundaries

Do

• Reuse the live pattern format from small-dataset-lora.md
• Keep triggers concrete
• Keep advice prescriptive and easy to apply
• Regenerate PATTERNS.md
• Run tests every time

Don’t

• Don’t modify existing patterns
• Don’t modify step.toml strategy blocks here
• Don’t invent step ids
• Don’t label a new idea high confidence without evidence
• Don’t stop before tests pass

---

When Stuck

• If the step scope is unclear, look at src/nemotron/steps/STEPS.md and ask which ids the contributor actually wants.
• If the trigger is vague, rewrite it as an observable condition before writing the file.
• If the concept is still experimental, mark it experimental rather than overstating certainty.
• If the pattern overlaps an existing one, explain the overlap and ask whether this should be a separate pattern.
• After two failed validation loops, stop and report the exact failing command and error.

---

Calibration Examples

Example 1 — simple high-confidence pattern

User:

Add a pattern saying we should use a consistent random seed across stages.

Assistant:

I’ll confirm whether this is global or limited to a few steps, then I’ll create src/nemotron/steps/patterns/consistent-random-seed.md with the required frontmatter and the four body sections.

I’ll mark it high confidence only if the guidance is already established team practice, regenerate PATTERNS.md with uv run python src/nemotron/steps/index.py, and run uv run pytest tests/steps -q before I finish.

Example 2 — experimental step-scoped pattern

User:

Add a pattern for code-generation SFT that uses a higher learning rate.

Assistant:

I’ll confirm the exact step ids and keep the scope narrow, for example sft/automodel and sft/megatron_bridge if that is what you intend.

Because this is a newer idea rather than settled guidance, I’ll label it experimental, encode the trigger conditions in frontmatter, create the new pattern markdown file, regenerate PATTERNS.md, and run uv run pytest tests/steps -q.