spec-sanitization

Spec Sanitization

The sanitization pass turns raw analysis into specs an implementer can build from.

Why This Exists

Analysts read source code, binaries, and runtime behavior. Even with good intentions, they leak implementation details:

• Function names from source (minified or not)
• Variable and class names from source
• Code structure ("function X calls Y which calls Z")
• Line numbers and file locations
• Raw file paths (workspace/raw/source/analysis/chunk-42.md:67)

These have no place in the output specs. Your job: READ each spec, UNDERSTAND the behavior, REWRITE without source references, TRANSFORM provenance citations.

The Rewrite Rule

You must not copy text from raw specs into output specs. Not sentences, not paragraphs, not sections. Read the raw specs to understand the behavior, then write a fresh output spec from your understanding.

Why? Raw specs have source code identifiers woven into every sentence — minified names (k0, Wq, z1), internal function signatures (Pn(a, b, c)), and numeric implementation constants. Find-and-replace cannot catch them all; many internal identifiers read like plain English (shouldRetryOnTimeout, evict_stale_connections). A paraphrase that preserves the original's structure is still leaking the original's design. The only reliable approach is to never copy the text at all.

Process per file:

1. Read the raw spec end-to-end
2. Close it (do not refer back to it while writing)
3. Write the output spec from your understanding of the behavior
4. Use only: behavioral descriptions, user-facing identifiers (env vars, CLI flags, config keys, protocol fields), and numeric constants (timeouts, limits, sizes)
5. For any concept you could not translate into behavioral language — because you don't understand what it does — add: [UNCERTAINTY: U-{DOMAIN}-{NNN}] {what the raw spec said, in behavioral terms as best you can} — behavioral purpose could not be determined from available analysis.

Never preserve implementation jargon in slightly-reworded form. "validator.Exists() is called" rewritten as "the exists check runs" is still jargon — neither you nor the implementer knows what it means. Either translate it to behavior ("verifies the value exists in the constrained list") or flag it as uncertain.