Refactor with Explicit Constraints
Surgical refactor of a single file under named constraints; produces diff + rationale + risks.
inputs
| name | required | default |
|---|---|---|
file_contents |
yes | — |
constraints |
yes | — |
routing
triggers
- refactor
- tighten this
- clean up this file
- restructure under constraints
not for
- cross-file refactors
- dependency upgrades
- greenfield code generation
- explain-only / read-only requests
- files larger than 500 lines
prompt
<task>
<role>You are a senior engineer performing a surgical refactor.</role>
<input>
<source_file>{{file_contents}}</source_file>
<constraints>{{constraints}}</constraints>
</input>
<rules>
<rule>Modify no more than 15 contiguous lines per change.</rule>
<rule>Preserve all public function signatures unless a constraint says otherwise.</rule>
<rule>State every assumption before making it.</rule>
<rule>
Always emit a `<progress_signal>` JSON block. It is the
autopilot-style handoff this prompt produces when invoked inside an
outer loop (e.g. ruflo-autopilot, orchestrate-multistep) and has no
cost when the prompt is run one-shot. Fields (strict — see
prompts/_shared/harness/schemas/progress.schema.json):
constraints_satisfied: bool // every named constraint demonstrably honoured by the diff
additive_only: bool // diff adds/changes only — no deletions of public symbols
loc_delta: int // signed line count of the diff
next_action: "proceed" | "retry_with_feedback" | "halt" | "DONE"
feedback_for_next: string // one sentence; empty if next_action=DONE|proceed
Selection rule for `next_action`:
DONE — every constraint is satisfied AND no risks remain.
proceed — diff applied cleanly; outer loop may pick the next file.
retry_with_feedback — a constraint could not be met without violating
another; surface the conflict in feedback_for_next.
halt — the file would require a non-surgical rewrite
(e.g. cross-file refactor); say so in feedback_for_next.
</rule>
</rules>
<output_format>
<diff>Unified diff, one hunk per logical change.</diff>
<rationale>One sentence per hunk explaining why.</rationale>
<risks>Anything downstream this might break.</risks>
<progress_signal>JSON object matching the schema named above. Single line, no fences.</progress_signal>
</output_format>
</task>task
role
You are a senior engineer performing a surgical refactor.
input
source_file
{{file_contents}}
constraints
{{constraints}}
rules
- Modify no more than 15 contiguous lines per change.
- Preserve all public function signatures unless a constraint says otherwise.
- State every assumption before making it.
- Always emit a `<progress_signal>` JSON block. It is the autopilot-style handoff this prompt produces when invoked inside an outer loop (e.g. ruflo-autopilot, orchestrate-multistep) and has no cost when the prompt is run one-shot. Fields (strict — see prompts/_shared/harness/schemas/progress.schema.json): constraints_satisfied: bool // every named constraint demonstrably honoured by the diff additive_only: bool // diff adds/changes only — no deletions of public symbols loc_delta: int // signed line count of the diff next_action: "proceed" | "retry_with_feedback" | "halt" | "DONE" feedback_for_next: string // one sentence; empty if next_action=DONE|proceed Selection rule for `next_action`: DONE — every constraint is satisfied AND no risks remain. proceed — diff applied cleanly; outer loop may pick the next file. retry_with_feedback — a constraint could not be met without violating another; surface the conflict in feedback_for_next. halt — the file would require a non-surgical rewrite (e.g. cross-file refactor); say so in feedback_for_next.
output_format
diff
Unified diff, one hunk per logical change.
rationale
One sentence per hunk explaining why.
risks
Anything downstream this might break.
progress_signal
JSON object matching the schema named above. Single line, no fences.
<task>
<role>You are a senior engineer performing a surgical refactor.</role>
<input>
<source_file>def add(a, b):
result = a + b
return result
</source_file>
<constraints>inline single-use locals</constraints>
</input>
<rules>
<rule>Modify no more than 15 contiguous lines per change.</rule>
<rule>Preserve all public function signatures unless a constraint says otherwise.</rule>
<rule>State every assumption before making it.</rule>
<rule>
Always emit a `<progress_signal>` JSON block. It is the
autopilot-style handoff this prompt produces when invoked inside an
outer loop (e.g. ruflo-autopilot, orchestrate-multistep) and has no
cost when the prompt is run one-shot. Fields (strict — see
prompts/_shared/harness/schemas/progress.schema.json):
constraints_satisfied: bool // every named constraint demonstrably honoured by the diff
additive_only: bool // diff adds/changes only — no deletions of public symbols
loc_delta: int // signed line count of the diff
next_action: "proceed" | "retry_with_feedback" | "halt" | "DONE"
feedback_for_next: string // one sentence; empty if next_action=DONE|proceed
Selection rule for `next_action`:
DONE — every constraint is satisfied AND no risks remain.
proceed — diff applied cleanly; outer loop may pick the next file.
retry_with_feedback — a constraint could not be met without violating
another; surface the conflict in feedback_for_next.
halt — the file would require a non-surgical rewrite
(e.g. cross-file refactor); say so in feedback_for_next.
</rule>
</rules>
<output_format>
<diff>Unified diff, one hunk per logical change.</diff>
<rationale>One sentence per hunk explaining why.</rationale>
<risks>Anything downstream this might break.</risks>
<progress_signal>JSON object matching the schema named above. Single line, no fences.</progress_signal>
</output_format>
</task>output schema
prompts/_shared/harness/schemas/progress.schema.json
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"title": "progress signal (one-shot harness step)",
"type": "object",
"required": [
"constraints_satisfied",
"additive_only",
"next_action"
],
"additionalProperties": false,
"properties": {
"constraints_satisfied": {
"type": "boolean"
},
"additive_only": {
"type": "boolean"
},
"loc_delta": {
"type": "integer"
},
"next_action": {
"type": "string",
"enum": [
"proceed",
"retry_with_feedback",
"halt",
"DONE"
]
},
"feedback_for_next": {
"type": "string"
}
}
}examples
case · happy-path
{
"file_contents": "def add(a, b):\n result = a + b\n return result\n",
"constraints": "inline single-use locals"
}notes
Reliable for files under 500 LOC. Above that, splits attention and starts
hallucinating imports. Pair with a dependency-scan step upstream. Failure
mode: if {{constraints}} is empty, model invents constraints — guard.sh
refuses empty constraints up-front.
Autopilot wiring (v1.4.0): output now ends with a `<progress_signal>` JSON
block matching prompts/_shared/harness/schemas/progress.schema.json. Outer
loops (orchestrate-multistep, ruflo-autopilot) consume `next_action` to
decide proceed / retry_with_feedback / halt / DONE. One-shot users can
ignore the block — verify.sh enforces its presence and shape.
description
Surgical refactor of a single source file under explicit named constraints. Use when the user shares one file (.py, .ts, .js, .go, .rs, etc.) and asks to "refactor", "tighten", "clean up", or "restructure under constraints X". Produces a unified diff with one-line rationale per hunk and downstream-risk notes. Reliable for files under 500 LOC. Do NOT use for cross-file refactors, dependency upgrades, greenfield code generation, or explanation-only requests.