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