---
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`.