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:

## Pass N — YYYY-MM-DD — focus: <what this pass tackled>
- changed: <what got edited>
- still rough: <open gaps, ranked — top next focus>
- deferred: <thing> — because <reason>

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

# 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

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.