prototype-loop

Prototype Loop Skill

Codifies the leveraged-prototype dev loop documented in pulp #940. The loop closed 5 framework gaps in ~2 hours during the 2026-04-28 Spectr-on-@pulp/react parity session.

When to use this skill

Trigger this skill when the user is doing any of:

• Porting a UI to Pulp and wants tight visual-feedback iteration (Spectr's WebView editor → native via @pulp/react is the canonical example).
• Gap-finding — they suspect there are framework gaps and want to enumerate them via an AOT analyzer.
• Multi-PR upstream coordination — they're filing a batch of framework PRs and want a tight loop while upstream merges land.
• Hitting slow cross-platform configure cost (Skia/Dawn/threejs FetchContent) on changes that only need single-platform validation during iteration.

Do not trigger for: bugfixes, cross-platform refactors, or final-landing flows. Those want the cross-platform default.

When NOT to use this skill

• Pre-merge / landing the consumer's PR — always exit focus mode (or run shipyard pr / pulp pr) before landing. The ship path validates cross-platform regardless, but exiting focus mode keeps subsequent local iteration honest.
• Bugfixes that touch platform-specific code — a cross-platform build is the cheapest correctness check for those.
• Refactors that span subsystems — single-platform configure can mask a build break on a sibling platform.

The loop in one breath

analyze → file → prototype (ar-swap) → monitor → bump → ship

Each step has tooling. Some ships in Slice 1 (this PR), some lands in follow-up slices.

Slice status (as of 2026-04-27)

#	Surface	Status	Issue
1	pulp loop CLI + skill + slash command + docs	shipped	#940
2	pulp-ar-swap.sh ABI-checked archive splice	deferred	#946
3	pulp loop --watch-issues PR-monitor	deferred	#947
4	Lift @pulp/css-adapt, pulp-css-analyze, extract-html-bundle	deferred	#948

Step 1 — AOT analyze the consumer's bundle

Run pulp-css-analyze (Slice 4, lifting from spectr/native-react/tools/pulp-css-analyze until then) over the consumer's pre-built React bundle. The output is a coverage report listing unmapped CSS props with occurrence counts.

Reference output shape:

Unmapped CSS props (8 total):
  fontFamily            14×   examples: src/Label.tsx:23, src/Header.tsx:8, ...
  textAlign             6×    examples: src/Caption.tsx:12, ...
  ...

The occurrence counts are how you prioritize — file the 14× issue first.

Step 2 — File framework issues with the right shape

Each gap deserves its own issue. The shape that worked on 2026-04-28:

• One-line title — e.g. "Label.font_family_ accessor missing from public surface".
• Occurrence count — "Used in 14 places across the Spectr bundle (see analyzer report URL)".
• Acceptance criteria — concrete, testable. "label.set_font_family("Inter") followed by label.font_family() == "Inter" returns true".
• Bridge-fn signature suggestion — "label.set_font_family(string) mirroring set_font()".
• Cross-link to the analyzer report that surfaced it.

Filing 6 well-shaped issues with concrete signatures cuts upstream ramp-up dramatically. If you're going to file an umbrella + sub-issues, link the sub-issues from the umbrella's body so the dashboard view is coherent.

Step 3 — Enter focus mode (pulp loop)

pulp loop                       # auto-detect host platform
pulp loop --platform=macos      # explicit override
pulp loop --status              # report current state
pulp loop --off                 # restore cross-platform mode

The CLI persists [loop] focus_platform = "..." in ~/.pulp/config.toml. Subsequent invocations stay pinned until explicitly cleared.

--no-watch flips state and exits without entering the watch loop — this is what tests use, and it's also useful when you want the marker but plan to drive builds yourself.

Step 4 — Local prototype via ar-swap (Slice 2 — deferred, #946)

Pick the simplest gap from your filed issues. Build the framework patch in another worktree:

git worktree add ../pulp-fix-issue-X feat/fix-issue-X
cd ../pulp-fix-issue-X
cmake --build build --target pulp-view

Once Slice 2 ships, pulp loop --ar-swap-from ../pulp-fix-issue-X will splice the changed .o files into the pinned SDK's static archive after validating header/library ABI. The validator refuses on vtable mismatch — that's the trap that bit during the 2026-04-28 session with Label::font_family_.

Until Slice 2 lands, do the ar-swap by hand:

1. Build the patched object file in the other worktree.
2. nm -gU the object — make sure exported symbols match what your consumer's compile expects.
3. ar -r <pinned-sdk>/lib/libpulp-view.a <patched.o> — splice.
4. Visually validate via pulp-screenshot or pulp loop's screencap.
5. DELETE the local archive after validation. Otherwise you'll forget it's spliced and ship a binary that doesn't match the upstream pin.

Step 5 — Monitor upstream PR state flips (Slice 3 — deferred, #947)

Once Slice 3 ships:

pulp loop --watch-issues 924,927,931,932

will poll gh pr list for state flips on PRs referencing the named issues. It fires a notification when each PR transitions to MERGED.

Until then, run this in a side terminal:

watch -n 60 'gh pr list --state merged --search "924 OR 927 OR 931 OR 932" --json number,title,mergedAt'

Step 6 — Bump SDK pin and validate cross-platform

After the upstream batch merges and auto-releases:

1. Bump the consumer's SDK pin in one shot (e.g. 0.52.0 → 0.56.0 if v0.53/v0.54/v0.55/v0.56 each came from one of the merged PRs). Update pulp.toml / find_package(Pulp …).
2. Run pulp loop --off — restore cross-platform mode.
3. Run shipyard pr (or pulp pr) — full cross-platform validation gates the merge. This is the contract: focus mode for iterating, cross-platform for landing.

Filing follow-up issues

When you discover a new framework gap while in focus mode, file it the same way as Step 2. Don't fix it locally and forget — the loop's discipline is upstream-first.

If you fixed something locally to keep iteration moving and the upstream issue isn't merged yet, leave a // TODO(issue-NNN) marker and a planning doc note in the consumer. The skill is "file framework issues immediately", not "fix and forget".

Switching modes

• Enter: pulp loop --platform=macos → all subsequent rebuilds are single-platform.
• Exit: pulp loop --off → restores cross-platform mode.
• Land: shipyard pr (or pulp pr) → still runs full cross-platform validation before merge regardless of focus state.

The mode is advisory at the build layer today. The marker is read by tooling that wants to know "is the developer iterating or landing?", but it does not silently hide cross-platform breakage. Slice 1 keeps the marker semantically clean: "I am iterating, please don't surprise me with cross-platform configure cost."

Common pitfalls

• Forgetting to exit focus mode before landing — pulp loop --off is one extra keystroke, but it's how you preserve the "single-platform for iterating, cross-platform for landing" separation. The ship path validates regardless, but the marker should match reality.
• Locally hacking around a framework gap instead of filing it — easy to fall into, especially when you're in flow. The skill prompts upstream issue-filing as the preferred path; resist the local-fix temptation.
• Drifting past merged upstream PRs — the --watch-issues monitor (Slice 3) is the structural answer. Until then, set a 5-minute timer or pin the gh pr list watch in a side terminal.
• ar-swap leaving SDK in inconsistent state — header vs .a vtable mismatch is the trap. Slice 2's helper refuses on mismatch; until then, nm -gU the patched object before splicing and delete the local archive after validation.
• Multiple worktrees on different focus platforms — the marker is per-PULP_HOME, so two worktrees pointing at the same ~/.pulp/config.toml share the marker. If you're working on macOS in one worktree and want a Linux focus check in another, use PULP_HOME=/tmp/pulp-linux pulp loop --platform=linux.

Slash command

The Claude Code slash command lives at .claude/commands/prototype-loop.md. It asks the user to confirm the focus platform, then orchestrates the loop.

Reference

• Issue: #940 — Codify the leveraged-prototype dev loop
• Validation example: pulp #924 + spectr#28
• Original 2026-04-28 coverage report: spectr feature/native-react-editor branch, planning/spectr-style-coverage-report.md
• Companion docs: docs/guides/focus-mode.md