refactor-for-determinism

name	refactor-for-determinism
description	Design or refactor skills by separating deterministic and non-deterministic steps. Use when creating or improving skills, especially to move repeatable workflows into scripts/ and update SKILL.md to call them.

Refactor for Determinism

Build reliable skills by separating deterministic steps from judgment-based steps.

Core Principle

Deterministic steps belong in scripts. Use SKILL.md to orchestrate the workflow and reserve judgment for the non-deterministic parts.

Workflow

1. Identify Deterministic vs Non-Deterministic Work

For each step in the skill:

• Deterministic: repeatable, mechanical, or validation-heavy steps → script candidates
• Non-deterministic: judgment, interpretation, creative choices → keep in SKILL.md

Examples of deterministic steps:

• Running quality checks
• Verifying clean git state
• Updating version strings
• Promoting CHANGELOG sections
• Collecting diff context for review

Examples of non-deterministic steps:

• Writing changelog content
• Selecting a solution approach
• Code review judgments
• Deciding release timing

2. Design Scripts for Deterministic Steps

For each deterministic step:

• Create a script in scripts/ within the skill directory
• Make it self-contained with clear error messages
• Validate inputs and exit non-zero on failure
• Prefer small, single-purpose scripts

3. Update SKILL.md to Use Scripts

• Replace manual command lists with script calls
• Reference scripts using relative paths: scripts/...
• Keep judgment steps explicit in prose

4. Document Boundaries

Make the line between scripted and non-scripted steps obvious:

• Use section headers like "Deterministic Steps" and "Judgment Steps"
• Call out where human/agent judgment is required

Output Format

## Determinism Audit

### Deterministic Steps (script candidates)
- [Step] → [script name]

### Non-Deterministic Steps (keep in SKILL.md)
- [Step] → [why it needs judgment]

### Script Plan
- scripts/[name] - [purpose, inputs, outputs]

### SKILL.md Updates
- [Where to call each script]

Common Mistakes

Mistake	Fix
Scripting judgment	Keep decision-making in SKILL.md
One giant script	Split into small, focused scripts
Silent failures	Print clear errors and exit non-zero
Hardcoded paths	Use repo-relative paths
Forgetting SKILL.md updates	Always wire scripts into instructions

What NOT to Do

• Do NOT hide decisions inside scripts
• Do NOT make scripts that require manual editing
• Do NOT mix multiple responsibilities into one script
• Do NOT add extra documentation files beyond SKILL.md