# Whiteboxing > Whiteboxing - Skill: `evnchn-agentic/whiteboxing` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add evnchn-agentic/whiteboxing` - Raw SKILL.md: https://api.skillmd.com/api/skills/evnchn-agentic/whiteboxing/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: evnchn-agentic (https://skillmd.com/u/evnchn-agentic) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/evnchn-agentic/whiteboxing --- # Whiteboxing ## Overview `superpowers:writing-skills` *creates* a skill in one RED→GREEN→REFACTOR cycle and stops. **Whiteboxing is what comes after:** the operator-in-the-loop **polish loop** run **many times on the same skill**, converging a rough first draft (a *brick*) into a refined, trustworthy, publishable skill (the *jade*). It's 拋磚引玉 operationalized — `writing-skills` throws the brick; this is the jade-polishing the create-once tools stop before. Convergence, not thrash, is the whole game: each pass must **build on** the last, not re-litigate it. **When is it jade (stop):** when a pass surfaces no new gap and the targeted critique comes back clean — don't over-buff (see `chengyu-stop-when-appropriate`). Jade is *clean + converged*, not *infinitely polished*. ## When to use - An existing skill (yours or `writing-skills`-created) needs refining — and you expect to do it repeatedly. - A round of feedback / a hot-take / a fresh review just landed on a skill. - You're turning a tacit process into a skill and know it'll take several passes. **Not for:** first-time creation from scratch → `superpowers:writing-skills`. A one-off doc edit with no convergence intent → just edit. ## The loop — two modes ### Mode A — Polish pass (the common case; run many times) > **First pass on a new skill:** there's no ledger yet — copy `POLISH.template.md` → `POLISH.md`, record the just-created skill as the baseline (Pass 0), then run the loop below. 1. **Read the ledger** — `POLISH.md` (below) + the skill's current files. 2. **Pick the focus** — the operator's hot-take/direction for this pass; if none, the top open gap from the ledger. 3. **Re-ground — don't trust the ledger about the world.** Grep the *live* corpus / source / state for the slice this pass touches; verify against current artifacts. A ledger note is a pointer, not truth. (Deriving a "standard" from a model's blob-read instead of the real corpus is how you ship a confabulated grammar.) 4. **Do the work** — edit SKILL.md / template / README. 5. **Targeted critique of what changed** — cold-apply a subagent to the touched part; for prose/engagement, a *fresh-lineage* review. Not a full re-review — that's Mode B. (**Fresh-lineage = a different model family** — Codex via MCP, or opencode/Qwen. A Claude subagent is *same-lineage* and does **not** count — correlated errors. No cross-lineage tool wired up? Say so; don't silently substitute a second Claude pass and call it fresh.) 6. **Update the ledger** — append: what changed · what's still rough · what was deferred-and-why. 7. **Commit.** Private by default. ### Mode B — Pre-public gate (run ONCE, at "make it public") A **stateless, from-scratch** review that explicitly does **not** trust `POLISH.md` (a ledger lies by omission): - fresh cold-apply test + engagement check; - corpus re-ground; - **the safety floor (below) — mandatory, blocks by default;** - then the operator's judgement calls, then flip. A passing Mode-A critique does **not** satisfy this gate — Mode B redoes every check from scratch, no matter how polished the ledger looks. ## POLISH.md — the ledger (primary state) The convergence memory; without it, passes thrash. Copy `POLISH.template.md`. Shape: ```markdown ## Pass N — YYYY-MM-DD — focus: - changed: - still rough: - deferred: — because ``` `POLISH.md` is the **primary** trail. **git history is an assistive escape hatch** — consult it when the ledger is unclear, never as the main record. **Where it lives + a safety note:** `POLISH.md` sits next to the skill it tracks (in the skill's own dir). It's a **working/private artifact** — it accumulates *deferred-because* reasons and candid framing notes, exactly what the safety floor flags. So **exclude it from the public flip** (`.gitignore` it, or drop it before flipping). `DESIGN.md` and `POLISH.template.md` may ship; a filled-in `POLISH.md` does **not**, by default. ## Safety floor — enforced, NOT discretionary Exposure safety is a floor, not a taste call. A *"publish, do whatever"* operator must still be protected from leaking their own PII/secrets or someone else's content. Before any public flip, **run this audit yourself**; surface each finding for explicit per-item disposition (redact / white-label / confirm-safe / exclude); **default is do-not-ship**; a blanket "approve all" does **not** waive it — the operator disposes of each finding but cannot waive the floor wholesale. - **Secrets / credentials** — API keys, tokens, passwords, `.env` values, auth headers. - **PII** (the operator's own *and* others') — emails, real names beyond a chosen handle, phone, address. - **Third-party / client content** — named companies/people/products not cleared; client artifacts; NDA-adjacent → white-label or block. - **Private paths / internal infra** — home paths, internal hostnames/IPs, private memory cross-refs. - **Unverified media** — re-view every image / photo-derived artifact for identifying content (logos, serials, faces, screens), redact, then **re-verify**. One crop is often not enough — a partial redaction that leaves text readable is the classic miss. **A default audit (minimum, not a ceiling — run from the artifact dir; any hit blocks until disposed):** ```bash # secrets / credentials gitleaks detect --no-git -s . 2>/dev/null || \ grep -rniE 'api[_-]?key|secret|token|password|bearer |AKIA[0-9A-Z]{16}|-----BEGIN' . # PII + infra: emails, IPv4, private home paths, internal hosts grep -rnE '[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}|([0-9]{1,3}\.){3}[0-9]{1,3}' . grep -rnE '/Users/|/home/[a-z]|~/[A-Za-z]|\.local\b|10\.[0-9]|192\.168\.' . # media: for EVERY image, Read it back (+ `exiftool`/`strings`) and confirm no logo/serial/face/screen for f in $(git ls-files '*.png' '*.jpg' '*.jpeg' 2>/dev/null); do echo "REVIEW: $f"; done ``` A clean grep is necessary, **not sufficient**, for media — eyes on each image is the real check, re-run after any crop (the partial-redaction trap). ## Operator judgement — genuinely deferred (only after the floor passes) - **Liveness** — *routine* (lives by use) vs *episodic* (needs its results sheltered as repos to live) → shelter accordingly. - **Publish path** — direct flip · brick (use-then-reveal) · hold private. - **Framing** — specificity is often the point; show the value-add not the plumbing; never write a private *motive* into the artifact; handle named third parties out-of-band, not in public text. ## Composition (compose, don't restate) - First-time create → `superpowers:writing-skills`. - General authoring lessons (description-as-trigger, match-the-form-to-the-failure) → reference its companion notes; don't duplicate. - Whiteboxing **owns** only: the loop, the ledger, the safety floor, and the floor-vs-judgement split. ## Common mistakes | Mistake | Fix | |---|---| | Using it to create from scratch | That's `writing-skills`; whiteboxing polishes what exists | | Trusting the ledger about the world | Re-ground against live artifacts each pass (step 3) | | Full re-review every pass | Targeted critique in Mode A; full stateless review only at Mode B | | Letting the operator waive the safety floor | The floor is enforced; only taste/strategy is deferred | | One redaction pass on media | Re-verify after redacting — partial crops leave readable leaks | | No ledger | Passes thrash and re-litigate; the ledger is what converges them | ## Self-test Build it, then **whitebox the whiteboxing**: run a Mode-A pass on this skill *using* this skill, logging to its own `POLISH.md`. If it can't polish itself, it isn't done.