diff --git a/.amplifier/AGENTS.md b/.amplifier/AGENTS.md index af4e1ab..53c8e33 100644 --- a/.amplifier/AGENTS.md +++ b/.amplifier/AGENTS.md @@ -161,3 +161,47 @@ Visual check at blog.ampbox.io v Commit + push ``` + +## Content Organization: Book, Not Blog + +The site is organized as a **book of investigations**, not a reverse-chronological +feed. Inspired by makingsoftware.com. Key principles: + +**Topics, not dates.** Content is grouped by investigation theme (e.g., "Rage: +Rebuilding the Build System" is a 5-post series, not 5 unrelated entries). Dates +are secondary metadata, not the primary navigation. + +**The homepage is a pitch, not an index.** Lead with a compelling excerpt, a +diagram, a question that creates intrigue. Show the reader what the content +quality is like before presenting any navigation. A flat list of article cards +is a cop-out. The homepage should make you curious. + +**Series are first-class.** Multi-post series (like the Rage build system series) +get their own landing page with a visual overview, progress indication, and +cross-links between posts. Individual posts link to their series context. + +**Figure density matters.** Target 1 visual per 300-500 words for technical posts. +Not decoration, but content: architecture diagrams, flow charts, before/after +comparisons, concept illustrations. If 500+ words pass without a visual, ask +what would replace them. + +**No blog chrome.** No comments, no share buttons, no "related posts" sidebar, +no newsletter popups, no social proof widgets. The content quality is the +credibility signal. If it needs a "clap" button, the writing isn't good enough. + +## Current Content Plan: Rage Series + +Source: kenotron-ms/rage repo + ~/workspace/family/Work/Reference/BuildXL spec + +| # | Title | Angle | Visuals Needed | +|---|-------|-------|----------------| +| 1 | Your Build Cache Is Lying to You | The silent stale cache problem. Make it concrete. | Flow: declared vs observed inputs. Before/after diagram of cache miss. | +| 2 | Two-Phase Fingerprinting: BuildXL's Deep Magic | WF→pathset→SF algorithm deep-dive. | Architecture: the two-phase lookup flow. Code walkthrough diagrams. | +| 3 | Hooking Syscalls Without a Kernel Driver | Three OS, three mechanisms. Most technically dense. | Side-by-side: macOS interpose / Linux eBPF / Windows Detours. Animated (Remotion): syscall interception flow. | +| 4 | TypeScript 7 Makes the Build Harness More Important | Counter-intuitive thesis. Widest reach. | Comparison: single-machine vs distributed. The parallelism table as a visual. | +| 5 | node_modules in a Content-Addressed Store | The unsexy problem that kills CI. | Flow: lockfile → CAS → hardlink restore. Before/after CI times. | +| 6 | What I Learned Maintaining Lage and Why I Rewrote It | Personal narrative, meta post. | Timeline: lage → BuildXL integration hack → rage. | + +Each post stands alone but gains context from the series. The series landing page +shows progress (like makingsoftware.com's progress bar) and creates anticipation +for upcoming posts.