Your Documentation's Unit of Work Is Wrong: Write Retrievable Concepts, Not Documents
If the primary reader is a retrieval-augmented agent, the authoring unit must be the fragment the retriever returns, not the document a human reads start to finish; teams that keep reusing human READMEs as agent context pay for narrative they cannot retrieve and lose the explicit links that make fragments interpretable in isolation.
AngleTake the agent-vs-human doc contrast as a structural claim about authoring granularity, then derive concrete authoring rules: one concept per unit, explicit outbound links, headings sized for context assembly, no onboarding narrative, no screenshots.
Source video ↗The Only Architectural Decision That Matters in LLM Pipelines Is Where You Put the Deterministic Check
The durable pattern in LLM-generated artifact pipelines is not the model or the prompt but the explicit fence between nondeterministic generation and deterministic validation — that fence is what makes it defensible to let generated output enter version control through an automated PR, and it is the natural attachment point for schema conformance, link validity, and staleness gates.
AngleRead the init/update pipeline as a reference architecture for generated derived state, argue that pipelines without a named deterministic stage are silently pushing validation onto human reviewers, and show how to place the gate and what to assert there.
Source video ↗Agent Efficiency Gains Are Discovery-Shaped, and Your Metrics Are Hiding It
Structured context artifacts attack orientation overhead, not execution or reasoning cost — a claim visible only when you measure per tool-call category — so any team citing aggregate token reductions as justification for agent memory investments is likely claiming ROI from a mechanism that cannot touch the majority of the task loop.
AngleContrast the steep drops in file-enumeration calls against the near-flat shell output and success-rate numbers, then prescribe per-tool-category instrumentation as the minimum bar for evaluating agent context interventions.
Source video ↗One Doc Serving Two Readers Is a Fiction: Budget for a Derived Human Layer
Optimizing content for machine consumption degrades human comprehension, and the need to bolt human-oriented diagrams onto an agent-first wiki is evidence, not an edge case; the correct response is to make the human layer an explicit derived rendering of the machine schema rather than compromising the schema or maintaining two authored sources of truth.
AngleUse the Mermaid addendum as a falsifiable signal that a single artifact cannot satisfy both readers, then lay out the derived-rendering architecture and the drift-detection it requires.
Source video ↗Tool-Call Category Auditor for Agent Context Interventions
beyond-evalsIn structured-context interventions, discovery-class tool calls (file enumeration, glob, find, grep) compress by more than 30% while execution-class calls (shell, edit, test) move by less than 10%, so any single aggregate percentage misrepresents where the savings originate and cannot predict ROI for execution-heavy workloads.
Proof of conceptA harness that runs a fixed task set twice — with and without an injected typed concept index — instrumenting every tool invocation by category, logging counts, output tokens, and per-task success, then reporting per-category deltas with confidence intervals across multiple seeds and repositories.
MeasurementPer-category tool-call counts and output tokens (delta and variance), success rate, and the ratio of discovery savings to execution savings per task; falsified if category deltas are uniform or if execution calls drop comparably to discovery calls.
Source video ↗Schema Gate: Deterministic Validation Stage for Generated Repository Artifacts
gatehouseA deterministic post-generation pass (front-matter schema conformance, link resolution, staleness detection against git history) rejects a measurable and categorizable fraction of generated artifacts, and gating on it raises the merge-without-modification rate and lowers human review latency on auto-opened PRs.
Proof of conceptImplement a validator over typed front matter plus the link graph, wire it between agent generation and PR creation in a CI workflow, and run it on generated documentation PRs over a full update cycle, logging every failure by category rather than only pass/fail.
MeasurementFailure rate and category distribution per run, pass rate after remediation, human edit distance on merged PRs, review latency, and merged-without-modification percentage; falsified if the gate blocks almost nothing or if gated PRs show no review-cost reduction.
Source video ↗Dual-Render Compiler: Deriving the Human Layer from the Agent Schema
newA human-consumable layer generated deterministically from a typed concept graph (narrative assembly plus diagrams from explicit links) achieves human comprehension parity with hand-written docs while keeping agent retrieval cost unchanged, which means the two-reader problem is a rendering problem rather than a duplication problem.
Proof of conceptBuild a renderer that takes typed, self-contained concept fragments plus their links and emits a narrative traversal with generated diagrams, then compare it against both the raw agent-facing artifacts and hand-authored human docs on the same repository content.
MeasurementHuman comprehension scores on a task-based quiz across the three representations, agent-side retrieval token and tool-call cost per representation, and measured drift between schema updates and rendered output; falsified if comprehension parity requires hand-editing the rendered layer or if the rendered layer degrades agent retrieval.
Source video ↗Break-Even Model for Continuously Generated Agent Documentation
movement-labAt the repository level, the full cost of agent-facing documentation — generation tokens, CI minutes, human review time per auto-opened PR — is recovered only above a task-volume threshold, and below that threshold the intervention is net negative despite positive downstream agent-side savings.
Proof of conceptInstrument one repository across a complete update cycle: meter generation tokens, CI compute, and review time per PR, and cross-reference against saved agent tokens and eliminated tool calls on that repository's task traffic.
MeasurementBreak-even task count and tokens per repository update cycle, cost-per-task-saved versus cost-per-update, and sensitivity to update frequency; falsified if break-even occurs at a task volume low enough to be effectively always satisfied.
Source video ↗