Phase 3: never pre-escape Edit-tool strings — verify the diff for literal backslash-quotes after inserting quoted text #147

Routed up from Preponderous-Software/acsf-dev-loop#35, which was classified template-rule during triage and is therefore not implemented in that instance. The mechanism stated in that issue was found to be wrong and is corrected here before the rule is written anywhere.

What was observed

A docstring containing double quotes was inserted with the Edit tool, and the inner quotes were pre-escaped JSON-style (\"smooth, graded representation spaces\"). The .py file ended up with literal backslashes in the source. The self-review caught it only on a careful read of gh pr diff.

Corrected mechanism

The original issue claimed that Python does not process \" as an escape inside a triple-quoted string. It does — '''say \"hi\"''' evaluates to say "hi" with no backslash in the value (verified with python3 -c). So the docstring's runtime value was correct; what was wrong was the source text, because the Edit tool writes new_string verbatim and the escapes were never needed. The defect is cosmetic-but-public: a backslash-littered docstring in a source file reads as a mistake and survives every test.

The hazard is therefore a tool-usage one, independent of language: any text passed through the Edit tool is written byte-for-byte, so pre-escaping quotes, backslashes, or newlines as if the parameter were a JSON string literal leaves those escapes in the file.

Suggested template text (Phase 3 — Implementation, universal rules)

Never pre-escape Edit-tool strings. old_string / new_string are written verbatim — a \" typed to "protect" a quote lands in the file as a backslash followed by a quote. Type the literal characters wanted in the file. After inserting any text that contains quotes, grep the diff for stray \" and \' before committing (git diff | grep -n -F '\"', then the same with "\\'"), and prefer the other quote style for inner literals (single quotes inside a double-quoted or triple-double-quoted string) so no escaping question arises at all.

Why upstream

Every generated dev-loop edits source files with the same tool, so the hazard is not specific to the ACSF project or to Python.

This issue body was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

drafted by Claude on behalf of Daniel Stephenson