kylesnowschwartz/simpleclaude/sc-dirty-room

Dirty-Room Design

This is a bastardization of the technique used by Compaq 1982 to clone the IBM PC BIOS.

A structured approach to porting a software artifact to a different language or platform while consulting its internals. A reading agent examines the original and produces discovery, fixtures, and a translation brief — notes on which algorithms, data structures, and idioms are worth carrying across the language boundary. The implementation agent receives all three artifacts and explicit permission to read the original source directly.

The clean-room skill builds a wall between specification and implementation to preserve copyright independence; the dirty-room takes notes through the open window because the constraints here are technical, not legal. Use this when the goal is a faithful port rather than an independent reimplementation.

EXECUTION MODEL

Phases 0 through 6 run in sequence. The core phases (1-4) MUST NOT be skipped or reordered.

• Phase 0 establishes scope, target language, and pins the artifact version
• Phase 1 (Read) examines the original via a Task() agent and produces discovery, fixtures, and a translation brief
• Phase 2 (Refine) finalises the spec and translation brief for handoff
• Phase 3 (Port) builds in a Task() agent that may consult the original directly
• Phase 4 (Verify) confirms equivalence via spec compliance and fixture replay
• Phases 5-6 present results and offer next steps

After each phase, present the output to the user and wait for approval before proceeding.

No isolation, by design

The implementation agent in Phase 3 receives the original artifact's path and may read it freely. The reading agent's notes flow through to the porter. This is the explicit difference from /sc-clean-room — the wall is gone because the work is a translation, not a clean reimplementation. Process-level separation between agents is preserved only for token efficiency; it is no longer load-bearing for independence.

Phase 0: Resolve Target, Scope, and Languages

Parse $ARGUMENTS. The first argument is the target, anything after is a scope, focus, or target-language hint.

Target resolution

Version pinning is mandatory. Record an immutable identifier so all artifacts reference the same version.

Scope and language negotiation

Use AskUserQuestion:

• Source language and runtime
• Target language and runtime (this is the defining input; if same as source, ask whether a direct implementation is a better fit)
• Which parts to port (the whole thing, a subset, a single module)
• Quality attributes that matter (performance parity, API compatibility, idiomatic target-language code)
• What is explicitly out of scope
• Licence check: confirm the user has rights to study the original and produce a port. If unclear, redirect to /sc-clean-room.

Tell the user: "Target: [what]. Scope: [boundaries]. Languages: [source] → [target]."

Run directory

Slug: <artifact-name>-<source-lang>-to-<target-lang> (lowercase, hyphens). Create with mkdir -p .agent-history/dirty-room/<slug>.

Run git check-ignore -q .agent-history/ — if it fails, warn the user to add the ignore rule.

If the directory already exists, ask: start fresh, resume, or abort.

Classify the artifact

Run State

Before leaving Phase 0, fix the following named variables.

Substitution contract. Two grammars appear in this skill and must not be confused:

• Tokens of the form <UPPER_SNAKE> are Run State variables. The orchestrator MUST replace them with the resolved value before sending any prompt to a Task() agent. Every Phase 1 and Phase 3 prompt body performs this literal substitution before invocation.
• Tokens of the form [brief description] inside example artifact templates (the discovery.md, fixtures.md, specification.md, and verification.md blocks) are human-readable scaffolds the spawned agent fills with its findings — do NOT replace these.

Echo the Run State back to the user as a compact block before Phase 1 so they can confirm:

SLUG=<resolved>
RUN_DIR=<resolved>
ARTIFACT_NAME=<resolved>
SOURCE_LANG=<resolved>
TARGET_LANG=<resolved>
SOURCE_PATH=<resolved>
TARGET_PATH=<resolved>
SOURCE_VERSION=<resolved>
SCOPE=<resolved>

(IMPL_PREFS is filled in at Phase 3.)

Phase 0 Materialisation

After resolving Run State, the orchestrator MUST materialise the source on disk and record its version pin to <RUN_DIR>provenance.json before proceeding to Phase 1. Run exactly one row from the table below — the row whose target type matches what the user supplied.

provenance.json shape (uniform across all rows):

{
  "target_type": "repo_url | local_path | package | protocol",
  "identifier": "<the original argument as supplied>",
  "version_pin": "<commit SHA, package version, or doc revision/access date>",
  "captured_at": "<ISO-8601 UTC timestamp>",
  "source_path": "<absolute path>"
}

Update SOURCE_PATH and SOURCE_VERSION in Run State from <RUN_DIR>provenance.json (the source_path and version_pin fields, respectively). From Phase 1 onward, all agent prompts derive <SOURCE_PATH> and <SOURCE_VERSION> from <RUN_DIR>provenance.json.

Phase 1: Read the Source

Examine the original to document what it does, how it does the parts worth preserving, and capture behavioural fixtures for verification.

BLOCKING: Complete the reading before moving to Phase 2.

Launch as a Task() agent. This agent reads the original freely. Its output goes to disk; the orchestrator reads those files afterward. Unlike clean-room, there is no contamination concern — the implementation agent will see the same source material itself.

Per the substitution contract above, replace every <UPPER_SNAKE> token in the prompt body with its Run State value before invoking. Leave the [bracket] scaffolds inside the example artifact templates untouched — those are for the spawned agent to fill.

Task(
  description: "Dirty-room reading: examine original artifact for port",
  prompt: """
  ## Role: Reading Agent
 
  Examine the original artifact and produce three deliverables:
  1. A discovery document (behaviour and noteworthy internals)
  2. A behavioural fixtures file
  3. A translation brief (how to carry this across the language boundary)
 
  Target: <ARTIFACT_NAME>
  Scope: <SCOPE>
  Provenance: <RUN_DIR>provenance.json is authoritative for SOURCE_PATH and SOURCE_VERSION; read it before starting.
  Source version: <SOURCE_VERSION>
  Source language: <SOURCE_LANG>
  Target language: <TARGET_LANG>
  Source path: <SOURCE_PATH>
  Run directory: <RUN_DIR>
 
  ## What to capture in discovery.md
  - Public interface: function signatures, types, config options, error types
  - Behavioural contracts: input/output mappings, side effects, edge cases
  - Integration surface: dependencies, consumers, environment expectations
  - Non-functional characteristics: performance envelope, concurrency model
  - **Internal techniques worth noting**: algorithms, data structures,
    optimisation tricks, ordering of operations, invariants the code relies on