Conversation
Two full rewrites of README + the four design docs, each produced by a clean-context Opus subagent following one guide: - docs-draft-v2/ follows the distilled doc-writing rules - docs-draft-v3/ follows the foundational research briefing Source docs under docs/ are unchanged. For A/B review: pick one to promote, then delete both draft dirs. Note: the v2 lifecycle draft also fixes a stale 'no browser terminal' claim that v3 and the live doc keep.
Synthesized the stronger half of each prior draft, then iterated every doc through a skeptical hiring-evaluator reader-test (clean-context Opus agents) plus a final editorial pass. Carried in: accurate browser-terminal framing in the lifecycle doc, IMDSv2 one-hop presented as the load-bearing control, teardown moved ahead of the caveats, real numbers instead of hedges, de-numbered flow headings, hook-first local-dev lede. Zero em dashes.
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.
Three full rewrites of the README and design docs, side by side, so we can pick a direction by reading rather than guessing. Not meant to merge as is: once we choose, the winner gets promoted into
docs/andREADME.md, and these draft directories get deleted.Each directory is the complete set (README plus architecture, security, lab-lifecycle, local-dev), produced by a clean-context agent under one guide:
docs-draft-v2/followed the distilled doc-writing rules.docs-draft-v3/followed the foundational research briefing (pushed harder on brevity and full-sentence prose).docs-draft-v4/is the hand-finished hybrid: the stronger half of each, then iterated through a skeptical reader-test and a final editorial pass.How to review: open the same file across the three directories and compare, or just read
docs-draft-v4/and comment on what to change. Inline comments are ideal; I will iterate on them.For reference, the live v1.0 docs and the optional lint setup live on a separate branch (
docs-lint-enforcement), not here.