docs: add blog with "How Piwi was built" post - #417
Merged
Conversation
Scaffold a VitePress blog under apps/docs/blog: an auto-updating index driven by a build-time content loader (posts.data.mts), a Blog entry in the top nav, and list styling scoped under .blog-list. New posts appear on the index automatically; no hand-maintained list. Add the first post — a four-part tour of the browser demo, the desktop app, auto-heal PRs, and AI steps — written to the docs voice and drawn from the feature sources, with a marked placeholder for the project's origin story. Blog pages set sidebar:false so they render with the doc layout without inheriting the docs journey sidebar. The loader is .mts so it bundles as ESM and can import from the ESM-only vitepress package. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Add a second blog post — a retrospective of the project's first eight months reconstructed from git history, adapted to a first-person blog voice and brought up to v0.25 (auto-heal PRs, share links) with a short "since then" coda. Replace the placeholder origin-story section in the four-part tour with a two-paragraph intro that links to the full genesis post. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Cut the day-by-day chronicle, the numbers and release-timeline tables, and the commit hashes. Keep six sections on the parts that were actually hard: the in-browser app, dual databases, failure clustering, locator healing and auto-heal PRs, and AI steps as a compiler. Mark six slots for personal opinion/story with HTML comments, to be filled from the author. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
The April–June commits are under my name but were not hand-written: that was a surgical phase assisted by DeepSeek V4 Flash. Rewrite the "three assistants" section so the record is Copilot → DeepSeek → Claude, and note in the open story slot that the under-my-name commit count is not solo work. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Merge the four-part tour into the genesis so there is a single "how it was built" post covering every hard part, and remove the tour; its one unique topic, the desktop app, is folded in as a brief entry. Rewrite the prose without em dashes so it reads as hand-written. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Fill two of the author story slots in the author's voice: a "Why I built it" section (the CyborgTests starting point, wanting no third-party dependency, building tools for team and community) and the demo-decision paragraphs (the Blazor/WASM playgrounds that inspired the in-browser app, and why an open-a-link demo matters). No em dashes. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Fill two more story slots: the dual-database decision (SQLite first, Postgres always planned, Drizzle, the migration reset once the LLM instructions held) and the locator-healing philosophy (developer decides, never magical, never a raw CSS selector), the latter corrected against the reporter and recipe docs. Promote the desktop app to its own section and add a browser-extension section, both grounded in their docs. Remove the desktop bullet from the brief list. Still no em dashes. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Two more feature sections grounded in the docs: the per-worker run timeline with its setup/test/wasted-waits/teardown span filter, and open in IDE with the confirmable-local-server versus fire-and-forget URL scheme distinction behind Auto. No em dashes. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Promote evidence gathering to a full section that tells its "storing to reconstructing" evolution, deepen failure clustering (deterministic fingerprint floor plus the semantic and human-in-the-loop layer), and add the missing AI-assisted diagnosis section: SCM-grounded diff window, relevance-ranked changed files, full-source context, and server-side patch validation, with the developer always deciding. Drop the evidence bullet from the brief list. No em dashes. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Give the post a clearer arc the reader can keep: why, the two rules the project follows, the failure-explaining pipeline (evidence, clusters, diagnosis, fix) as nested steps, then flaky-test pricing, the CI loop (gate, PR feedback, fix verification, agent fix plans), the ideas behind the demo, AI steps and the databases, and the surrounding tools. Bold the key takeaways throughout. Add the parts the docs cover that the post missed: flaky scoring and wasted-CI-minutes impact, quarantine with a way out, the CI gate, PR feedback with CODEOWNERS ownership, fix verification's three verdicts, MCP fix plans, and brief-list entries for sharding, run imports, offline export and share links, notifications and analytics. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Widen the section to "Flaky tests and wasted time": waitForTimeout sleeps classified as wasted time with configurable patterns and view-time re-classification, and the timeout advisor surfacing oversized timeouts and stale test.slow() marks with the reclaimable minutes. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Add three new diagrams in the house style (failure-loop, demo-in-browser, piwi-ecosystem) and wire eight figures into the post: the live-run poster up top, the loop under the heart intro, the fingerprint diagram in clustering, the diagnosis screenshot, the healing capture diagram, the flaky tab screenshot, the in-browser demo architecture, and the ecosystem map opening the toolbox. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
The traces prop can arrive as a non-array value, so `props.traces.length` was undefined and the summed evidence count rendered as NaN in the section header. Read both attachments and traces through Array.isArray guards so the count stays numeric. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
…ptures Add three docs screenshot scenes (gather-evidence, run-timeline, ai-diagnosis), all captured in dark theme, and a run-timeline data-shot anchor on WorkersTimeline. ai-diagnosis is now produced by a scene (cluster 10 with its stored, verified diagnosis) instead of the marketing pipeline, so it leaves the external allowlist. Wire the images in: the post gains evidence and run-timeline figures and refreshes the diagnosis one; evidence.md and the faster-suite recipe get the evidence and timeline shots. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Fill the three-assistants section with the author story: Copilot in Rider as the unblocker on a personal .NET project, discovering the cloud agent, and the honest emotional beat, ahead of the factual Copilot/DeepSeek/Claude arc for Piwi itself. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Expand the three-eras section with the full journey: Copilot in Rider as the unblocker, the cloud agent and the army-of-developers feeling with its overconfidence caveat, the opencode and DeepSeek spring at near-zero cost, then Claude Code with plan and execute roles, and the weekly step-back lesson. Close the post with the slower stabilization rhythm and the two questions every new idea must answer. All author story slots are now filled. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Retitle the assistants section to match its content, anchor the toolbox intro to the failure loop by name, and widen the desktop availability note beyond Linux. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
…tions Lead the desktop section with the capabilities only a desktop app can provide (local re-runs with the bundled Node, one-click MCP client setup, disk-path imports, folder-linked projects) and compress reporter discovery to one sentence. Give the extension its test-functions story a full paragraph: the reviewed catalog, live ranking while recording, exports that call your own functions, and the against-this-page checklist. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Cut the post from 82 bold spans to a handful per section so emphasis reads again, keeping only the strongest phrase in each and the structural bullet labels. Remove the dollar figures and credit references from the assistants story, keeping the tool and model journey. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
…oject-uawswl # Conflicts: # apps/docs/.vitepress/config.mts
Give the two strongest sections the missing depth. AI steps now shows the naive locator-cache that churns git, the committed artifact JSON, the canonical byte-stable file, and the pre-armed waitForResponse race. Healing shows what the passing-run probe records, the probe-per-resolution blowup and the dedupe-by-call-site fix, and why capture only fires on a single resolved element. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Explain where the name came from (Playwright Dashboard renamed over a Microsoft trademark worry, PW heard as pi-wi) at the end of "Why I built it", and replace the flat footer with a warm, actionable close that ties back to the opening pain and folds in the MIT and demo offering. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j
Contributor
Coverage Report for Reporter (./packages/reporter)
File CoverageNo changed files found. |
Contributor
Coverage Report for Application (./apps/application)
File CoverageNo changed files found. |
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
2 participants
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.
What & why
Adds a blog section to the documentation site with the first post: "How Piwi was built", a detailed technical narrative covering the eight-month development of Piwi, its core architecture, and the two guiding principles behind all design decisions.
The post explains:
Also includes:
posts.data.mtsfor build-time post indexing,blog/index.mdfor the listing pagegather-evidence.png,run-timeline.png) and updatedai-diagnosis.pngfor the postcustom.cssfor post listingsTestCaseEvidenceCard.vueto safely handle undefined attachment/trace arraysHow was it tested?
Checklist
docs: ...)apps/docs/— new blog post, diagrams, screenshots, styling)https://claude.ai/code/session_011QZAWkvGnmB38Sjnj5P68j