docs: research/ layout convention (experiment journals)#426
Draft
obj-p wants to merge 2 commits into
Draft
Conversation
…igration policy Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Bi4bG4Dtkc5GTYqkoUkGdB
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Bi4bG4Dtkc5GTYqkoUkGdB
obj-p
commented
Jul 22, 2026
| **Question.** The single hypothesis this experiment tests. | ||
|
|
||
| **Environment.** What it needs: host tier (VM-free) or vzy snapshot | ||
| (`post-xcode`, `post-xcode-sip-amfi`, …); toolchain requirements; the |
Owner
Author
There was a problem hiding this comment.
Remove this parenthesis. Those details grow stale (e.g. post-xcode). The vzy script should be self documentating.
| Experiments that guide the architecture of PreviewsMCP. Each experiment | ||
| validates a claim about Xcode, swiftc, LLVM, or macOS that an architectural | ||
| decision rests on, and stays re-runnable so the claim can be re-checked when | ||
| the toolchain moves (a new Xcode or macOS major). Non-shipping: nothing here |
Owner
Author
There was a problem hiding this comment.
Why do we even need the Non-shipping line?
| claim still holds on the current toolchain; red means drift. VM-dependent | ||
| reproductions boot the snapshot they need via | ||
| [vzy](https://github.com/obj-p/vzy). | ||
| - **Capture** — the exception, for one-off empirical data that is too costly |
Owner
Author
There was a problem hiding this comment.
I think it's okay to commit abbreviated captures as long as it's a scripted result and reproducible. It's nice to have the output immediately for context.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Standardizes the
research/layout so every experiment reads as a journal: what it asks, how to run it, what it found, and whether the claim still holds on the current toolchain.What this adds
research/README.mddefining:reproduce.shre-runs the experiment and asserts against a committed expectation; red = toolchain drift) and capture (frozen one-off data marked with the environment it was taken in).previews-research,previews-research-3201,archive/*): no bulk copy — redo high-leverage findings against the current toolchain, restart from the committedjit-poc/andpreviews-re/, select by leverage.Out of scope (follow-ups)
jit-poc/README.mdandpreviews-re/README.mdto the template headings — reevaluated after the template settles.Draft to iterate on the template wording. No gates run yet.
🤖 Generated with Claude Code
https://claude.ai/code/session_01Bi4bG4Dtkc5GTYqkoUkGdB