sc-dirty-room

What this skill does

# 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

| Argument | Target | Version pin |
|----------|--------|-------------|
| Repository URL | Clone or fetch the repo | Record commit SHA |
| Local path | Examine directly | Record git commit SHA; if not a git repo, record a checksum |
| Package name | Locate via registry (npm, PyPI, RubyGems, crates.io, etc.) | Record exact package version |
| Protocol or API name | Fetch public docs and specs | Record document revision or access date |

**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 /sc-work 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

| Type | Reading focus |
|------|---------------|
| **Library/Package** | Exported functions, types, behaviour contracts, internal algorithms |
| **CLI Tool** | Command interface, input/output formats, exit codes, argument parsing strategy |
| **API/Service** | Routes, request/response schemas, error codes, middleware ordering |
| **Protocol** | Message types, sequencing, state transitions, framing |
| **Data Format** | Syntax, semantics, edge cases, error recovery, parser strategy |
| **Algorithm** | Inputs, outputs, invariants, complexity, optimisations worth preserving |

### 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.

| Variable | Definition | Derivation rule |
|----------|------------|-----------------|
| `ARTIFACT_NAME` | Short canonical name of the original artifact | Lowercase, hyphens; strip versions, namespaces, and registry decorations. For repo URLs, use the repo's basename; for packages, the registry name without scope (`@org/foo` → `foo`); for protocols, the common abbreviation (e.g. `http2`, `grpc`). |
| `SOURCE_LANG` / `TARGET_LANG` | Canonical language tokens | Lowercase, hyphens. Use the canonical short names: `go`, `rust`, `python`, `typescript`, `javascript`, `ruby`, `java`, `kotlin`, `swift`, `c`, `cpp`, `csharp`, `elixir`, `erlang`, `scala`, `clojure`, `haskell`, `ocaml`. Pick the closest match for variants (`ts` → `typescript`, `py` → `python`). |
| `SLUG` | Run identifier | `<ARTIFACT_NAME>-<SOURCE_LANG>-to-<TARGET_LANG>` |
| `RUN_DIR` | Run directory (absolute path) | `<repo-root>/.agent-history/dirty-room/<SLUG>/` |
| `SOURCE_PATH` | Absolute path to the materialised original | Set by Phase 0 Materialisation, below. |
| `TARGET_PATH` | Absolute path where the port will be written | Confirm with the user; default to `<repo-root>/<ARTIFACT_NAME>-<TARGET_LANG>/` if unspecified. |
| `SOURCE_VERSION` | Immutable version pin of the materialised source | Read after Materialisation; this is the `version_pin` field recorded by the Materialisation recipe in `<RUN_DIR>provenance.json`. |
| `SCOPE` | Negotiated scope of the port | Captured during Phase 0 scope negotiation. A short prose summary of which parts are in scope and out of scope. |
| `IMPL_PREFS` | Porter's preferred architecture, test strategy, libraries | Captured at the start of Phase 3, immediately before the porting Task() is launched, via `AskUserQuestion`. |
| `APPROVAL_SIGNAL` | What counts as user approval at each blocking gate | An explicit affirmative from the user — "yes", "approved", "proceed", "lgtm", "go ahead", or equivalent. Silence, partial approval ("looks mostly good but…"), or any qualified response does NOT count; re-ask explicitly until you receive an unambiguous affirmative or an explicit halt. |

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):

```json
{
  "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>",
  "captur