| name | determinize-refactor |
| description | Analyze a prompt-heavy skill/plugin and produce a prioritized migration plan that moves deterministic instructions out of prose into scripts or structured contracts — improving reliability and cutting token cost. Use when the user says "reduce prompt tokens", "make this skill deterministic", "script-mode this skill", or "audit a skill for token bloat". Outputs a Markdown audit report with a token summary and per-file conversion plan, NOT code. NOT for authoring a skill from scratch (use writing-great-skills) or scoring quality (use linting-and-scoring). |
Determinism refactor (script-mode)
Analyze a prompt-heavy skill and produce a migration plan that improves reliability and
reduces token cost by moving the deterministic parts of the prose into scripts or
structured contracts, leaving only genuine judgment in the prompt.
Inputs
Accept any of:
- a plugin path (e.g.
claude-code/plugins/core/oncall/alert-rca)
- a skill path (e.g.
.../skills/<skill-name>/)
- a single prompt file (
SKILL.md or references/*.md)
If no path is provided, ask for the target scope before continuing.
Workflow
1. Collect the prompt corpus
Gather SKILL.md + all references/*.md for each target. Include other markdown only when it
directly affects runtime behavior. Ignore tests/scripts for token sizing, but read them to
check whether logic is already deterministic.
2. Classify by determinism
Tag each section as one of: strict workflow, fixed mappings, arg/call contracts,
output templates, retry/error policy, partial (mixed rules + judgment), narrative
/ human explanation, context, or interpretation guidance. Attach an evidence snippet
from the exact file/section for every tag.
3. Quantify token cost (state assumptions)
Default line-based estimate: tokens ≈ non_empty_lines × 11 — show a low/high range with
multipliers 9 and 13. Break the count down by file, by section, and by execution
path (fast path vs full path) when the skill has conditional flows.
4. Estimate refactor savings
Apply reducibility by classification:
| Class | Reducible |
|---|
| Deterministic (strict workflow, fixed mappings, contracts, templates) | 80–95% |
| Partial (mixed rules + judgment) | 30–60% |
| Narrative / interpretation | 10–20% |
Return conservative and aggressive totals, and highlight the top 5 sections by
absolute token savings.
5. Recommend prompt → script extractions
For each high-impact deterministic section, propose a target artifact:
- workflow state machine
- mapping / classification module
- scoring calculator
- output renderer
- validation-gate checker
Include the expected reliability benefit and the dependency risk.
6. Build the file-by-file conversion plan
For each convertible file: what (exact sections/rules to extract), why (determinism /
reliability / token rationale), how (script/module shape, inputs/outputs, integration
path). Plus metadata: suggested script path, estimated savings (conservative/aggressive),
priority (P0/P1/P2), risk (low/med/high), dependencies/blockers.
Output structure (Markdown report per path)
- Token summary (mandatory, first section)
- original tokens (one clear number + optional low/high range)
- post-refactor: conservative and aggressive
- % improvement, conservative and aggressive
- show the formulas explicitly:
post_refactor_tokens = original_tokens − reducible_tokensimprovement_percent = (reducible_tokens / original_tokens) × 100
- Concrete savings breakdown (conservative + aggressive)
- Top deterministic sections to extract first
- Detailed file conversion plan — a per-file table:
file | what | why | how | script path | savings (cons/agg) | priority | risk
- Suggested pipeline changes
- Residual prompt — what should stay model-driven (the judgment that shouldn't be scripted)
If multiple paths are given, separate reports with clear ## <path> headings.
Quality bar
- Every quantified claim includes its formula and assumptions.
- Every extraction recommendation cites source files.
- Token counts are estimates unless a real tokenizer was run — say which.
- Call out known uncertainty explicitly.
- Never omit original tokens, post-refactor tokens, or % improvement.
- Never omit the conservative/aggressive what/why/how conversion list.
- Default output is a Markdown audit report per path. Never emit JSON/code files unless the user explicitly asks.
Errors
| Issue | Fix |
|---|
| No path given | Ask for the target skill/plugin/file before analyzing. |
| Skill is already lean (mostly judgment) | Report low reducibility honestly; recommend leaving it as prose. |
| Can't measure real tokens | Use the line-based estimate and label it an estimate with the multiplier range. |
| User wants the code, not a plan | This skill outputs the plan; hand off to an implementer to write the scripts. |
| target repo/plugin path unreadable (permissions/sandbox) | report which paths were skipped; never guess their contents |
