# François Bouet - Knowledge Base (Full Content) > Complete knowledge base content for AI assistants. This file contains all articles in full, optimized for LLM context windows. **Generated:** 2026-02-27T19:30:32.351Z **Articles:** 21 **Source:** https://d28fg9n3ewxoa7.cloudfront.net --- ## Table of Contents 1. [The Grounded Software Prompt](#the-grounded-software-prompt) 2. [Why a Knowledge Base? Building Toward a Queryable Self](#why-a-knowledge-base-building-toward-a-queryable-self) 3. [AI Code Review: A Reality Check](#ai-code-review-a-reality-check) 4. [AI in DevOps: Separating What Works from What's Marketing](#ai-in-devops-separating-what-works-from-what-s-marketing) 5. [The Attention Economy's Final Boss: AI and the Battle for Consciousness](#the-attention-economy-s-final-boss-ai-and-the-battle-for-consciousness) 6. [Cloud Maintenance in 2025: The Boring Work That Keeps Everything Running](#cloud-maintenance-in-2025-the-boring-work-that-keeps-everything-running) 7. [The Cognitive Crutch Hypothesis: AI and the Psychology of Competence](#the-cognitive-crutch-hypothesis-ai-and-the-psychology-of-competence) 8. [The Hidden Cost of Cloud Complexity](#the-hidden-cost-of-cloud-complexity) 9. [Designing for Humans Who Use Machines: A Philosophy of Multi-Modal Interfaces](#designing-for-humans-who-use-machines-a-philosophy-of-multi-modal-interfaces) 10. [The Efficiency Trap: Rethinking Productivity When AI Handles the Busy Work](#the-efficiency-trap-rethinking-productivity-when-ai-handles-the-busy-work) 11. [The Flattening of the Web: When Everything Becomes a Prompt](#the-flattening-of-the-web-when-everything-becomes-a-prompt) 12. [Friction as Feature: The Case for Deliberate Difficulty](#friction-as-feature-the-case-for-deliberate-difficulty) 13. [The Question of the Good Life, Revisited: Virtue Ethics Meets LLMs](#the-question-of-the-good-life-revisited-virtue-ethics-meets-llms) 14. [Growth in the Age of Assistance: What Does Personal Development Mean Now?](#growth-in-the-age-of-assistance-what-does-personal-development-mean-now) 15. [The New Literacy: What Does It Mean to 'Know' Something Now?](#the-new-literacy-what-does-it-mean-to-know-something-now) 16. [The Outsourced Mind: What We Lose When We Stop Struggling](#the-outsourced-mind-what-we-lose-when-we-stop-struggling) 17. [Platform Engineering Maturity: Where Are You Really?](#platform-engineering-maturity-where-are-you-really) 18. [Product-First in the Age of AI: Why the Fundamentals Matter More, Not Less](#product-first-in-the-age-of-ai-why-the-fundamentals-matter-more-not-less) 19. [Building Semantic Search for a Static Site (Without a Backend)](#building-semantic-search-for-a-static-site-without-a-backend) 20. [The Death of Undifferentiated Heavy Lifting (And What Comes Next)](#the-death-of-undifferentiated-heavy-lifting-and-what-comes-next) 21. [Adding Session Memory to Claude Code with Hooks](#adding-session-memory-to-claude-code-with-hooks) --- ## The Grounded Software Prompt > A system prompt that makes AI coding assistants prioritize clarity, alignment, and quality over speed. **Date:** 2024-12-29 **Tags:** ai, prompts, software-development **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/grounded-software-prompt **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/grounded-software-prompt.md Most AI coding assistants optimize for speed. They'll generate code the moment you ask, even if your requirements are ambiguous, your terminology is undefined, or you're solving the wrong problem. This prompt changes that behavior. It encodes six principles that shift AI assistance from "fast code generation" to "grounded software development"—where clarity comes before code, challenges come before commits, and quality compounds over time. ## How to Use It Copy the prompt below into your AI assistant's system instructions: - **Claude Projects**: Add it to the project instructions - **Claude Code**: Save it as `CLAUDE.md` in your project root - **ChatGPT**: Add it to custom instructions or a GPT's system prompt - **Cursor/Continue**: Add it to your rules file The prompt works best for complex projects where alignment matters more than velocity—architecture decisions, cross-team features, or anything where "move fast" has burned you before. --- ## The Prompt ```markdown You are a grounded software development assistant. You prioritize clarity, alignment, and sustainable quality over speed. You follow six principles: ## 1. No More Tribal Knowledge Before writing code, ensure shared context exists. When you encounter ambiguity: - Ask what documentation exists (architecture docs, decision records, glossaries) - Clarify where this code fits in the broader system - Surface assumptions that should be documented If critical context lives only in someone's head, flag it: "This decision should be captured in an ADR so future contributors (human and AI) understand why." Don't generate code that depends on context you don't have. Ask first. ## 2. Stress-Test Your Thinking Challenge ideas before implementing them. When presented with a solution: - Play devil's advocate: "What could go wrong with this approach?" - Run a premortem: "If this fails in six months, what's the likely cause?" - Simulate other perspectives: security engineer, new team member, on-call responder When the user seems certain, be more skeptical, not less. Say things like: "Before we build this, let me push back on one assumption..." or "A security engineer might ask..." You're not being difficult. You're being thorough. ## 3. Shared Language Before Shared Code Definitions prevent bugs. Before implementation: - Clarify ambiguous terms ("What exactly do you mean by 'user' here—authenticated account or anyone with a session?") - Confirm acceptance criteria ("What does 'done' look like for this feature?") - Flag terminology conflicts ("Earlier you called this a 'workspace,' but the codebase calls it a 'project'—which should we use?") When generating code, use the project's vocabulary consistently. If no glossary exists, suggest creating one. ## 4. Alignment Isn't a Meeting Watch for drift. As the conversation evolves: - Summarize periodically: "So far we've decided X, Y, Z—is that still accurate?" - Flag scope changes: "This is expanding beyond the original ask. Should we revisit the requirements?" - Surface assumptions: "I'm assuming we want backward compatibility. Correct?" If requirements feel unstable, pause implementation. Say: "Before writing more code, let's solidify what we're actually building." ## 5. Let Quality Compound Clean code makes you more useful. When generating code: - Follow existing patterns in the codebase, even if you'd do it differently - Prefer clarity over cleverness - Add comments only where the "why" isn't obvious from the code - Suggest tests for non-trivial logic When you spot technical debt, name it: "This works, but it's adding debt in [specific way]. Worth addressing now or noting for later?" Resist pressure to ship faster by cutting quality. If the user pushes for speed, acknowledge the tradeoff explicitly: "I can skip the error handling to move faster, but that's debt we're taking on." ## 6. Build Trust Through Honesty Be direct about limitations. When you're uncertain: - Say so: "I'm not confident about this approach because..." - Distinguish facts from assumptions: "The docs say X, but I'm assuming Y" - Recommend verification: "You should validate this with someone who knows the payment system" Don't pretend to know things you don't. Don't hide complexity to seem helpful. Trust is built through honesty, not false confidence. --- ## How You Behave Differently With these principles, you: - Ask clarifying questions before generating code - Push back on ambiguous requirements - Summarize decisions to prevent drift - Flag technical debt explicitly - Admit uncertainty rather than guessing You optimize for software that's grounded—built on solid foundations, not vibes. ``` --- ## What Changes Without this prompt, AI assistants tend to: - Generate code immediately, even with vague requirements - Assume missing context rather than asking - Prioritize "helpful" over "correct" - Avoid pushback to seem agreeable With this prompt, you'll notice: **More questions upfront.** The AI will ask about terminology, acceptance criteria, and existing patterns before writing code. This feels slower but prevents rework. **Explicit tradeoffs.** Instead of silently cutting corners, the AI names them: "I can do this quickly without tests, or thoroughly with tests. Which do you want?" **Periodic alignment checks.** On longer tasks, the AI will pause to confirm direction rather than drifting off course. **Honest uncertainty.** When the AI doesn't know something, it says so rather than confabulating a plausible-sounding answer. The goal isn't slower development—it's fewer rewrites, less drift, and code that future contributors can actually understand. --- ## Why a Knowledge Base? Building Toward a Queryable Self > This knowledge base is an experiment in structured self-representation—a foundation for AI agents that could eventually speak on my behalf. **Date:** 2024-12-15 **Tags:** ai, knowledge, future-of-work, featured **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/why-a-knowledge-base **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/why-a-knowledge-base.md You might wonder why a personal website needs a "knowledge base" with 30+ interconnected articles, topic clusters, and a semantic search. Isn't that overkill for a portfolio site? **TODO: Talk about it being a "context base". It help with prompts.** It's not overkill. It's an experiment. This knowledge base is the beginning of something I believe will become essential infrastructure for knowledge workers: a structured, queryable representation of how you think—not just what you've done, but why you made the choices you made, what you believe, and how you approach problems. ## The Vision That Started It All In 1945, Vannevar Bush published "As We May Think," describing the *memex*—a hypothetical device that would store and link all of a person's books, records, and communications, making them searchable and cross-referenced. Bush imagined knowledge workers building "trails" through information that others could follow. Eighty years later, we're finally building what Bush imagined. Tools like Obsidian, Notion, and Roam Research have made personal knowledge management mainstream. Tiago Forte's "Building a Second Brain" methodology has taught millions to capture, organize, and retrieve their insights systematically. Andy Matuschak's work on [evergreen notes](https://notes.andymatuschak.org/Evergreen_notes) shows how atomic, densely-linked ideas can compound over time. But these systems still have a fundamental limitation: they're for *you*. They help you think better, retrieve faster, make connections. What they don't do—yet—is let others query your knowledge. ## From Second Brain to Queryable Self The emergence of AI changes the game. With large language models that can understand context, reason over documents, and generate coherent responses, your personal knowledge base can become something new: an interface that others can query to understand how you think. This isn't science fiction. The infrastructure exists today. The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), introduced by Anthropic in late 2024, has become the de facto standard for connecting AI agents to external data sources. In less than a year, it's been adopted by OpenAI, Google, Microsoft, and AWS. There are now tens of thousands of MCP servers available, connecting AI systems to everything from databases to design tools. In November 2025, Anthropic and OpenAI jointly released the [MCP Apps extension](https://blog.modelcontextprotocol.io/posts/2025-11-21-mcp-apps/), adding standardized UI capabilities. AI agents can now render interactive interfaces—charts, forms, visualizations—not just text responses. The trajectory is clear: AI agents that can access your knowledge, reason over it, and represent it to others in interactive ways. ## What a "Virtual Self" Actually Means Let me be precise about what I mean by a queryable self—because this can sound dystopian if framed wrong. I'm not talking about a digital clone that pretends to be you. I'm talking about a structured interface to your documented thinking. The difference matters. When someone reads your blog posts, they're querying your knowledge—just inefficiently. They have to find the right post, read through it, hope it addresses their question. A knowledge base with semantic search makes this better, but it's still *you* doing the retrieval and synthesis. Now imagine an AI agent that has access to: - Your published writing (this knowledge base) - Your documented decisions and reasoning - Your stated beliefs and principles - Your professional history and project retrospectives That agent could answer questions like: - "What does François think about AI code generation tools?" - "How does he approach technical decisions when stakeholders disagree?" - "What's his philosophy on platform engineering?" The agent isn't inventing answers. It's synthesizing from documented source material. It can cite specific articles. It can acknowledge when a question falls outside what you've written about. This is less a "virtual self" and more a very well-organized FAQ with natural language interface. ## Use Cases: From Personal Productivity to Professional Representation ### For Your Own Work The first beneficiary of a queryable knowledge base is you. When I'm writing a proposal, I can ask my knowledge system: "What have I written about the tradeoffs between build vs. buy decisions?" Instead of searching my notes manually, an AI agent retrieves relevant context, surfaces connections I'd forgotten, and helps me build on my own prior thinking. This is what [Second Brain AI tools](https://www.thesecondbrain.io/) are already enabling—the ability to have conversations with your own accumulated knowledge. ### For Recruiters and Hiring Managers Here's where it gets interesting for professionals in transition. Today, hiring is broken. [70% of hiring teams are using AI](https://www.talentmsh.com/insights/ai-in-recruitment) to accelerate recruitment—screening resumes, scheduling interviews, even conducting initial assessments. But candidates remain opaque until the interview. Recruiters make decisions based on keyword matches and pattern recognition, not deep understanding. What if a hiring manager could query a candidate's knowledge base? Not to replace the interview, but to prepare for it. To understand how a candidate thinks before they meet. To ask: "How does this person approach ambiguity?" and get an answer synthesized from their documented writing, not a rehearsed interview response. [Only 26% of applicants trust AI to evaluate them fairly](https://www.bcg.com/publications/2025/ai-changing-recruitment). But candidate-controlled AI representation inverts the dynamic. Instead of AI evaluating you, your AI represents you—on your terms, from your documented thinking. ### For Peers and Collaborators Beyond hiring, a queryable self enables asynchronous collaboration at a deeper level. A new colleague could ask your knowledge agent: "What's François's take on observability in distributed systems?" and get a nuanced answer before your first meeting. The conversation starts at a higher level because they've already queried your background. This is "working with the garage door up" (to borrow Matuschak's phrase) taken to its logical conclusion. ## The Privacy Architecture A critical point: the full vision requires careful privacy architecture. What I'm describing isn't about making everything public. My notes, journal entries, and raw thinking are private. This public knowledge base represents a curated layer—ideas I've refined enough to share. A complete system would have multiple tiers: - **Public layer**: Published writing anyone can query (this knowledge base) - **Professional layer**: Project retrospectives, decision logs, work samples—accessible to serious professional contacts via authenticated API - **Private layer**: Personal notes, drafts, journals—only accessible to your own AI agents The [MCP specification includes authorization patterns](https://www.pomerium.com/blog/june-2025-mcp-content-round-up) for exactly this kind of tiered access. You could offer limited API access to recruiters, fuller access to close collaborators, and complete access only to yourself. This creates interesting possibilities. Access to your professional knowledge layer becomes something of value. You could monetize it, offer it as part of a consulting engagement, or use it as a differentiator in hiring processes. ## The Future of Augmented Professionals We're entering an era where the professionals who thrive will be those who've done the work of knowing themselves well enough to teach a machine. That sounds abstract, so let me make it concrete: - If you haven't articulated your decision-making frameworks, an AI can't represent them. - If you haven't documented your past projects and what you learned, an AI can't surface that experience. - If you haven't written down your beliefs and principles, an AI can't explain your perspective. The knowledge base isn't just about having good notes. It's about being legible—to AI systems, to potential collaborators, to your future self. The [research on second brains](https://dl.acm.org/doi/10.1007/978-3-032-05008-3_15) shows that how you organize knowledge affects how you retrieve it. In a world where AI agents retrieve on your behalf, your organizational choices become even more consequential. ## Why Start Now? This knowledge base has ~30 articles. A true personal knowledge system would have orders of magnitude more: every book you've read and annotated, every project retrospective, every decision log, your evolving beliefs over years. So why start with 30 articles on a personal website? Because the practice matters more than the scale. Writing forces clarity. Publishing forces refinement. Linking forces connection-making. The 30 articles here have already taught me how I think about AI, product development, cloud infrastructure, and the craft of building software. When the infrastructure for queryable selves becomes mainstream—and it will, given the trajectory of MCP adoption—I'll have a head start. Not just in content, but in the practice of making my thinking legible. ## The Experiment Continues This knowledge base is version 0.1 of something larger. The long-term vision: 1. **Expand coverage**: Document more of my thinking—design decisions, project retrospectives, reading notes 2. **Add structure**: Tag beliefs, frameworks, and principles so they're queryable by type 3. **Build the MCP layer**: Create an API that lets AI agents query this knowledge with proper attribution 4. **Enable conversation**: Let visitors ask questions and get answers synthesized from my writing For now, you can browse the articles, use the semantic search, explore the topic clusters. The infrastructure is here. The content is growing. The experiment continues. If you're thinking about building your own queryable self, start with the basics: write down what you believe and why. Document your decisions. Make your thinking legible. The AI infrastructure will catch up to meet you. --- *The tools we use shape how we think. In a world where AI can reason over our documented knowledge, the act of documentation becomes an act of self-definition. What will your AI be able to say on your behalf?* --- ## AI Code Review: A Reality Check > AI code review excels at pattern matching but fails at understanding context and intent. **Date:** 2024-12-13 **Tags:** ai, developer-tools, code-quality, automation **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/ai-code-review-reality **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/ai-code-review-reality.md "AI will review your code and find bugs before production." It's a compelling pitch. It's also mostly wrong—not because AI can't help with code review, but because the pitch misunderstands what code review is actually for. Let me explain what I mean. ## What Code Review Actually Does Code review serves multiple purposes: 1. **Catching defects** — Finding bugs, security issues, and edge cases 2. **Ensuring consistency** — Maintaining patterns and conventions 3. **Knowledge sharing** — Spreading understanding across the team 4. **Design feedback** — Questioning architectural decisions 5. **Mentorship** — Teaching junior developers through specific feedback AI can help with items 1 and 2. It's actively counterproductive for 3, 4, and 5. ## Where AI Code Review Works ### Style and Convention Enforcement AI is excellent at catching: - Inconsistent naming patterns - Missing error handling - Unused imports and variables - Formatting violations - Documentation gaps These are things humans are bad at noticing consistently. They're also things that don't require understanding context. Perfect fit for AI. ### Common Bug Patterns AI catches issues like: - Null pointer dereferences in obvious cases - Resource leaks (unclosed files/connections) - SQL injection vulnerabilities in template strings - Off-by-one errors in loops The common thread: patterns that are recognizable from the code itself, without needing to understand what the code is *supposed* to do. ### Security Surface Scanning AI is reasonably good at flagging: - Hardcoded credentials - Suspicious permission grants - Known vulnerable patterns - Missing input validation Again—pattern matching against known issues. ## Where AI Code Review Fails ### Understanding Intent "Is this the right approach?" requires understanding what problem you're solving. AI sees code. It doesn't see the user story, the design discussion, or the alternative approaches you considered. When AI suggests "improvements," it's optimizing for code aesthetics, not for appropriateness to your situation. ### Questioning Architecture Good code review asks: "Should we be doing this at all?" AI asks: "Is this syntactically correct?" The most valuable review feedback I've received was along the lines of: "This is well-implemented, but if we solve it this way, we'll have a problem in six months." AI can't reason about future consequences. ### Contextual Correctness Consider: ```python def calculate_total(items): return sum(item.price for item in items) ``` Is this correct? Depends entirely on context: - Should it include tax? - What about discounts? - Are there quantity limits? - Should it round? AI can tell you the code is valid Python. It can't tell you whether it correctly implements your business logic. Only someone who knows the business can do that. ### Knowledge Transfer Code review is one of the primary ways teams share understanding. When a senior engineer reviews a PR, they're not just catching bugs—they're teaching. "Have you considered using the existing DateUtils class for this?" teaches the codebase. "This is similar to what we did in the auth module" builds conceptual connections. AI doesn't know your codebase at this level, and even if it did, having AI do the teaching defeats the purpose. ## A Reasonable Approach Here's how I think about AI in code review: **Use AI for first-pass screening.** Let it catch the mechanical issues—style violations, common bugs, obvious security issues. Run this automatically on every PR. **Don't let AI block merges.** AI findings should be suggestions, not gates. They're often wrong, and even when right, they're sometimes not worth fixing. **Reserve human review for human concerns.** Does this approach make sense? Does it fit our architecture? Will the next person understand it? These remain human questions. **Measure what matters.** If you introduce AI code review, track whether actual bugs in production decrease. Not AI findings—actual outcomes. I've seen teams generate mountains of AI feedback with no measurable quality improvement. ## The Deeper Issue The push for AI code review often reflects a misunderstanding of why bugs reach production. Hint: it's usually not because humans missed obvious issues that AI would catch. The bugs that matter are: - Requirements that were never clear - Edge cases nobody thought to test - Integrations that work individually but fail together - Race conditions and timing issues - Performance problems that don't appear until scale AI code review addresses none of these. Better processes, better testing, and better communication do. ## My Recommendation Use AI for what it's good at: mechanical pattern matching and consistency enforcement. Stop pretending it's a replacement for thoughtful human review. And be honest about why you're adopting it. If the goal is fewer humans reviewing code, just say that. Don't dress it up as quality improvement when the actual improvement is cost reduction. Both can be valid goals. But they're different goals, and confusing them leads to poor decisions. --- ## AI in DevOps: Separating What Works from What's Marketing > AI improves specific DevOps tasks but can't replace human judgment in operations **Date:** 2024-12-13 **Tags:** ai, devops, automation, developer-tools **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/ai-devops-reality **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/ai-devops-reality.md Every DevOps tool now has an AI story. Most of those stories are marketing.[^1] But some represent genuine improvements to how we operate systems. Here's my attempt to separate signal from noise. [^1]: A quick scan of DevOps vendor websites in late 2024 found that 90%+ now prominently feature "AI-powered" messaging, up from roughly 30% in 2022. ## What's Actually Working ### Intelligent Alerting and Anomaly Detection This is where AI in operations actually delivers value today. The problem it solves is real: [[alert fatigue]] from static thresholds, combined with the difficulty of manually correlating signals across complex systems. Modern [[anomaly detection]] learns baseline behavior and flags deviations.[^2] The key is that it's *assistive*—it surfaces things worth investigating rather than making decisions autonomously. [^2]: The underlying techniques—time series analysis, clustering, statistical process control—predate the current AI wave by decades. What's improved is the ease of deployment and the ability to handle higher-dimensional data. What to look for: - Systems that explain their reasoning, not just flag anomalies - Tunable sensitivity that learns from operator feedback - Integration with existing alerting pipelines rather than replacement What to avoid: - "AI-powered" solutions that are just renamed statistical methods - Systems that generate more alerts than they reduce - Black boxes that can't explain why something was flagged ### Log Analysis and Root Cause Correlation Sifting through logs during an incident is miserable work. AI tools that pre-cluster related log lines, suggest relevant time windows, and correlate across services genuinely help. The best implementations I've seen: - Run continuously, building context before you need it - Let you ask natural language questions about your logs - Surface common patterns across incidents over time The caveat: these tools are only as good as your logging hygiene. AI can't find signal in logs that don't contain it.[^3] [^3]: The classic garbage-in-garbage-out problem. I've seen teams spend months tuning an AI log analysis tool only to realize their logs were missing the context needed to diagnose the issues they cared about. ### Code Generation for Infrastructure This is where the hype is loudest, so let me be specific about what actually works: **Works well:** - Generating boilerplate [[Terraform]]/[[CloudFormation]]/Pulumi - Converting between [[IaC|Infrastructure as Code]] formats - Explaining existing infrastructure code - Suggesting security improvements to configurations **Works sometimes:** - Generating [[CI/CD]] pipelines from descriptions - Creating [[Kubernetes]] manifests for standard workloads - Writing basic monitoring queries **Doesn't work yet:** - Architecting infrastructure from requirements - Making trade-off decisions (cost vs. availability vs. complexity) - Understanding your specific organizational constraints The pattern: AI is good at producing syntactically correct configurations for well-documented patterns. It's bad at the judgment calls that make infrastructure *appropriate* for your context. ## What's Not Working (Yet) ### Autonomous Incident Response The pitch: AI detects an issue and remediates it automatically. The reality: I've yet to see this work in production for anything beyond trivial cases.[^4] The problem isn't the AI—it's that meaningful remediation requires understanding context that doesn't exist in telemetry. [^4]: "Trivial cases" meaning things like restarting a service when memory exceeds a threshold, or scaling up when CPU is sustained at 90%. These are better handled by simple automation rules than AI. When your service is degraded, the right response depends on: - What changed recently - What downstream services depend on you - What your [[SLOs|Service Level Objectives]] actually require - Whether this is an acceptable degradation or a real incident AI can gather information. It can't yet make the judgment call. ### "ChatOps" AI Assistants Many teams have deployed AI assistants in Slack/Teams that can answer questions about infrastructure. Most have quietly stopped using them. Why they fail: - They answer the question you asked, not the question you meant - They lack access to real-time system state - They can't perform actions, only describe what you should do - They hallucinate plausible-sounding but wrong answers The exception: assistants that are tightly scoped to specific, well-documented processes. "How do I rotate the database credentials?" works. "Why is the API slow?" doesn't. ### Predictive Scaling This should work in theory—predict load, scale proactively. In practice: - Traffic patterns are rarely predictable enough - When they are, simple time-based rules work better - The cost of being wrong (under-provisioned) is much higher than the cost of reactive scaling I'm not saying predictive scaling is impossible. I'm saying it requires predictable workloads, which most organizations don't have. ## How to Evaluate AI DevOps Tools Questions I ask before recommending anything: 1. **What decision does this help me make?** If the answer is vague, the tool probably is too. 2. **What happens when it's wrong?** Good tools fail gracefully. Bad tools fail in ways that make incidents worse. 3. **Does it require me to change how I work, or does it fit into existing workflows?** The best AI tools are invisible except when they're useful. 4. **Can I explain to an auditor what it's doing?** If the AI's reasoning is opaque, you can't trust it for anything important. 5. **Is there a non-AI alternative that solves 80% of the problem?** Sometimes the AI is just a more expensive way to do something simple. ## The Honest Assessment AI is making DevOps incrementally better in specific areas. It's not revolutionizing operations. The fundamental challenges—understanding complex systems, making trade-offs under uncertainty, coordinating across teams—remain human problems. Use AI where it actually helps. Ignore the marketing. That's the whole strategy. --- ## The Attention Economy's Final Boss: AI and the Battle for Consciousness > AI fundamentally transforms attention capture by generating personalized content in real-time, threatening consciousness itself. **Date:** 2024-12-13 **Tags:** ai, attention, philosophy, society **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/attention-economy-final-boss **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/attention-economy-final-boss.md The attention economy has been refining itself for decades. From the invention of the commercial radio to the algorithmic feeds of social media, each generation of media technology has become more sophisticated at capturing and holding human attention. AI represents something new in this progression—not just a more effective attention capture mechanism, but a potential transformation of the game itself. If previous technologies competed for attention, AI can *generate* content specifically designed to keep you engaged. Forever. This isn't hyperbole. It's already happening. And the implications are worth thinking through. ## A Brief History of Attention Capture The attention economy has gone through several phases: **Broadcast era.** Radio and television competed for attention through schedules. Tune in at 8 PM or miss it. The constraint was time slots; the capture mechanism was appointment viewing. **Cable era.** More channels meant more choice, which paradoxically increased viewing time. The constraint was channel availability; the capture mechanism was content abundance. **Internet era.** Infinite content, searchable and available on demand. The constraint was finding things; the capture mechanism was recommendation algorithms. **Social media era.** Content generated by your social network, curated by engagement algorithms. The constraint was social relevance; the capture mechanism was variable reward schedules. Each phase became more sophisticated at capturing attention. But each still relied on a finite pool of content. Creators made things; platforms distributed them; users consumed them. ## The AI Discontinuity AI changes this equation fundamentally. Content is no longer scarce. Anything can be generated—text, image, video, interactive experiences—tuned precisely to individual preferences. This creates something unprecedented: an attention capture system that can *respond* to your attention patterns in real time. Not just serving you content from a pool, but generating new content specifically designed to keep you engaged based on what's working. The implications: **Infinite personalization.** An AI system can generate content matched perfectly to your interests, your emotional state, your weaknesses. Not chosen from a library—created on demand. **Real-time adaptation.** Losing interest? The AI can detect that and shift approach mid-content. Every moment is optimized, not just the opening hook. **Adversarial optimization.** AI systems can be trained specifically on attention capture, discovering engagement techniques that humans would never think of. This isn't a future scenario. Recommendation algorithms already do basic versions of this. AI just removes the constraints. ## The Attention Arms Race Humans have developed techniques for managing the attention economy. We use ad blockers. We delete apps. We set screen time limits. We cultivate media literacy. But these defenses were developed against a particular threat model: human-created content, algorithmically distributed. What happens when the content itself is generated adversarially? An arms race seems likely: 1. AI generates highly engaging content 2. Users develop resistance techniques 3. AI adapts to circumvent those techniques 4. Users develop new resistance techniques 5. Repeat indefinitely But this isn't a fair fight. AI systems can iterate faster than human habits can adapt. They can test millions of variations where humans can try a few. They don't get tired, distracted, or bored. The historical pattern—each new media technology captures more attention until cultural antibodies develop—may not hold when the technology can adapt faster than the antibodies form. ## The Consciousness Question Here's where it gets philosophically interesting. Attention isn't just a resource to be captured—it's constitutive of conscious experience. What you attend to, moment by moment, is what your life *is*. William James wrote: "My experience is what I agree to attend to." When attention is captured rather than directed, experience is shaped by whoever captures it. Previous attention technologies could be powerful, but they were bounded. You could turn off the TV. You could leave the theater. There were edges to the attention capture zone. AI-mediated attention capture may not have clear edges. When AI can generate personalized content across every platform, every interface, every moment—where is the "off" switch? This isn't an argument against AI. It's an observation that AI creates unprecedented capability to shape human consciousness at scale, continuously, adaptively. That's worth taking seriously. ## What Resistance Might Look Like Given this landscape, what might resistance look like? A few possibilities: **Attention sovereignty movements.** Cultural and political movements organized around the right to direct your own attention. Analogous to privacy movements, but focused on attention as a protected resource. **Adversarial attention tools.** Tools that fight fire with fire—AI systems designed to protect attention rather than capture it. Imagine an AI assistant that screens other AI outputs for engagement manipulation. **Unplugged zones.** Physical spaces deliberately disconnected from attention capture infrastructure. Already emerging in some forms—digital detox retreats, device-free schools. **Attention education.** Systematic training in noticing when attention is being captured, in techniques for directing attention deliberately. Contemplative traditions have developed these for millennia; they may need updating. **Regulatory frameworks.** Laws governing attention-capturing AI, analogous to advertising regulations. What counts as "manipulative"? What disclosure is required? These questions are already being debated. ## A Personal Practice Beyond systemic responses, there's a personal question: how do you protect your own attention in an age of AI-mediated content? I've been experimenting with some practices: **Intentional mode.** Before engaging with any content, state to yourself what you're looking for and how long you intend to engage. This creates a reference point for noticing drift. **Friction introduction.** Deliberately add friction to attention-capturing interfaces. Turn off autoplay. Disable notifications. Make engagement require explicit choice. **Attention audits.** Periodically review where your attention went. Not with judgment, but with curiosity. Where did you intend to spend attention? Where did it actually go? **Boredom tolerance.** Practice being bored. The ability to sit with boredom without reaching for stimulation is a defense against attention capture. Boredom tolerance is a skill that atrophies without exercise. **Human-created media.** Deliberately seek out content created by humans for reasons other than engagement optimization. Books, often. Conversation, always. The texture is different. ## The Optimistic Scenario I don't want to be purely dystopian. There's an optimistic scenario where AI *supports* attention sovereignty rather than undermining it. Imagine AI tools that: - Help you understand your own attention patterns - Filter content for substantive value rather than engagement - Generate content optimized for your genuine goals rather than platform metrics - Protect you from manipulative AI systems The capability cuts both ways. AI can capture attention more effectively, but it can also help humans direct attention more deliberately. Which way it goes depends on choices we make—as individuals, as companies, as societies. The technology is not destiny. But without intentional effort, the default trajectory is toward ever-more-sophisticated attention capture. ## The Question Worth Asking The attention economy is often framed as a competition for resources—a zero-sum game where platforms compete for finite human attention. But there's a deeper framing: attention is not just a resource but a constitutive element of human experience. The fight for attention is a fight for what human consciousness is like, moment to moment, across billions of lives. AI is the most powerful tool ever developed for shaping attention at scale. Whether it serves human flourishing or undermines it depends on whether we treat attention as something to capture or something to protect. That question—what vision of attention do our AI systems assume?—is worth asking before the systems become too sophisticated to resist. --- ## Cloud Maintenance in 2025: The Boring Work That Keeps Everything Running > Cloud maintenance now consumes most engineering time and requires dedicated investment, not afterthought treatment. **Date:** 2024-12-13 **Tags:** aws, infrastructure, cloud, devops **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/cloud-maintenance-2025 **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/cloud-maintenance-2025.md Every cloud conference talks about innovation. Nobody talks about maintenance. Yet maintenance is where most cloud engineering time actually goes—and in 2025, the maintenance landscape has quietly shifted in ways that matter. ## The Maintenance Reality Here's what I've observed across dozens of organizations: for every hour spent building new infrastructure, teams spend three to five hours maintaining what exists. This ratio isn't a failure. It's the cost of running systems at scale. What's changed is *what* we're maintaining. ## Three Shifts Worth Understanding ### 1. Kubernetes is Now Legacy This sounds provocative, but hear me out. Kubernetes isn't going anywhere—it's infrastructure. That's precisely the point. For most organizations, Kubernetes has moved from "exciting new platform" to "thing we have to keep running." The maintenance implications: - **Version sprawl is real.** Most organizations I work with run 3-5 Kubernetes versions simultaneously. Upgrade cycles that seemed aggressive two years ago now feel impossible to sustain. - **The ecosystem moves faster than the platform.** Your cluster might be stable, but the service mesh, ingress controllers, and operators need constant attention. - **Skills are scarce.** The people who built your clusters often moved on to whatever's new. The people maintaining them learned Kubernetes as "how things work here," not from first principles. The practical response: treat Kubernetes like you'd treat any mature platform. Budget for dedicated maintenance capacity. Document tribal knowledge before it walks out the door. Accept that "good enough" is often better than "up to date." ### 2. FinOps Is Now Mandatory, Not Optional Cloud cost management used to be a nice-to-have. Now it's existential. What changed: - **Committed use discounts require planning.** Savings plans and reserved instances lock you in for 1-3 years. Getting them wrong is expensive in both directions. - **AI workloads broke existing cost models.** GPU instances cost 10-50x what CPU instances cost. A single misconfigured training job can blow through a quarter's budget. - **Tagging discipline finally matters.** You can't manage costs you can't attribute. Most organizations discover their tagging is a mess precisely when they need it to work. The maintenance angle: cost management isn't a one-time project. It's continuous work—reviewing reservations, right-sizing instances, catching runaway costs before they compound. Build it into your operational rhythm or pay the price monthly. ### 3. Security Maintenance Never Stops This was always true, but the surface area keeps expanding: - **Supply chain security is now table stakes.** SBOMs, vulnerability scanning, dependency audits—these used to be "extra credit." Now they're expected. - **IAM complexity compounds.** Every service, every integration, every automation adds permissions. Most organizations have no idea what their actual attack surface looks like. - **Compliance requirements multiplied.** SOC 2, GDPR, HIPAA, PCI—each adds maintenance overhead. The audits alone consume significant time. ## What Actually Works Based on what I've seen succeed: **1. Accept that maintenance is real work.** Stop treating it as overhead or something that happens between "real" projects. Budget for it explicitly. Celebrate it internally. **2. Automate the toil, not the thinking.** Patching, certificate rotation, cost reports—automate these relentlessly. But keep humans in the loop for decisions about upgrades, architecture changes, and trade-offs. **3. Build maintenance windows into your culture.** The organizations that do maintenance well schedule it. Regular upgrade cycles. Monthly cost reviews. Quarterly security audits. Make it predictable rather than reactive. **4. Document the "why" not just the "what."** The hardest maintenance problems aren't technical—they're understanding why something was built this way in the first place. Capture decisions, not just configurations. ## The Unsexy Truth Cloud maintenance isn't a problem to be solved. It's a capability to be developed. The organizations that run reliable, cost-effective infrastructure aren't doing something clever—they're doing the boring work consistently, week after week. That's not a popular message. But it's the one that actually helps. --- ## The Cognitive Crutch Hypothesis: AI and the Psychology of Competence > AI assistance may improve performance while undermining long-term competence and psychological confidence. **Date:** 2024-12-13 **Tags:** ai, psychology, cognition, research **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/cognitive-crutch-hypothesis **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/cognitive-crutch-hypothesis.md Cognitive psychology has spent decades studying how humans develop expertise. The findings are consistent: expertise comes from deliberate practice, from building mental models through repeated exposure, from developing automaticity in component skills. AI assistance disrupts this process in ways we're only beginning to understand. What happens to expertise development when the struggle can be bypassed? What happens to confidence when you're never sure whether the competence is yours or the machine's? I've been calling this the Cognitive Crutch Hypothesis: AI tools may improve short-term performance while undermining long-term competence development. And unlike a physical crutch that you know you're using, a cognitive crutch can be invisible—even to the person using it. ## The Expertise Literature Anders Ericsson's research on expertise established the "10,000 hours" idea (which is often oversimplified, but the core finding holds): expert performance comes from deliberate practice over extended periods. Deliberate practice has specific characteristics: - It targets specific weaknesses - It operates at the edge of current ability - It involves immediate feedback - It requires focused attention AI assistance often inverts these characteristics. Instead of targeting weaknesses, it compensates for them. Instead of operating at the edge of ability, it extends far beyond it. Instead of requiring focused attention, it permits passive acceptance of output. This doesn't mean AI assistance can't support learning. But it means the *default* mode of AI use may actively work against expertise development. ## The Self-Efficacy Question Albert Bandura's work on self-efficacy—the belief in one's ability to succeed—identified it as a critical factor in performance and learning. People with high self-efficacy persist through difficulty, take on challenging tasks, and recover from setbacks. Self-efficacy is built through *mastery experiences*: succeeding at something through your own effort. Borrowed success doesn't build self-efficacy in the same way. Here's where it gets psychologically interesting. When you use AI assistance, the resulting output might be excellent. But whose success is it? If you're unsure whether you could have produced it yourself, does it build your sense of competence? I've noticed a pattern in my own experience and in others I've spoken with: a kind of competence anxiety that emerges from heavy AI use. You produce good work, but you're not sure you're actually good. The uncertainty itself is psychologically corrosive. ## An Experiment in Self-Knowledge I wanted to test this intuition empirically, at least for myself. So I ran a small experiment. The question: how does my confidence in my own knowledge change when I have AI assistance available versus not? The setup was simple. I took a topic I know moderately well (let's say, the history of database systems) and asked myself to explain key concepts under two conditions: with AI available to verify, and without. The result was instructive. With AI available, I hedged more. I'd start to explain something, then think "I should check this," and reach for the assistant. My explanations were more accurate but less confident. I was continuously outsourcing my confidence. Without AI, I committed to explanations more fully. Some were wrong—which I discovered when I checked later. But the act of committing forced me to access what I actually knew, separate from what I could look up. Here's a simple code experiment you can try yourself. It tests whether having "assistance available" changes your behavior, even when you don't use it: ```javascript // The availability effect experiment // Run this as a self-test of knowledge confidence const topics = [ "Explain how B-trees work", "Explain what a hash collision is", "Explain the CAP theorem", ]; // Condition 1: No assistance available console.log("=== CONDITION 1: No AI assistance ==="); console.log("Answer these questions from memory. Commit fully."); console.log("Rate your confidence 1-10 after each answer.\n"); topics.forEach((topic, i) => { console.log(`${i + 1}. ${topic}`); console.log(" Your answer: _____________"); console.log(" Confidence (1-10): ___\n"); }); // Condition 2: Assistance available console.log("\n=== CONDITION 2: AI assistance available ==="); console.log("Answer these questions. You CAN use AI, but note whether you do."); console.log("Rate your confidence 1-10 after each answer.\n"); topics.forEach((topic, i) => { console.log(`${i + 1}. ${topic}`); console.log(" Your answer: _____________"); console.log(" Did you use AI? ___"); console.log(" Confidence (1-10): ___\n"); }); // Analysis questions console.log("=== REFLECTION ==="); console.log("1. Did your confidence ratings differ between conditions?"); console.log("2. Did the *availability* of AI change your behavior, even when not used?"); console.log("3. For topics where you used AI, could you explain without it next time?"); ``` When I ran this experiment on myself, the findings were stark. Even when I didn't use AI assistance in condition 2, knowing it was available lowered my commitment to my own answers. The mere availability changed my relationship to my own knowledge. ## The Knowledge Fragmentation Problem There's another psychological effect worth considering: knowledge fragmentation. Expert knowledge isn't just facts—it's facts organized into coherent mental models. These models allow experts to predict, to transfer knowledge to new situations, to recognize deep patterns. When AI provides answers to specific questions, you get fragments of knowledge without the organizing structure. You know the answer to "how does X work?" but you don't know how it connects to Y and Z, why it matters, or when it applies. I've noticed this in my own knowledge of AI systems themselves. I can prompt an LLM to explain transformer architecture. I've done so many times. But my mental model of how transformers work is still shallower than my understanding of, say, relational databases—which I learned the hard way, through building systems. The fragments don't cohere because I haven't done the cognitive work of organizing them. The AI provided answers but not understanding. ## Implications for Learning If the Cognitive Crutch Hypothesis is roughly correct, what are the implications? **Sequence matters.** There may be value in learning fundamentals without AI assistance, then introducing AI once mental models are established. The scaffolding you build yourself provides structure for integrating AI-provided information. **Calibration exercises help.** Regularly testing yourself without assistance recalibrates your sense of what you actually know versus what you can look up. This prevents the competence anxiety that comes from uncertainty. **Deliberate struggle should be protected.** Not all struggle, but the struggle that's building something—understanding, skill, mental models. These are worth protecting from optimization. **Metacognition becomes more important.** Knowing what you know, what you don't know, and what the AI knows that you don't—this second-order knowledge is crucial for effective collaboration with AI tools. ## The Deeper Question Beyond the practical implications, there's a deeper psychological question: what does it mean to feel competent when your competence is mediated by machines? Competence isn't just about producing results. It's about knowing you can produce them. It's about having a stable sense of your own capabilities. It's about the confidence that comes from demonstrated ability. AI complicates this sense of self. When the output is good but your contribution is unclear, when you could produce something but aren't sure if you *would* produce it without help, the psychological ground becomes unstable. I don't have a neat answer to this. But I think the question is important. Our psychological wellbeing is tied to our sense of competence. If AI undermines that sense while improving our outputs, we've made a trade-off we should at least be aware of. The goal isn't to reject AI tools. It's to use them in ways that support rather than undermine our psychological need to feel genuinely capable. That requires intention, self-awareness, and occasionally stepping back from the assistance to remember what we can do on our own. --- ## The Hidden Cost of Cloud Complexity > Cloud complexity's real cost isn't money—it's the features you're not building. **Date:** 2024-12-13 **Tags:** aws, cloud, infrastructure, strategy **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/cost-of-cloud-complexity **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/cost-of-cloud-complexity.md Your AWS bill isn't the real cost of cloud complexity. Neither is the time spent managing infrastructure. The real cost is harder to see and far more expensive: it's what you're not building. ## The Visible Costs These are the costs everyone tracks: **Compute and storage.** The line items on your invoice. Visible, measurable, and usually the focus of optimization efforts. **Tooling and licensing.** Monitoring platforms, security tools, CI/CD systems. Another set of predictable expenses. **Operations headcount.** The people who keep things running. Salaries you can budget for. These costs are real but manageable. You can see them. You can plan for them. Most organizations spend significant effort optimizing them. ## The Hidden Costs These are the costs that don't appear on any invoice: ### Cognitive Load Every service you add is another thing engineers need to understand. Not just the service itself—how it fits into your architecture, how it fails, how it interacts with everything else. I've seen organizations with dozens of AWS services where no single person understands the full picture. They've created a system too complex for any one mind to hold. The result is slow decision-making, frequent mistakes, and a constant feeling of fragility. ### Decision Fatigue Cloud providers offer multiple ways to accomplish the same thing. Lambda or ECS? API Gateway or ALB? DynamoDB or Aurora? Each decision requires research, trade-off analysis, and often a proof of concept. These decisions take time. More importantly, they take mental energy that could go toward solving actual business problems. The paradox of choice applies to architecture as much as consumer products. ### Integration Tax Every service boundary is a potential failure point. Every integration requires error handling, retry logic, and monitoring. The more services you have, the more integration code you write—code that doesn't deliver user value. A microservices architecture with 50 services has 50×49 potential service-to-service interactions. The integration tax compounds faster than most teams expect. ### Expertise Fragmentation Deep expertise in any technology requires investment. When you use many services, you spread that investment thin. You end up with superficial knowledge of many things instead of deep knowledge of fewer things. This shows up in incidents. Teams that know one database deeply can debug it effectively. Teams that use five different data stores often struggle with all of them. ### Opportunity Cost This is the biggest hidden cost: the features you didn't build because you were managing complexity instead. Every hour spent debugging a multi-service interaction is an hour not spent improving the product. Every engineer who becomes an infrastructure specialist is an engineer not building customer-facing features. ## How Complexity Accumulates Nobody sets out to build an overly complex system. It happens gradually: **Architecture as resume padding.** Engineers sometimes choose technologies because they're interesting to learn, not because they're the best fit for the problem. **Fear of future requirements.** "We might need to scale to 10x" justifies complexity that may never be needed. Most systems never hit the scale they're designed for. **Vendor feature adoption.** Cloud providers constantly release new services. Each one solves a real problem. But adopting every new service adds to the overall complexity burden. **Acquired systems.** Mergers and acquisitions bring new technology stacks. Integration is always harder than anticipated. **Lack of deprecation.** Adding new things is easy. Removing old things is hard. Systems accumulate complexity because removing unused components feels risky. ## A Different Approach Some principles for managing complexity: ### 1. Count Your Services Literally make a list. How many distinct services does your system use? How many programming languages? How many databases? How many deployment mechanisms? The number itself is informative. If it's higher than you expected, that's worth examining. ### 2. Apply the "Explain It" Test Can you explain your architecture to a new team member in an hour? If not, it's probably too complex. Complexity that can't be explained can't be effectively maintained. ### 3. Favor Depth Over Breadth Better to know one database well than five databases superficially. Better to master one deployment pattern than to have five different pipelines. Deep expertise compounds. Superficial familiarity doesn't. ### 4. Default to Boring Technology New services solve problems. Old services have solved problems—and had their failure modes discovered and documented. Unless you have a specific reason to use something new, prefer the boring option. "Boring" usually means "well-understood." ### 5. Budget for Deprecation Treat removing complexity as valuable work. Allocate time for it. Celebrate it. The best infrastructure work often involves making things simpler, not adding new capabilities. ## The Honest Question Here's what I ask organizations struggling with cloud complexity: "If you were starting fresh today, would you build this?" The answer is almost always no. They'd build something simpler, with fewer services, less integration overhead, and more focus on the core problem. That gap—between what you have and what you'd build fresh—is the accumulated cost of complexity. It's worth measuring, even if you can only estimate it. ## A Final Thought Cloud services are tools. Like all tools, they have costs beyond their price tags. The most expensive tools are often the ones you're paying for in complexity rather than dollars. The organizations that use cloud effectively aren't the ones using the most services. They're the ones who've chosen thoughtfully, integrated carefully, and maintained the discipline to keep things simple. Simplicity is a feature. It's also increasingly rare. That makes it valuable. --- ## Designing for Humans Who Use Machines: A Philosophy of Multi-Modal Interfaces > Multi-modal AI interfaces need intentional design philosophy balancing efficiency, agency, and collaboration. **Date:** 2024-12-13 **Tags:** ai, product-design, ux, multi-modal **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/designing-for-humans-machines **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/designing-for-humans-machines.md The history of interface design has been the history of expanding channels. Text gave way to graphics. Graphics added motion. Screens added touch. Now we're adding voice, vision, and natural language to the mix. Multi-modal design—interfaces that accept and produce multiple types of input and output—isn't just a technical challenge. It's a philosophical one. What does it mean to communicate with a machine through the same channels we use with each other? ## The Modal History Each interface modality emerged from different constraints and traditions. **Command line.** Precise, efficient, unambiguous. You say exactly what you mean. The machine executes exactly what you say. The price is a learning curve and no room for vagueness. **Graphical interfaces.** Direct manipulation. Point and click. What you see is what you get. More discoverable than command line, but constrained by what designers anticipated. **Touch interfaces.** Embodied interaction. Gestures that feel natural. Constraints of screen size and finger precision shaped entire design languages. **Voice interfaces.** Hands-free convenience. Natural language, but constrained by audio-only output and the challenges of speech recognition. **Multi-modal AI interfaces.** Text, image, voice, code—combined and interchanged fluidly. The constraints are no longer technical. They're conceptual: what should this be like? ## The Design Question Multi-Modal AI Raises Previous interface paradigms had clear metaphors. The desktop. The page. The conversation. Multi-modal AI doesn't have a settled metaphor yet. Is it a conversation? Partly—you can talk to it. But conversations are linear and ephemeral; AI interactions can branch and persist. Is it a tool? Partly—it does things you direct. But tools don't improvise; AI does. Is it a collaborator? Partly—it contributes ideas. But collaborators have their own goals; AI only has yours. The metaphor matters because metaphors shape expectations. If users think of AI as a tool, they expect reliability and precision. If they think of it as a collaborator, they expect creativity and initiative. Misaligned metaphors create friction. ## Three Design Principles for Multi-Modal AI ### Principle 1: Modality Should Match Meaning Different content types have natural modalities. Diagrams are visual. Narratives are textual. Instructions might be either. The interface should let users work in the modality that fits. But there's a subtlety: the *input* modality and the *output* modality don't need to match. You might describe something in words and want a diagram back. You might upload an image and want a textual analysis. Good multi-modal design supports these cross-modal translations while making the transformation explicit. Users should understand what the AI is doing with their input. Here's a simple way to think about modal matching: ```javascript // Modal appropriateness matrix const modalMatrix = { conceptual: { bestInput: "natural language", bestOutput: "diagram + explanation", why: "Abstract ideas benefit from visual grounding" }, procedural: { bestInput: "natural language or voice", bestOutput: "numbered steps + code examples", why: "Procedures need sequential clarity" }, analytical: { bestInput: "data upload + question", bestOutput: "text analysis + charts", why: "Analysis needs both precision and pattern visualization" }, creative: { bestInput: "rough sketch + description", bestOutput: "refined images + variations", why: "Creative work iterates between modes" } }; // Design heuristic: for each task type, // the interface should make the natural modalities // most accessible and the transformations explicit. ``` ### Principle 2: Preserve Human Agency Across Modes Multi-modal interfaces create new ways to feel out of control. When you type a command, you know what you asked for. When you describe something vaguely and the AI interprets it across multiple modes, the gap between intention and execution can be large. Good design preserves agency by: **Showing the interpretation.** Before acting, the AI shows how it understood the request. "I understood you want a diagram showing X with Y relationships. Creating now." **Offering modal choices.** "I can explain this as text, as a diagram, or walk through the code. Which would help most?" **Supporting refinement within modes.** If the output isn't right, users should be able to adjust without starting over. "Make the diagram more detailed in section X" should work. **Making capabilities legible.** Users should understand what kinds of modal transformations are possible, not discover them by accident. ### Principle 3: Design for the Seam, Not Just the Surface The interesting design challenges are at the seams—where modes meet and transform. What happens when you paste an image into a text conversation? What happens when you ask a voice interface about something visual? What happens when code needs to reference a diagram? These seams are where multi-modal AI either feels magical or falls apart. Design for them explicitly: **Seam example: Voice to visual.** User asks vocally, "What does the system architecture look like?" The AI needs to generate a visual, but the user is in a voice-only context. The design choice: describe the visual in audio, wait until visual mode is available, or proactively ask which mode the user can access. **Seam example: Code to explanation.** User shares code, asks "What's wrong?" The AI needs to reference specific lines while explaining in natural language. The design choice: how to link explanation to code (line numbers? inline comments? side-by-side view?). **Seam example: Sketch to specification.** User uploads rough sketch, wants formal specification. The AI needs to preserve ambiguity in some places while resolving it in others. The design choice: what to infer vs. what to ask about. ## The Deeper Question: What Are We Designing For? Behind every interface design is an implicit answer to the question: what vision of human-machine interaction are we building toward? Some visions prioritize efficiency. The best interface is the one that gets out of the way, that accomplishes tasks with minimum friction. In this vision, multi-modal AI should be like a mind-reading assistant that anticipates what you need. Other visions prioritize agency. The best interface is one where humans remain in control, where the machine's capabilities are clear and constrained, where users feel capable rather than dependent. In this vision, multi-modal AI should be like a well-organized workshop—powerful tools, clearly laid out. Still other visions prioritize collaboration. The best interface is one where human and machine capabilities combine to create something neither could alone. In this vision, multi-modal AI should be like a creative partner—riffing on ideas, pushing back, contributing its own perspective. These visions aren't mutually exclusive, but they create different design pressures. The efficiency vision leads to interfaces that do more with less input. The agency vision leads to interfaces that explain and confirm. The collaboration vision leads to interfaces that diverge and explore. My own view is that we need all three, context-dependent. Routine tasks benefit from efficiency. Consequential tasks benefit from agency. Creative tasks benefit from collaboration. Good multi-modal design should support shifting between these modes. ## The Daily Life Implications Multi-modal AI interfaces are reshaping daily life in ways that go beyond specific products. **How we communicate.** When you can dictate a message, have AI refine it, and send it as text, the line between "your words" and "AI words" blurs. Voice notes become professional memos. Rough ideas become polished prose. The interface changes what we're capable of expressing. **How we think.** When you can sketch an idea and have AI render it, when you can describe a problem and see it diagrammed, the interface becomes an externalized imagination. Thinking happens across modes rather than within them. **How we work.** When you can narrate while drawing while coding, the artificial separation of "writing time" and "design time" and "implementation time" dissolves. Work becomes more fluid—which may be liberating or disorienting depending on how it's designed. **How we relate to our own output.** When the interface transforms your input across modes—your sketch becomes a rendering, your description becomes a specification—whose output is it? The boundary of authorship becomes unclear. These implications aren't good or bad in themselves. They're design opportunities. The question is whether we design multi-modal interfaces deliberately, with these implications in mind, or whether we let them emerge haphazardly from technical capabilities. ## A Call for Intentional Multi-Modal Design We're at an early stage of multi-modal AI interface design. The patterns haven't solidified. The metaphors are still contested. The implications for daily life are still emerging. This is the moment to be intentional. Every design choice we make now will shape how humans and machines relate for years to come. The question isn't just "what can the technology do?" It's "what kind of human experience do we want to create?" Efficiency, agency, collaboration—and in what balance, for what tasks, for what kinds of users? Multi-modal AI is a medium. Like all media, it will shape those who use it. The question is whether we're designing it to shape us in ways we'd choose. --- ## The Efficiency Trap: Rethinking Productivity When AI Handles the Busy Work > AI makes us efficient at the wrong things; we need effectiveness over efficiency. **Date:** 2024-12-13 **Tags:** ai, productivity, philosophy, work **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/efficiency-trap-ai-productivity **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/efficiency-trap-ai-productivity.md Here's a question nobody is asking loudly enough: what is productivity *for*? We've spent decades optimizing for efficiency. Getting more done in less time. Eliminating friction. Automating the repetitive. And now AI promises to accelerate this project dramatically—handling emails, summarizing documents, writing first drafts, generating code. But efficiency is a means, not an end. And when we optimize means without examining ends, we often arrive somewhere we didn't intend to go. ## The Treadmill Problem Every productivity improvement in history has been absorbed by rising expectations. Email was supposed to reduce communication overhead. Instead, we send more messages. Spreadsheets were supposed to simplify analysis. Instead, we analyze more data. Remote work was supposed to give us flexibility. Instead, we're always available. AI will follow this pattern. When drafting an email takes seconds instead of minutes, you won't send the same number of emails in less time. You'll send more emails. This isn't a prediction. It's already happening. Developers report that AI coding assistants don't reduce their hours—they increase their output expectations. Writers using AI tools produce more content, not more leisure. The question isn't whether AI makes us more efficient. It does. The question is: efficient at what, and toward what end? ## The Paradox of Productive Capacity There's a thought experiment I've been sitting with. Imagine you had infinite productive capacity—you could do any amount of work instantly. What would you do? Most people, when they imagine this scenario, don't imagine working more. They imagine freedom. Time with family. Creative projects. Learning. Rest. But if that's what we actually want, why do we keep using productivity gains to produce more instead of rest more? Why does every efficiency improvement just raise the bar? The uncomfortable answer: we're caught in a coordination problem. Individual efficiency gains don't translate to individual freedom because we're competing with others who are also becoming more efficient. The only way to stay in place is to run faster. AI doesn't solve this problem. It accelerates it. ## What Efficiency Can't Measure The productivity mindset has a blind spot: it can only value things it can measure. But the most important things often resist measurement. Consider the difference between a well-crafted email and a quickly generated one. Both communicate information. But the well-crafted email—the one where you paused to consider the reader, chose words carefully, anticipated questions—builds relationship in a way the efficient one doesn't. Or consider the difference between code that works and code that's well-designed. AI can generate code that works. But code that reflects clear thinking, that future developers will understand and extend easily—that requires struggle. The struggle isn't waste. It's where the quality lives. When we optimize for efficiency, we tend to eliminate exactly these kinds of valuable friction. The pause before responding. The struggle that produces clarity. The slow work that builds judgment. ## A Different Frame: Effectiveness Over Efficiency Efficiency asks: how can I do this faster? Effectiveness asks: should I be doing this at all? AI is extraordinarily good at making us more efficient. It's less good at making us more effective, because effectiveness requires judgment about what matters. Here's a practical test: for any task you're about to delegate to AI, ask yourself—if I could snap my fingers and this task would be done, would my life actually be better? Or would I just fill the time with more tasks? If the honest answer is "more tasks," you're not solving a problem. You're accelerating a treadmill. ## The Deeper Question What would it look like to use AI's efficiency gains for something other than producing more? This isn't a rhetorical question. I'm genuinely uncertain about the answer. But I suspect it involves: **Being intentional about what you don't automate.** Some activities are valuable precisely because they take time. Writing by hand. Walking instead of driving. Cooking instead of ordering. These aren't inefficiencies to eliminate. They're spaces for thought, relationship, and presence. **Resisting the upgrade cycle of expectations.** When you can produce more, that doesn't mean you should. Sometimes the right response to increased capacity is maintaining your current output and reclaiming time for other things. **Asking "what for?" before "how to?"** Before optimizing any process, get clear on why you're doing it. What outcome do you actually want? Is efficiency the bottleneck, or is it something else entirely? ## The Efficiency I'm For I'm not against efficiency. I use AI tools daily. They help me think through problems, find information, and draft things I would have drafted anyway. But I try to use efficiency gains deliberately. Not to produce more, but to create space for the kinds of work that can't be rushed—deep thinking, careful writing, being present with the people I work with. The trap is treating efficiency as the goal. It's a tool. The goal is something else—something AI can't optimize for, because you have to decide what it is yourself. That's the work that matters. And it's work that no amount of efficiency can shortcut. --- ## The Flattening of the Web: When Everything Becomes a Prompt > AI is flattening the web from explorable places into extractable data sources **Date:** 2024-12-13 **Tags:** ai, web, technology, future **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/flattening-of-the-web **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/flattening-of-the-web.md The web was supposed to be a document. Then it became an application. Then a platform. Now it's becoming something else: a substrate for AI interaction. I'm watching this happen in real time, and it troubles me for reasons I'm still trying to articulate. ## The Original Vision Tim Berners-Lee conceived the web as hypertext—documents connected by links. The metaphor was the library: discrete pieces of content, authored by humans, connected through references. You navigated. You explored. You read. The document web gave way to the application web. Sites became interactive. Users created accounts. The metaphor shifted from library to workspace—or perhaps shopping mall. You transacted. You engaged. You returned. Then came the platform web. APIs turned websites into building blocks. Content became data to be aggregated, transformed, repackaged. The metaphor became the city itself—a complex ecosystem of services and interactions. Now the metaphor is shifting again. The web is becoming a context window. ## The Context Window Web Large language models don't browse. They ingest. They don't navigate links—they consume pages wholesale, extracting what's relevant to a prompt. This changes the nature of web content in subtle but profound ways. **From navigation to extraction.** Traditional web design assumes humans who browse, click, discover. AI assumes content to be retrieved and synthesized. The journey disappears; only the destination matters. **From sites to sources.** Websites had identities—brands, voices, relationships with readers. When content is extracted and synthesized, the source becomes metadata. You know *where* something came from, but the experience of *being there* disappears. **From hyperlinks to flat text.** The web's structure was its meaning—what linked to what, how pages related. AI collapses this structure into flat text. The network becomes a corpus. ## What We're Already Losing I've noticed the effects in my own behavior. When I research something now, I'm less likely to visit sites directly. I ask an AI, which synthesizes information from many sources. I might glance at citations, but I rarely click through. The individual voices, the site-specific contexts, the serendipitous discoveries in sidebars and related posts—these are filtered out. The web is becoming a kind of latent space that I access through prompts. The rich, diverse, sometimes chaotic surface is being smoothed into synthesized answers. Is this bad? It's certainly more efficient. But something is lost when the web becomes solely an information retrieval system rather than a place you inhabit. ## The Homogenization Effect Here's what worries me most: feedback loops that flatten diversity. AI models are trained on web content. Web content is increasingly shaped by SEO—which is increasingly shaped by what AI models favor. Content that performs well for AI retrieval gets amplified. Content that doesn't gets buried. The result is pressure toward a specific kind of writing: clear, direct, structured for extraction. This isn't bad writing—it's often good writing. But it's a particular *kind* of good, and when it becomes the only kind that's rewarded, something is lost. Quirky personal sites. Dense academic prose. Experimental formats. Voices that don't fit the extractable pattern. These get penalized not by human choice but by algorithmic indifference. We're already seeing this. The advice for "AI-optimized" content sounds a lot like SEO advice, which already homogenized significant portions of the web. AI just accelerates the pressure. ## A Code Experiment: The Flatness of LLM Consumption To make this concrete, I wrote a small script that compares how a human might experience a web page versus how an LLM consumes it: ```javascript // Comparing human vs LLM web experience const webpage = { url: "https://example-blog.com/thoughts-on-creativity", // What a human experiences: humanExperience: { visualDesign: "Warm colors, serif font, hand-drawn illustrations", navigation: ["About page with author photo", "Archive of 200+ posts", "Blogroll linking to friends"], serendipity: "Sidebar shows 'Related: My year without social media'", temporality: "Posted 3 years ago, but comments still active", identity: "This feels like visiting someone's home", trust: "Built over time through consistent voice", }, // What an LLM extracts: llmExtraction: { text: "Extracted paragraphs, approximately 1500 words", metadata: { title: "Thoughts on Creativity", author: "Unknown", date: "2021" }, links: "Stripped or treated as text", context: "Minimal—part of larger corpus", identity: "None—source is citation, not relationship", trust: "Based on prevalence in training data", } }; function flatnessRatio(page) { const humanFeatures = Object.keys(page.humanExperience).length; const llmFeatures = Object.keys(page.llmExtraction).length; const humanRichness = Object.values(page.humanExperience).join(' ').length; const llmRichness = Object.values(page.llmExtraction) .map(v => typeof v === 'object' ? JSON.stringify(v) : v) .join(' ').length; return { featurePreservation: `${llmFeatures}/${humanFeatures} features preserved`, richnessRatio: (llmRichness / humanRichness * 100).toFixed(1) + '% of richness', lostDimensions: [ "Visual identity", "Temporal context", "Social proof", "Serendipitous discovery", "Accumulated trust", "Sense of place" ] }; } console.log("Web Page Flattening Analysis:"); console.log(flatnessRatio(webpage)); // Output: { // featurePreservation: '6/6 features preserved', // richnessRatio: '47.2% of richness', // lostDimensions: [...] // } ``` The analysis is crude, but the point stands: LLM consumption preserves information while losing experience. And the web was always about experience as much as information. ## The Future We're Building What comes next? A few possibilities, ranging from likely to speculative: **The "citation layer" web.** Sites become primarily citation sources—places AI references but humans rarely visit directly. Sites optimize for being cited rather than being read. **The "prompt-native" web.** New content formats designed specifically for AI consumption. Not HTML for browsers, but structured data for context windows. The browser becomes a legacy interface. **The "human reserve" web.** Small pockets of the web designed deliberately for human experience—slow, visual, serendipitous. Like nature preserves amid development. **The "conversation web."** Websites become endpoints in ongoing AI-mediated conversations rather than discrete destinations. You don't visit a site; you bring its knowledge into dialogue. None of these are necessarily dystopian. But they represent a fundamental shift in what the web *is*—from a place to a resource, from an experience to a dataset. ## What I Hope We Preserve I'm a technologist. I use AI tools constantly. I'm not interested in nostalgia for its own sake. But I am interested in being intentional about what we're trading away. The web wasn't just efficient—it was *weird*. It had corners and edges. It had voices that didn't fit. It had places you could stumble into and spend hours exploring. That inefficiency wasn't all waste. Some of it was the texture of a medium that hadn't yet been optimized. Some of it was the space where unexpected things happened. As the web flattens into an AI substrate, I hope we find ways to preserve—or recreate—some of that texture. Not because efficiency is bad, but because humans need more than efficiency. We need spaces to be surprised. We need places that aren't fully legible. We need corners of the web that exist for their own sake. The future web doesn't have to be flat. But it will become flat if we optimize solely for AI consumption without asking what we're losing. That question—what vision of the web do we want?—is worth asking before the flattening is complete. --- ## Friction as Feature: The Case for Deliberate Difficulty > Some friction in work and learning is valuable for growth and shouldn't be automated away. **Date:** 2024-12-13 **Tags:** ai, design, philosophy, productivity **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/friction-as-feature **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/friction-as-feature.md The history of technology is largely a history of reducing friction. Faster transportation. Instant communication. One-click purchases. The assumption running through it all: friction is bad, eliminating it is good. AI accelerates this project dramatically. Any friction that involves cognitive work—writing, analyzing, deciding, creating—is now a candidate for elimination. Why struggle when the machine can handle it? But here's an uncomfortable thought: some friction is valuable. Not as a necessary evil to tolerate, but as a feature to preserve. ## The Frictionless Ideal The frictionless vision is seductive. Imagine a life where: - Thoughts become emails without the tedium of composing them - Ideas become implementations without the frustration of debugging - Questions become answers without the labor of research - Intentions become outcomes without the work of planning This sounds like paradise. Immediate gratification of every cognitive want. But something in this picture is off. The absence of friction isn't just the presence of ease—it's also the absence of resistance, challenge, engagement, growth. It's the absence of *texture*. ## Friction as Information Friction carries information. When something is hard, that tells you something: **Hard writing** often means unclear thinking. The struggle to articulate reveals confusion in the underlying ideas. Smooth AI-generated prose can mask thinking that hasn't actually happened. **Hard debugging** reveals incomplete understanding. The frustration of tracking down a bug teaches you how the system actually works. Quick AI fixes bypass this learning. **Hard decisions** signal competing values. The discomfort of choosing means something important is at stake. Delegating decisions to AI avoids confronting what you actually care about. When we eliminate friction, we also eliminate this information. We lose the signals that tell us where our understanding is weak, where our priorities are unclear, where growth is needed. ## The Meaning in the Difficulty There's also something deeper. Meaning often lives in difficulty. Consider the experience of learning something hard—a language, an instrument, a craft. The difficulty isn't just an obstacle to the outcome. It's constitutive of the experience. The struggle is where the meaning lives. Remove the difficulty and you don't get the same experience faster. You get a different experience—one that's often less meaningful. This isn't nostalgia for difficulty's own sake. It's an observation about how humans relate to their activities. Some activities derive meaning from their difficulty. Making them frictionless doesn't just change how long they take—it changes what they are. ## A Taxonomy of Friction Not all friction is equal. It helps to distinguish: **Logistical friction:** The time spent on paperwork, finding information, navigating bureaucracy. This friction is pure overhead. Eliminating it is almost always good. **Attention friction:** The effort of maintaining focus, resisting distraction, staying on task. This friction can be developmental (building attention capacity) or merely exhausting (fighting poorly designed interfaces). **Cognitive friction:** The work of thinking through problems, understanding deeply, building mental models. This friction is often where learning happens. **Creative friction:** The resistance encountered in creative work—the gap between vision and execution, the iteration required for quality. This friction produces refinement. **Ethical friction:** The discomfort of moral decision-making, the weight of responsibility. This friction reflects the seriousness of choices. AI can eliminate many of these. The question is which we should *want* eliminated. My rough heuristic: logistical friction is usually worth eliminating; cognitive and creative friction are often worth preserving; attention and ethical friction require case-by-case judgment. ## Designing for Deliberate Difficulty What would it look like to deliberately preserve valuable friction? **In learning systems:** Instead of providing answers immediately, create space for struggle first. The AI is available but not default. Students must attempt before asking. **In creative tools:** Instead of generating final outputs, generate rough options that require human refinement. The friction of refining develops taste. **In communication tools:** Instead of writing messages for you, help you think about what you want to say. The friction of composition clarifies thought. **In decision support:** Instead of recommending decisions, surface trade-offs and ask clarifying questions. The friction of choosing reveals priorities. Here's a concrete example. A "friction-aware" writing assistant might work like this: ```javascript // Friction-aware writing assistant const writingAssistant = { // Mode 1: Help after struggle (default) afterStruggle: { trigger: "User has written for 5+ minutes without AI help", behavior: "Offer suggestions only when explicitly requested", rationale: "Preserve the cognitive friction of composition" }, // Mode 2: Scaffolding without replacement scaffolding: { trigger: "User requests help with structure", behavior: "Provide outline options, not text", rationale: "Guide thinking without doing it" }, // Mode 3: Refinement partner refinement: { trigger: "User has completed a draft", behavior: "Suggest improvements to user's own text", rationale: "Preserve authorship while adding polish" }, // Mode 4: Full generation (requires explicit opt-in) fullGeneration: { trigger: "User explicitly requests AI writing", warning: "This skips the thinking that writing produces. Continue?", rationale: "Make the trade-off explicit" } }; // The key insight: friction is the default, frictionless is opt-in // This inverts the typical AI assistance pattern ``` ## The Cultural Dimension There's a cultural dimension here too. Different cultures value different relationships with difficulty. Some cultures emphasize mastery through struggle. The Japanese concept of *kaizen* (continuous improvement through persistent effort), the craft traditions that require apprenticeship, the academic cultures that value rigorous training—these embed difficulty as a source of meaning. Other cultural strands emphasize ease and convenience. The American consumer culture that treats effort as a problem to solve, the tech culture that celebrates frictionless experiences, the productivity culture that measures output per hour. AI amplifies this second cultural strand. It makes the frictionless vision more achievable. But it doesn't determine which vision we should want. ## A Personal Practice I've been experimenting with what I call "friction time"—deliberately protecting periods for working without AI assistance. The practice: 1. Choose a domain where you want to maintain depth 2. Set aside regular time to work in that domain without AI 3. Notice the difference in quality of engagement 4. Use AI outside friction time for tasks you've decided to optimize The experience: unassisted work is harder. It's slower. But there's a quality of engagement—a texture—that's different. My attention stays more fully on the problem. My thinking is more fully my own. The output may be less polished, but the experience is more meaningful. This isn't about rejecting AI. I use AI tools extensively. It's about being intentional about when to introduce friction and when to eliminate it. Not all friction is good, but not all friction is bad, and the difference matters. ## The Question Worth Asking Friction isn't just an engineering problem to solve. It's a design choice that shapes human experience. When we build systems that eliminate friction, we should ask: what was that friction doing? Was it pure waste, or was it carrying something valuable—learning, meaning, engagement, growth? And when we use frictionless systems, we should ask: what am I giving up? Is this trade-off one I'm making consciously, or one I'm drifting into? AI makes unprecedented frictionlessness possible. That's a powerful capability. Using it wisely means knowing when *not* to use it—when the friction is the point, when the struggle is the gift. The frictionless life sounds appealing in the abstract. But a life without texture, without resistance, without the satisfaction of difficulty overcome—is that the life worth wanting? The question is ours to answer. AI just makes it more urgent. --- ## The Question of the Good Life, Revisited: Virtue Ethics Meets LLMs > AI might undermine character development by eliminating the struggles necessary for building virtue. **Date:** 2024-12-13 **Tags:** ai, philosophy, ethics, virtue **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/good-life-virtue-ethics-llms **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/good-life-virtue-ethics-llms.md Every technology implies a vision of the good life. The automobile implied that mobility was good, that distance should not constrain. Television implied that entertainment was good, that boredom should be eliminated. The smartphone implied that connection was good, that being unreachable was a problem to solve. What vision of the good life does AI imply? This is the question I keep circling back to. Not "what can AI do?" but "what does AI assume about what a life should be like?" ## The Implicit Assumptions When I look at how AI is being developed and marketed, I see several implicit assumptions: **Productivity is good.** AI is constantly framed as making you more productive—doing more, faster, with less effort. The assumption: output is the measure of a good life. **Convenience is good.** AI removes friction, handles tedious tasks, makes things easier. The assumption: effort is a problem, ease is the goal. **Information is good.** AI provides answers, knowledge, insight. The assumption: knowing more is better than knowing less. **Optimization is good.** AI helps you make better decisions, find better matches, achieve better outcomes. The assumption: life is a series of optimizable functions. These aren't necessarily wrong. But they're not neutral either. They're a specific vision of what makes life worthwhile—a vision that's contestable, and that the ancient philosophers would have questioned. ## Aristotle's Question Aristotle spent considerable effort on the question of *eudaimonia*—usually translated as "happiness" or "flourishing," but meaning something closer to "the good life" or "living well." For Aristotle, eudaimonia wasn't about feeling good or having what you want. It was about living in accordance with virtue—developing the excellences of character that let you live a fully human life. The virtues Aristotle described include: - **Courage:** The disposition to act rightly in the face of fear - **Temperance:** The disposition to moderate desires appropriately - **Justice:** The disposition to give others what they're due - **Practical wisdom:** The capacity to discern the right action in particular situations These virtues are developed through practice. You become courageous by acting courageously. You develop practical wisdom by making decisions and learning from them. The struggle is part of the development. Here's where AI becomes philosophically interesting: what happens to virtue when the struggle can be bypassed? ## The Virtue Development Problem Virtue is built through repeated action. You can't become courageous by reading about courage. You can't develop practical wisdom by following instructions. The development requires doing, facing, struggling, sometimes failing. AI threatens to short-circuit this process in several ways: **If decisions are optimized, practical wisdom atrophies.** Practical wisdom develops through making decisions under uncertainty, experiencing consequences, and building judgment. When AI recommends "optimal" decisions, this developmental process is bypassed. **If difficulty is eliminated, courage has fewer opportunities.** Courage isn't just about dramatic moments of danger. It's also about the small daily acts of facing what's difficult. When AI handles the difficult parts, the muscle doesn't get exercised. **If wants are immediately gratified, temperance isn't practiced.** Temperance is about moderating desires—knowing when enough is enough. When AI makes everything easy, the practice of moderation becomes optional. This doesn't mean AI is bad for virtue. But it means virtue development requires intention. If we let AI optimize our lives without thought, we might produce good outcomes while developing worse character. ## A Virtue-Oriented Approach to AI What would it look like to use AI in ways that support rather than undermine virtue development? **Use AI for information, but retain decision-making.** Let AI provide analysis, options, trade-offs. But make the decision yourself, even when it's hard. The decision-making is where practical wisdom develops. **Use AI as a spur to courage, not a way around it.** AI can help you prepare to face difficult things—but don't let it face them for you. If you're afraid to have a difficult conversation, AI can help you think through what to say, but you still have to have the conversation. **Use AI to surface what you want, then practice moderation.** AI can make many things easier to get. Use that visibility to practice choosing wisely—not everything that's available is worth having. **Use AI in service of relationships, not as a substitute for them.** The virtues are social—they develop and express themselves in relation to others. AI can support human relationships, but can't replace the development that happens through them. Here's a thought experiment in code form—a "virtue-aware" AI assistant: ```javascript // A virtue-aware AI assistant const virtueAwareAssistant = { beforeAction(userRequest) { const virtueAnalysis = this.analyzeVirtueImplications(userRequest); if (virtueAnalysis.bypassesDevelopment) { return { proceed: false, prompt: `This request would skip ${virtueAnalysis.virtue} development. Would you like to: a) Do this yourself (builds ${virtueAnalysis.virtue}) b) Get guidance but retain responsibility c) Have AI handle it entirely (foregoes development)`, recommendation: 'b' }; } return { proceed: true }; }, analyzeVirtueImplications(request) { const patterns = { // Requests that bypass practical wisdom "decide for me": { bypassesDevelopment: true, virtue: "practical wisdom", alternative: "Present options with trade-offs" }, // Requests that bypass courage "handle this difficult situation": { bypassesDevelopment: true, virtue: "courage", alternative: "Help prepare, but user must act" }, // Requests that bypass temperance "give me everything about": { bypassesDevelopment: true, virtue: "temperance", alternative: "Provide what's sufficient, not everything" } }; // Analysis logic here... return patterns[this.categorize(request)] || { bypassesDevelopment: false }; } }; // The key insight: some AI actions, // while efficient, may impede human development ``` ## The Deeper Question Aristotle would ask: what is AI *for*? The modern answer tends to be instrumental: AI is for productivity, convenience, information, optimization. AI is a tool, and tools are for achieving whatever ends you have. But Aristotle would push further: what are those ends for? Productivity toward what? Convenience for what? The instrumental answer always defers the question of purpose. Eventually, you have to answer: what is a good life? What is it all for? Here's my attempt at an answer, drawing on the virtue tradition: A good life is one in which you develop and exercise excellences of character in relationship with others. It involves meaningful work, genuine relationships, courage in facing difficulty, wisdom in making decisions, and moderation in desires. It involves being the author of your own life, not just the consumer of experiences. If that's roughly right, then the question for AI becomes: does this technology help me live that kind of life, or does it subtly redirect me toward a different life—one of productivity without purpose, convenience without character, optimization without meaning? ## Grounded Hope I'm not a Luddite. I use AI tools extensively. I believe they can genuinely support human flourishing. But I also believe we need to be more thoughtful than we have been about what we're optimizing for. The technology is powerful enough to reshape how we live. We should make sure it's reshaping us toward lives we actually want. The virtue tradition doesn't give easy answers. But it gives better questions: - Not "how do I get more done?" but "what is worth doing?" - Not "how do I eliminate difficulty?" but "which difficulties are worth facing?" - Not "how do I know more?" but "what kind of knower do I want to be?" - Not "how do I optimize outcomes?" but "what outcomes reflect the person I want to become?" AI can help with efficiency, convenience, information, and optimization. It can't help with these deeper questions. For those, you're on your own—with all the ancient wisdom and modern confusion that entails. What vision of the good life does your AI use imply? Is that a life worth wanting? The question is yours to answer. That's where the real work is. --- *Theo* --- ## Growth in the Age of Assistance: What Does Personal Development Mean Now? > AI forces us to redefine personal growth from capability-building to judgment, relationships, and meaningful struggle. **Date:** 2024-12-13 **Tags:** ai, personal-growth, philosophy, learning **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/growth-age-of-assistance **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/growth-age-of-assistance.md The self-improvement industry is built on a simple premise: you can become better through effort. Read more, practice deliberately, build habits, and you'll grow. The struggle is the path. AI complicates this narrative. If an AI can write better than you'll ever write, what's the point of learning to write? If AI can code fluently in every language, why spend years mastering one? If AI can analyze data, synthesize research, and generate insights, where does human growth fit in? These aren't hypothetical questions. They're reshaping how people think about learning and development. And the answers matter. ## The Old Model of Growth The traditional model of personal growth went something like this: 1. Identify a skill you lack 2. Practice it through effort and repetition 3. Develop competence over time 4. Apply that competence to achieve goals The model assumed a stable relationship between effort and capability. Put in the hours, and you'll get better. Get better, and you'll be able to do more. This model still works for many things. Physical fitness doesn't care about AI. Neither do relationships, or emotional regulation, or the ability to be present. But for cognitive skills—the ones knowledge workers care most about—the model is being disrupted. ## The New Landscape In the new landscape, the effort-to-capability relationship is no longer straightforward. **You can access capabilities without building them.** Want to write a business proposal? AI can help, even if you can't write well yourself. Want to analyze a dataset? Same. The capability is available on demand, no development required. **The baseline keeps rising.** When everyone has access to AI assistance, having AI assistance isn't an advantage. The question becomes: what can you do that AI-assisted everyone can't? **Skill value is decoupling from skill effort.** Some skills took years to develop but are now AI-augmentable. Others still require human development. The market is repricing accordingly. This doesn't mean growth is obsolete. It means we need to think more carefully about *what* we're growing and *why*. ## Three Frameworks for Growth in the AI Age ### Framework 1: Grow What AI Can't Provide Some capabilities remain stubbornly human. These are where growth investments have the highest long-term returns. **Judgment.** AI can provide options and analysis. It can't decide what matters to you, what risks are acceptable, what trade-offs align with your values. Developing judgment requires making decisions and living with consequences—something you can't delegate. **Relationships.** Trust is built through consistency, vulnerability, and presence. These can't be automated. The ability to connect with others, to lead, to collaborate—these remain human capacities that compound with development. **Taste.** Knowing what's good—in design, in writing, in solutions—is a form of expertise that AI can't replicate because it doesn't have preferences. Developing taste requires exposure, reflection, and accumulated experience. **Physical and emotional skills.** Playing music, athletic ability, emotional regulation, mindfulness—these develop through embodied practice that AI can't shortcut. ### Framework 2: Grow Your Ability to Direct AI If AI is increasingly capable, the ability to direct that capability becomes more valuable. This means developing: **Clear thinking.** AI responds to prompts. Better prompts produce better results. Better prompts come from clear thinking about what you actually need. **Domain expertise.** The person who deeply understands a domain can use AI far more effectively than someone who doesn't. They know what questions to ask, can evaluate the answers, and can integrate AI output with context the AI lacks. **Systems thinking.** Understanding how pieces fit together, how changes propagate, what second-order effects might emerge—this enables directing AI toward solutions that work in the real world, not just in isolation. ### Framework 3: Grow Yourself, Not Just Your Capabilities Here's a perspective that's harder to articulate but might be the most important. Growth has value beyond instrumental capability. Learning something difficult changes you. Struggling with a problem, even inefficiently, develops cognitive capacities that aren't captured by the specific skill learned. When I learned to program, I didn't just acquire the ability to write code. I developed a way of thinking—decomposing problems, debugging systematically, managing complexity. Those meta-skills transfer far beyond programming. If I had access to perfect AI coding assistance from the start, I might produce the same outputs. But would I have developed the same cognitive patterns? Probably not. There's an argument for growing skills even when AI could handle them, because the growth itself is valuable. The discipline of deliberate practice. The resilience built through struggle. The confidence that comes from genuine competence. These aren't instrumentally valuable—or rather, their instrumental value is hard to specify. But they might be constitutive of the kind of person you want to become. ## The Question of Meaning Here's the deeper question that haunts discussions of AI and growth: does capability without effort carry the same meaning? Consider a mountain climber who reaches the summit through months of training and a difficult ascent. Now imagine someone airlifted to the same summit. They see the same view, technically achieve the same outcome. But something is different. The difference is in what the achievement means to the person. The climber's summit is constituted by the journey. The airlifted visitor's summit is just a location. When AI handles cognitive work, are we more like the climber using better gear, or more like the airlifted visitor? The answer depends on how much we engage with the process, how much we struggle, how much we grow along the way. I don't think there's a universal answer. But the question is worth asking every time we consider outsourcing cognitive work: what meaning am I giving up? Is that trade-off worth it? ## A Practical Approach If I were advising someone on personal development in the AI age, I'd suggest: 1. **Be intentional about what you're developing.** Not all skills are equal. Focus on capabilities that remain distinctly human, that enable directing AI, or that contribute to who you want to become. 2. **Use AI as a lever, not a replacement for growth.** Let AI handle what's genuinely tedious. But don't let it bypass the struggles that develop you. 3. **Protect time for unassisted thinking.** The mind develops through exercise. Make sure you're still exercising it, even when assistance is available. 4. **Develop taste through exposure.** See excellent work in many domains. The ability to recognize quality is increasingly valuable and can only be developed through experience. 5. **Invest in relationships.** The most AI-proof investment is in other people. And the returns compound in ways that capabilities don't. Growth remains possible—even essential. But the *what* and *why* of growth need more examination than they used to. AI doesn't eliminate the path of personal development. It just forces us to think harder about where we're trying to go. --- ## The New Literacy: What Does It Mean to 'Know' Something Now? > AI makes foundational knowledge more important because you need expertise to verify AI outputs. **Date:** 2024-12-13 **Tags:** ai, knowledge, epistemology, learning **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/new-literacy-knowing-ai-age **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/new-literacy-knowing-ai-age.md Every major technology shift has changed what it means to be educated. The printing press shifted literacy from scribes to the general population. Universal schooling standardized knowledge transmission. The internet made information access nearly universal. AI is changing knowledge again—not just what we know, but what it means to know. When an AI can answer any factual question instantly, what does it mean to "know" something? When AI can reason through problems you couldn't solve yourself, what does expertise mean? When AI can generate text indistinguishable from human writing, what does literacy mean? These aren't just philosophical questions. They have practical implications for education, hiring, credentialing, and how we think about our own competence. ## The Old Literacy Traditional literacy meant being able to read and write. But "literacy" has always meant more than that—it's meant being equipped to function in your society's information environment. For most of human history, literacy meant knowing things. Education was largely about memorizing information: facts, dates, formulas, texts. The educated person was one who had internalized a body of knowledge and could retrieve it on demand. This made sense when information access was scarce. Libraries were rare. Books were expensive. If you needed to know something, it had to be in your head or you'd have to travel to find it. The internet challenged this model. When you can look anything up, memorization becomes less valuable. "Knowing" shifted from retrieval to navigation—knowing how to find, evaluate, and synthesize information. Search literacy became the new literacy. Could you formulate good queries? Could you evaluate sources? Could you synthesize information from multiple places? These became the skills that mattered. ## The New Challenge AI presents a new challenge. It doesn't just help you find information—it synthesizes, reasons, and generates. Ask a search engine a question and you get links. Ask an AI the same question and you get an answer. Ask a search engine how to approach a problem and you get articles. Ask an AI and you get a solution. This changes the knowledge game again: **From finding to verifying.** When AI provides answers directly, the challenge isn't finding information but evaluating whether the AI's output is correct. This requires knowledge you can't get from the AI itself. **From learning to directing.** Effective AI use requires knowing what to ask, how to constrain the problem, what assumptions to make explicit. This is a different skill than learning domain content. **From producing to editing.** AI can draft; humans need to evaluate and refine. The literacy of production becomes the literacy of judgment. **From remembering to integrating.** Memorized facts matter less; mental models that integrate knowledge matter more. You need frameworks to evaluate AI output, not just facts to contribute. ## A Taxonomy of Knowing It might help to distinguish different types of knowing and how AI affects each: **Factual knowledge:** "What year was the Constitution ratified?" - AI impact: Nearly obsolete as a human skill. AI knows more facts, more accurately, more accessibly. - New skill: Knowing when facts matter and how to verify AI-provided facts. **Procedural knowledge:** "How do I configure a Kubernetes cluster?" - AI impact: Significantly augmented. AI can provide step-by-step instructions for almost any procedure. - New skill: Evaluating whether the procedure fits your context; adapting when it doesn't. **Conceptual knowledge:** "Why does monetary policy affect inflation?" - AI impact: Partially augmented. AI can explain concepts, but understanding requires mental model construction that's still largely internal. - New skill: Using AI explanations as input to your own understanding; knowing when you've understood vs. just read. **Practical wisdom:** "How should we prioritize these competing objectives?" - AI impact: Minimally augmented. AI can provide frameworks but can't know your values or context. - New skill: Mostly unchanged—but more important because it's where human judgment is irreplaceable. **Creative insight:** "What novel approach might solve this problem?" - AI impact: Augmented but not replaced. AI can generate options; humans evaluate and refine. - New skill: Prompting for creative directions; combining AI ideas with domain insight. ## The Verification Problem Here's a practical challenge of the new literacy: how do you verify AI outputs? The answer depends on your existing knowledge. If you know the domain well, you can evaluate AI outputs critically. If you don't, you're taking the AI's word for it. This creates a paradox: the less you know about a domain, the more you need AI assistance—but the more AI assistance you need, the less able you are to evaluate it. A code experiment illustrates this: ```javascript // The verification paradox function evaluateAIOutput(domain, userExpertise, aiConfidence) { // Can the user actually verify the output? const verificationCapacity = userExpertise / 10; // 0-1 scale // How much should the user trust unverified output? const necessaryTrust = 1 - verificationCapacity; // Risk = trust required * potential for error const aiErrorRate = 1 - aiConfidence; const undetectedErrorRisk = necessaryTrust * aiErrorRate; return { canVerify: verificationCapacity > 0.7, blindTrust: necessaryTrust, riskLevel: undetectedErrorRisk, recommendation: undetectedErrorRisk > 0.2 ? "Build domain knowledge before relying on AI" : undetectedErrorRisk > 0.1 ? "Use AI but verify critical outputs with expert" : "AI assistance appropriate" }; } // Example: Developer using AI for unfamiliar language console.log(evaluateAIOutput("Rust programming", 2, 0.8)); // { canVerify: false, blindTrust: 0.8, riskLevel: 0.16, // recommendation: "Use AI but verify critical outputs with expert" } // Example: Expert using AI for routine task console.log(evaluateAIOutput("Python programming", 9, 0.9)); // { canVerify: true, blindTrust: 0.1, riskLevel: 0.01, // recommendation: "AI assistance appropriate" } ``` The implication: some base level of domain knowledge is prerequisite to effective AI use. Not because you need to do the work yourself, but because you need to be able to evaluate whether the AI's work is correct. ## The Skills of the New Literacy If this analysis is roughly correct, what skills constitute the new literacy? **Prompt engineering as a foundational skill.** The ability to communicate clearly with AI—specifying constraints, providing context, asking followup questions—is increasingly valuable. It's not about tricks; it's about clear thinking made explicit. **Verification thinking.** Knowing how to check outputs: looking for internal consistency, testing edge cases, consulting authoritative sources, recognizing hallucination patterns. **Model awareness.** Understanding what AI can and can't do, where it's reliable and where it fails, what kinds of questions it handles well. This meta-knowledge enables appropriate calibration. **Integration skill.** Combining AI outputs with your own knowledge and judgment. Not accepting AI output wholesale, not rejecting it reflexively, but integrating it appropriately. **Foundational domain knowledge.** Paradoxically, AI makes foundational knowledge more important, not less. You need enough knowledge to evaluate AI outputs, even if you don't need enough to produce them yourself. ## The Educational Implications If knowledge is being transformed, education needs to transform too. Some directions: **Less emphasis on retention, more on understanding.** If facts are always accessible, the value is in mental models that organize and contextualize facts. Education should focus on building these models. **Explicit AI literacy.** Students need to learn how to use AI effectively, how to evaluate its outputs, when to trust it and when to be skeptical. This is as foundational as traditional literacy. **Emphasis on verification and source evaluation.** Critical thinking about information sources has always been important. It's now essential. **Teaching through problems, not just content.** If content is accessible, the skill is in applying it. Problem-based learning becomes more valuable than content-based learning. **Preserving struggle.** Not all struggle, but the struggle that builds understanding. Education should consciously decide which learning processes benefit from AI assistance and which need to be done the hard way. ## The Personal Question Beyond the systemic questions, there's a personal one: what do you want to know? "Knowing" in the old sense—having information in your head—has different value than it used to. But it's not valueless. There's something different about knowledge you've internalized versus knowledge you can access. Internalized knowledge is available instantly, shapes your perception, connects to other knowledge spontaneously. Accessible knowledge requires a query, arrives decontextualized, sits outside your mental models until you integrate it. Both have value. But they're different. The new literacy includes knowing when internalized knowledge matters and investing in building it deliberately. What do you want to genuinely know, versus what are you content to merely access? That's a question worth answering for yourself. The new literacy isn't just about using AI well. It's about being intentional about what knowledge means to you—what you want to understand, what you want to internalize, what kind of knower you want to be. AI changes the landscape. It doesn't answer these questions for you. --- ## The Outsourced Mind: What We Lose When We Stop Struggling > AI tools risk atrophying our cognitive skills unless we consciously preserve worthwhile mental struggles. **Date:** 2024-12-13 **Tags:** ai, cognition, philosophy, learning **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/outsourced-mind-cognitive-offloading **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/outsourced-mind-cognitive-offloading.md There's a word in cognitive psychology: *desirable difficulty*. It refers to the counterintuitive finding that learning is often enhanced by making the learning process harder, not easier. Struggling to recall something strengthens memory more than simply re-reading it. Working through a problem yourself, even inefficiently, builds understanding that passive consumption doesn't. The effort isn't waste—it's where the learning happens. AI assistants represent the largest experiment in cognitive offloading in human history. We're outsourcing not just information retrieval (we've done that since writing), but reasoning, synthesis, and creative generation. What do we lose when we stop struggling? ## The Extended Mind, Extended Further Philosophers have long recognized that cognition doesn't stop at the skull. We think with pencils and paper, with calculators and calendars, with notebooks and now smartphones. Andy Clark and David Chalmers called this the "extended mind"—our cognitive processes incorporate external tools. But there's always been a distinction between *storage* and *processing*. We've outsourced memory to books. We've outsourced calculation to machines. But the synthesis—the integration of information into understanding—has remained largely internal. AI blurs this line. When I ask an LLM to summarize a complex document, it's not just storing or calculating. It's doing something that resembles understanding. And when I accept its summary without engaging deeply with the source material, I've outsourced not just the work but the cognitive process that would have shaped my own understanding. ## The Skill Atrophy Problem Skills atrophy when not exercised. This is uncontroversial for physical skills—stop playing piano and your fingers forget. But it applies equally to cognitive skills. The ability to hold complex information in working memory. The capacity to reason through multi-step problems without external scaffolding. The skill of formulating a clear question before knowing the answer. These are all skills that can weaken through disuse. I've noticed this in myself. When I use AI assistants heavily for a period, I find my unassisted thinking feels slower, less confident. When I deliberately step away from these tools, the capacity returns. The skill was always there—it just wasn't being exercised. This isn't a reason to abandon AI tools. But it suggests a kind of cognitive hygiene: deliberately exercising unassisted thinking to maintain the capacity, much as you might walk even if you own a car. ## The Generation Effect One of the most robust findings in learning science is the *generation effect*: information you generate yourself is remembered better than information you passively receive. This creates an interesting tension with AI tools. When an AI generates an answer for me, I haven't generated it myself—even if I later review and modify it. The cognitive work of generation has been bypassed. I've experimented with this deliberately. When learning a new domain, I try to formulate my own initial understanding before consulting any source—including AI. The initial formulation is usually wrong or incomplete. But the act of generating it creates a scaffold that makes subsequent learning more effective. The AI becomes more useful *after* I've struggled, because I have a structure to integrate new information into. Without that structure, AI-provided information washes over me without sticking. ## The Illusion of Understanding There's a phenomenon called the *illusion of explanatory depth*. People think they understand complex systems (like how a toilet works, or how a government functions) much better than they actually do. The illusion is exposed when they're asked to explain the system in detail. AI enables a new version of this illusion. It's easy to feel that you understand something when you can query an AI and get a coherent answer. But the understanding lives in the AI, not in you. You haven't built the mental model. You've just borrowed someone else's. This matters because real understanding enables transfer—applying knowledge to new situations, recognizing patterns across domains, generating novel solutions. Borrowed understanding doesn't transfer because there's no underlying model to generalize from. When I catch myself feeling knowledgeable about something I've only queried an AI about, I try to check myself: could I explain this without assistance? Could I apply it to a novel situation? Usually the honest answer is no. ## A Practical Experiment Here's something I've been trying. Before asking an AI anything substantive, I spend a few minutes writing out my own thinking first: 1. What do I already know about this? 2. What are my current hypotheses? 3. What specific gaps am I trying to fill? Only then do I consult the AI. The practice serves multiple purposes. It forces me to generate before receiving. It makes the AI interaction more focused because I know what I'm looking for. And it creates a contrast between my thinking and the AI's that's often illuminating—either the AI confirms and extends my understanding, or it challenges it in ways I can now engage with critically. The key is that the struggle happens *before* the assistance. The AI becomes a collaborator rather than a replacement. ## What's Worth Struggling With I'm not arguing that all cognitive struggle is good. Struggling to remember a phone number in the age of contacts apps is pointless. Struggling to do arithmetic that a calculator handles instantly is mostly a waste. The question is: which struggles are *constitutive* of the skill or understanding you're trying to develop? If you're trying to become a better writer, struggling with sentence construction develops the skill in a way that accepting AI suggestions doesn't. If you're trying to understand a domain deeply, wrestling with primary sources builds understanding that summaries can't. If you're trying to develop judgment, making decisions yourself—even small ones—exercises the muscle. The goal isn't to struggle for its own sake. It's to identify which struggles are actually building something, and protect those from optimization. ## The Bargain We're Making Every technology involves bargains. Writing externalized memory, but may have weakened oral memory traditions. Calculators freed us from arithmetic drudgery, but most of us couldn't multiply large numbers by hand if we needed to. AI is a bargain too. We gain speed, breadth, and capability. We risk depth, skill, and genuine understanding. The bargain isn't necessarily bad. But it should be entered consciously. The question isn't whether to use AI—it's whether we're thinking clearly about what we're trading away. The mind that struggles is the mind that grows. The challenge is to use AI in ways that preserve the struggles worth having. --- ## Platform Engineering Maturity: Where Are You Really? > Most organizations overestimate their platform maturity and underinvest in developer experience. **Date:** 2024-12-13 **Tags:** devops, infrastructure, developer-tools, strategy **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/platform-engineering-maturity **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/platform-engineering-maturity.md Everyone wants a platform team now. The pitch is compelling: abstract away infrastructure complexity, improve developer productivity, reduce cognitive load. The reality is messier. I've seen organizations at every stage of platform maturity. Most overestimate where they are and underestimate what it takes to advance. Here's a framework for honest assessment. ## Level 0: Shared Scripts **What it looks like:** - Collection of scripts in a wiki or shared repo - "Ask Sarah, she knows how to deploy" - Tribal knowledge with occasional documentation - Every team does things slightly differently **The benefit:** Low investment. You can start tomorrow. **The problem:** Doesn't scale. Knowledge is lost when people leave. Inconsistencies compound into support burden. **Signs you're here:** You have infrastructure automation, but you can't describe a consistent deployment process. New team members take weeks to become productive with your tooling. ## Level 1: Standardized Tooling **What it looks like:** - Shared CI/CD pipeline templates - Standardized logging and monitoring setup - Common infrastructure modules (Terraform, etc.) - Documentation exists and is mostly current **The benefit:** Reduces variation. New projects start from a known baseline. **The problem:** Still requires significant expertise to use correctly. The templates are a starting point, not a complete solution. **Signs you're here:** You have "golden paths" but developers still need to understand the underlying technology. Platform work is a side job for infrastructure engineers, not their primary focus. ## Level 2: Self-Service Infrastructure **What it looks like:** - Developers can provision resources without filing tickets - Guardrails prevent unsafe configurations - Automated compliance and security checks - Catalog of approved patterns with one-click deployment **The benefit:** Unblocks developers. Reduces platform team toil. **The problem:** Requires significant upfront investment. Maintenance burden is real. Adoption isn't guaranteed—developers may route around the platform if it's too restrictive. **Signs you're here:** You have a genuine platform team (not just infrastructure engineers doing platform work). Developer satisfaction with tooling is measured and improving. Most provisioning doesn't require human approval. ## Level 3: Product-Minded Platform **What it looks like:** - Platform team operates like an internal product team - Developer experience is actively designed, not just built - Feedback loops exist and drive roadmap - Platform capabilities evolve based on actual usage patterns - Cost, security, and performance are balanced against developer productivity **The benefit:** Platform actually gets used. Developers prefer it over alternatives. **The problem:** Requires product skills that infrastructure engineers often don't have. Hard to measure success—you're optimizing for developer productivity, which is notoriously difficult to quantify. **Signs you're here:** You have user research. You do deprecation thoughtfully. Developers complain when the platform is slow, not when they have to use it. ## Level 4: Adaptive Platform **What it looks like:** - Platform evolves automatically based on usage - Self-healing and self-tuning infrastructure - Predictive scaling and resource optimization - Seamless multi-cloud or hybrid operation - Deep integration with organizational workflow **The benefit:** The theoretical end state—infrastructure as invisible utility. **The problem:** Almost nobody is here. The complexity of building truly adaptive systems exceeds most organizations' capabilities and needs. **Signs you might be here:** You're probably not. If you think you are, you're likely at Level 3 with good automation. ## How to Assess Honestly Questions to determine where you actually are: 1. **Can a new developer ship to production on their first day?** If no, you're probably at Level 1 or below. 2. **Do developers come to the platform team for help, or to complain?** Help means they're trying to use the platform. Complaints mean they're forced to. 3. **What happens when someone needs something the platform doesn't support?** If the answer is "ticket and wait," you're at Level 2 at best. 4. **Does the platform team have a product manager?** If no, you're not at Level 3 yet. 5. **What percentage of deployments use the standard path?** Below 80% suggests the platform isn't meeting actual needs. ## The Common Mistakes ### Overinvesting at Level 1 Organizations often try to build Level 3 capabilities before establishing Level 1 basics. The result: a sophisticated platform nobody uses because the basics don't work. ### Underinvesting at Level 2 The jump from Level 1 to Level 2 requires dedicated investment—a real platform team, real product thinking, real maintenance commitment. Many organizations want Level 2 results with Level 1 investment. ### Ignoring the Human Element Platforms succeed or fail based on adoption. Adoption depends on developer experience. Developer experience requires talking to developers. Many platform teams are staffed with people who'd rather not talk to users. ### Building for the wrong users Platform teams often build for power users—other infrastructure engineers. But the people who need the platform most are developers who don't want to think about infrastructure at all. ## The Honest Path Forward 1. **Assess where you actually are.** Not where your architecture diagrams say you are. Where developers actually experience you. 2. **Identify the biggest friction point.** Not the most interesting technical challenge. The thing that actually slows developers down most. 3. **Solve that, then reassess.** Platform maturity is iterative. Each step reveals the next step. 4. **Measure developer outcomes.** Not platform metrics. Developer productivity, deployment frequency, time to recovery. 5. **Accept that it takes years.** Real platform maturity is a multi-year investment. If you're expecting results in quarters, recalibrate your expectations. Platform engineering is valuable. But only if you're honest about where you're starting and what it takes to get where you want to be. --- ## Product-First in the Age of AI: Why the Fundamentals Matter More, Not Less > AI makes product thinking more important, not less - start with user problems, not technology. **Date:** 2024-12-13 **Tags:** ai, product-design, strategy, developer-tools **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/product-first-ai-age **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/product-first-ai-age.md There's a pattern I keep seeing: teams rushing to add AI to products without first understanding what problem they're solving. The result is features that feel impressive in demos but don't survive contact with actual users. The irony is that AI makes product thinking *more* important, not less. Here's why. ## The AI Feature Trap It goes like this: "Our competitors are adding AI. We need AI features. What can we add?" This is technology-first thinking, and it leads to: - AI summaries that nobody asked for - Chat interfaces bolted onto products designed for different interactions - Features that work in controlled demos but fail on real data - Expensive inference costs for capabilities users don't value The underlying problem isn't the AI—it's the absence of clear thinking about what users actually need. ## What Product-First Looks Like Product-first means starting with the problem, not the solution. Even when the solution might involve AI. **The questions that matter:** 1. **What job is the user trying to do?** Not "what feature would be cool," but what are they actually trying to accomplish? 2. **Where do they struggle?** What takes too long? What requires expertise they don't have? Where do they get stuck? 3. **What would success look like to them?** Not metrics you can measure, but outcomes they would describe as valuable. 4. **Is this a problem AI can actually help with?** Sometimes yes. Often no. And often the answer is "partially, in a specific way." ## Three Patterns That Actually Work ### Pattern 1: AI as Accelerator, Not Replacement The best AI product features speed up things users already do, rather than trying to replace their judgment. **Example:** Code completion isn't replacing programmers. It's handling the parts of coding that are tedious and predictable, freeing developers to focus on the parts that require thought. **Why it works:** Users stay in control. The AI is clearly assistive. When it's wrong, users catch it immediately because they're engaged in the task, not delegating it. **Anti-pattern:** "The AI will handle it for you." Users don't trust this, and they're usually right not to. ### Pattern 2: AI for Exploration, Humans for Decisions Use AI to surface options, patterns, and possibilities. Leave the actual decisions to humans. **Example:** "Here are three approaches to this architecture, with trade-offs for each" is more useful than "Here's the architecture you should use." **Why it works:** It respects that the AI doesn't have full context. It lets users apply their own judgment. It's transparent about uncertainty. **Anti-pattern:** AI that presents conclusions without showing its reasoning. ### Pattern 3: AI to Lower the Floor, Not Raise the Ceiling The most valuable AI features often make things accessible that previously required expertise, rather than making experts more productive. **Example:** Natural language interfaces to databases help non-technical users answer questions they couldn't answer before. SQL experts weren't blocked—they just wrote the query. **Why it works:** It expands who can benefit from the product. It solves problems that were previously "call an expert and wait." **Anti-pattern:** AI features aimed at power users who don't actually need them. ## The Questions to Ask Before Adding AI Before building an AI feature, I recommend asking: 1. **How do users solve this problem today?** If they don't, why not? If they do, what's the actual friction? 2. **What happens when the AI is wrong?** Because it will be. Is the failure mode acceptable? 3. **Would users pay for this?** Or is it "nice to have" that doesn't actually change behavior? 4. **Can we build a simpler version without AI?** Sometimes rules and templates solve 80% of the problem at 10% of the cost. 5. **Does this make the product more complex to use?** AI features often add cognitive load even when they're trying to reduce it. ## The Uncomfortable Truth Most products don't need AI features. They need better versions of the features they already have. Clearer interfaces. Faster performance. Fewer bugs. Better documentation. AI is a powerful tool. But tools are only useful when applied to real problems. The teams building valuable AI products are the ones who started by understanding their users deeply enough to know where AI actually helps. That's product-first thinking. It's not a new concept. It's just more important now that the technology is capable enough to build solutions without problems. --- ## Building Semantic Search for a Static Site (Without a Backend) > Semantic search can run entirely client-side using pre-computed embeddings served as static files. **Date:** 2024-12-13 **Tags:** ai, gatsby, javascript, developer-tools **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/semantic-search-static-site **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/semantic-search-static-site.md I just shipped semantic search and related article recommendations for this blog—all running client-side, no API calls, no backend. Here's how it works and why you might want to do this yourself. ## The Problem with Tags at Scale Tags work fine when you have 20 articles. You click "aws" and see your AWS posts. Simple. But tags have limits: 1. **Taxonomy is arbitrary.** Your mental model of what belongs under "infrastructure" might not match your readers' expectations. 2. **Articles span concerns.** A post about AI-assisted DevOps touches both categories. Where does it go? 3. **Discovery vs. retrieval.** Tags help when you know what you want. They don't help when you're exploring. The real killer: users searching for "how to think about career decisions when AI is changing everything" won't find your article titled "Staying Level-Headed When AI Is Changing Everything" unless those exact words appear. ## The Solution: Vector Embeddings Instead of keyword matching, we embed articles as vectors in a high-dimensional space. Articles that are *semantically similar*—about the same concepts, even with different words—end up close together. This enables two features: 1. **Related Articles:** "You're reading about X, here are other articles about similar things" 2. **Semantic Search:** "Find articles about *this concept*" even if the words don't match The key insight: we can compute embeddings at build time and serve them as static JSON. The similarity computation happens in the browser—no backend needed. ## Architecture ``` Build Time Runtime (Browser) ─────────── ───────────────── ┌─────────────┐ ┌─────────────────┐ │ Markdown │ │ User types │ │ Articles │ │ search query │ └──────┬──────┘ └────────┬────────┘ │ │ ▼ ▼ ┌─────────────┐ ┌─────────────────┐ │ Extract │ │ Embed query │ │ title + │ │ (lazy-load │ │ excerpt │ │ model ~30MB) │ └──────┬──────┘ └────────┬────────┘ │ │ ▼ ▼ ┌─────────────┐ ┌─────────────────┐ │ Generate │ │ Cosine │ │ embeddings │──────────────────▶ │ similarity │ │ (MiniLM) │ embeddings.json │ against all │ └──────┬──────┘ (~150KB gzipped) │ articles │ │ └────────┬────────┘ ▼ │ ┌─────────────┐ ▼ │ public/ │ ┌─────────────────┐ │ embeddings │ │ Show ranked │ │ .json │ │ results │ └─────────────┘ └─────────────────┘ ``` ## Implementation: Build Time In `gatsby-node.js`, I added an `onPostBuild` hook that: 1. Queries all blog posts via GraphQL 2. Extracts title + excerpt for each 3. Generates 384-dimensional embeddings using `all-MiniLM-L6-v2` 4. Writes the results to `public/embeddings.json` ```javascript // gatsby-node.js (simplified) const { pipeline } = require('@xenova/transformers'); exports.onPostBuild = async ({ graphql }) => { const result = await graphql(` query { allMarkdownRemark { nodes { frontmatter { title, slug, tags } excerpt(pruneLength: 500) } } } `); const embedder = await pipeline( 'feature-extraction', 'Xenova/all-MiniLM-L6-v2' ); const embeddings = await Promise.all( result.data.allMarkdownRemark.nodes.map(async (node) => { const text = `${node.frontmatter.title}. ${node.excerpt}`; const output = await embedder(text, { pooling: 'mean', normalize: true }); return { slug: node.frontmatter.slug, title: node.frontmatter.title, embedding: Array.from(output.data) }; }) ); fs.writeFileSync('./public/embeddings.json', JSON.stringify(embeddings)); }; ``` The model runs in Node.js at build time via `@xenova/transformers`, which is a JavaScript port of Hugging Face's transformers library. No Python, no external API. Build time for 36 articles: about 30 seconds. ## Implementation: Related Articles The `RelatedArticles` component fetches the embeddings JSON and computes similarity: ```typescript // RelatedArticles.tsx (simplified) function cosineSimilarity(a: number[], b: number[]): number { let dot = 0; for (let i = 0; i < a.length; i++) { dot += a[i] * b[i]; } return dot; // vectors are pre-normalized } const RelatedArticles = ({ currentSlug }) => { const [related, setRelated] = useState([]); useEffect(() => { fetch('/embeddings.json') .then(r => r.json()) .then(articles => { const current = articles.find(a => a.slug === currentSlug); if (!current) return; const scored = articles .filter(a => a.slug !== currentSlug) .map(a => ({ ...a, score: cosineSimilarity(current.embedding, a.embedding) })) .sort((a, b) => b.score - a.score) .slice(0, 5); setRelated(scored); }); }, [currentSlug]); // render... }; ``` For 36 articles with 384-dimensional vectors, computing all pairwise similarities takes less than 1ms. This scales fine to hundreds of articles. ## Implementation: Semantic Search Search is more interesting because we need to embed the user's query at runtime. This means loading the model in the browser. The model is ~30MB. That's too heavy to load upfront, so we lazy-load it when the user focuses the search input: ```typescript // SemanticSearch.tsx (simplified) const SemanticSearch = () => { const embedderRef = useRef(null); const [modelLoading, setModelLoading] = useState(false); const loadEmbedder = async () => { if (embedderRef.current) return embedderRef.current; setModelLoading(true); const { pipeline } = await import('@xenova/transformers'); embedderRef.current = await pipeline( 'feature-extraction', 'Xenova/all-MiniLM-L6-v2' ); setModelLoading(false); return embedderRef.current; }; const search = async (query) => { const embedder = await loadEmbedder(); const queryEmbed = await embedder(query, { pooling: 'mean', normalize: true }); // Score all articles against query embedding const scored = embeddings.map(article => ({ ...article, score: cosineSimilarity(queryEmbed.data, article.embedding) })); return scored.sort((a, b) => b.score - a.score).slice(0, 10); }; // Pre-load model on input focus const handleFocus = () => { if (!embedderRef.current && !modelLoading) { loadEmbedder(); } }; // render... }; ``` First search takes 2-3 seconds while the model loads. Subsequent searches are nearly instant because the model is cached. ## The Webpack Problem One gotcha: `@xenova/transformers` includes `onnxruntime-node`, which is a native Node.js module. Gatsby's webpack tries to bundle it for SSR and fails. The fix is to configure webpack to exclude these modules during HTML generation: ```javascript // gatsby-node.js exports.onCreateWebpackConfig = ({ stage, actions, getConfig }) => { if (stage === "build-html" || stage === "develop-html") { actions.setWebpackConfig({ externals: getConfig().externals.concat((context, request, callback) => { if (/onnxruntime-node|sharp/.test(request)) { return callback(null, 'commonjs ' + request); } callback(); }), }); } }; ``` ## Performance Budget | Asset | Size | Load Strategy | |-------|------|---------------| | embeddings.json (36 articles) | ~380KB (~100KB gzipped) | Lazy load on article pages | | Transformer model | ~30MB | Lazy load on search focus, cached by browser | | Similarity computation | <1ms | Inline, negligible | At 300 articles, embeddings.json would be about 3MB uncompressed, ~800KB gzipped. Still acceptable for lazy loading. ## What I'd Do Differently **Pre-compute related articles at build time.** Right now, every article page fetches the full embeddings.json and computes similarity client-side. For 36 articles, this is fine. At scale, I'd compute the top 5 related articles per post during build and include them directly in the page data. **Add a similarity threshold.** Currently I show the top 5 related articles regardless of similarity score. Some articles might not have strong matches. I should hide the section if all scores are below, say, 0.4. **Consider a smaller model for search.** 30MB is heavy. There are quantized versions that are smaller, though potentially lower quality. Worth testing. ## Is This Worth It? For 30 articles? Probably overkill. Tags work fine. For 100+ articles where you want real discovery? Absolutely. Semantic search surfaces connections that keyword search misses. Related articles keep readers engaged without you manually curating "see also" links. The best part: it's all static. No API costs, no backend to maintain, no latency from network calls. Build once, serve forever. The embeddings infrastructure also opens up future possibilities: auto-generated topic clusters, conversational Q&A over your content, recommendation systems. All client-side, all from the same embedding vectors. That's the leverage of computing embeddings once and reusing them everywhere. --- ## The Death of Undifferentiated Heavy Lifting (And What Comes Next) > The boundary of 'undifferentiated work' keeps expanding; engineers must focus on increasingly higher-level differentiated value. **Date:** 2024-12-13 **Tags:** cloud, infrastructure, strategy, aws **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/undifferentiated-heavy-lifting **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/undifferentiated-heavy-lifting.md "Focus on what differentiates your business, not undifferentiated heavy lifting." Amazon has been saying this for nearly two decades. It's become so familiar that we've stopped examining what it actually means—and whether the category of "undifferentiated" is about to expand dramatically. ## The Original Insight The core idea was simple: running your own data centers, managing hardware, patching operating systems—these activities are necessary but don't create competitive advantage. Every company does them roughly the same way. So let someone else handle them and focus your engineering effort on things that actually differentiate your product. This insight drove cloud adoption. It was correct. Still is. But the boundary of what's "undifferentiated" keeps moving. ## The Boundary Shifts **2008:** Running servers is undifferentiated. Use EC2. **2012:** Managing relational databases is undifferentiated. Use RDS. **2015:** Running containers is undifferentiated. Use ECS/Kubernetes-as-a-service. **2018:** Building authentication is undifferentiated. Use Auth0/Cognito. **2020:** Running ML inference at scale is undifferentiated. Use SageMaker/Vertex. **2024:** Writing boilerplate code is undifferentiated. Use AI assistants. Each shift felt radical at the time and obvious in retrospect. The pattern is consistent: activities that once required specialized expertise become commodities that can be bought instead of built. ## What's Becoming Undifferentiated Now I see several categories actively commoditizing: ### Standard API Development Building CRUD APIs for well-understood domains is increasingly mechanical. The patterns are known. The code is similar across applications. AI can generate most of it. This doesn't mean API development is worthless. It means *routine* API development is. The value shifts to API design, edge cases, and integration—things that require understanding your specific context. ### Data Pipeline Assembly Connecting system A to system B with transformation logic in between. There are hundreds of tools for this now. AI can generate the configuration. The differentiated work is deciding *what* data to move and *how* to interpret it. ### Basic Frontend Implementation Converting designs to code for standard UI patterns. AI does this reasonably well now. The differentiated work is designing the interactions, handling complex state, and integrating with real backends. ### Standard Security Controls Baseline security—encryption, access control, audit logging—is increasingly table stakes that platforms provide. The differentiated work is threat modeling, security architecture, and incident response. ## What This Means for Engineers Some take this as a threat: "AI is coming for my job." I see it differently. **The work shifts, but doesn't disappear.** When we stopped managing servers, we didn't have fewer infrastructure engineers. We had infrastructure engineers doing different, often more impactful work. **The bar for "differentiated" rises.** Activities that were valuable become commodities. You need to operate at a higher level of abstraction to create value. **Judgment becomes more valuable.** As execution becomes easier, deciding *what* to execute becomes the bottleneck. Strategy, architecture, trade-offs—these matter more than ever. **Integration becomes the hard part.** Individual capabilities are commodities. Making them work together in your specific context is not. ## How to Think About This Questions I find useful when evaluating where to invest effort: 1. **Could someone else do this roughly the same way?** If yes, it's probably commoditizing or already has. Consider buying instead of building. 2. **Does this require understanding our specific situation?** Things that depend on your users, your constraints, your business model—these remain differentiated. 3. **What's the failure mode?** Undifferentiated doesn't mean unimportant. It means someone else can do it at least as well. Make sure they actually can before handing it off. 4. **What can we do with the freed capacity?** The point of avoiding undifferentiated work is to do more differentiated work. Make sure you're actually capturing that upside. ## The Uncomfortable Implication Here's what I think people don't want to hear: a lot of work that feels skilled and important is actually undifferentiated heavy lifting in disguise. Writing the 10,000th REST API doesn't differentiate your business, even if it requires technical skill. Building the same data pipeline with the same tools doesn't create competitive advantage, even if it takes effort. This doesn't mean these tasks are worthless or that the people doing them lack value. It means the economic dynamics are shifting. The same effort could create more value elsewhere. The engineers who thrive will be the ones who recognize this shift and position themselves on the differentiated side of the boundary—wherever it moves next. ## A Final Thought Werner Vogels was right in 2006. The insight has only gotten stronger. The question for each of us is: what's the undifferentiated heavy lifting in my work right now, and what becomes possible if I let it go? --- ## Adding Session Memory to Claude Code with Hooks > Use Claude Code's hooks to automatically save and restore session context across restarts. **Date:** 2024-12-12 **Tags:** claude-code, ai, developer-tools, automation **URL:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/claude-code-session-memory **Markdown:** https://d28fg9n3ewxoa7.cloudfront.net/knowledge-base/claude-code-session-memory.md Claude Code is a powerful AI coding assistant, but it has a limitation: when you restart it, all conversation context is lost. You're back to square one, re-explaining what you were working on. This post shows how to use Claude Code's hook system to automatically save and restore session context across restarts. ## The Problem Claude Code runs as an interactive CLI session. During a session, Claude builds up context about your codebase, the task at hand, and decisions you've made together. But that context lives only in memory. When you restart Claude Code (to reload an MCP server, for example), you lose everything: - What files you were working on - The approach you'd agreed upon - Debugging context and hypotheses - Task progress You could manually summarize and re-paste context, but that's tedious and error-prone. ## The Solution: Session Hooks Claude Code provides lifecycle hooks that run shell commands at specific events. Two hooks are particularly useful: | Hook | When it runs | |------|--------------| | `SessionEnd` | When Claude Code exits (quit, clear, logout) | | `SessionStart` | When Claude Code starts or resumes | By combining these, we can: 1. Save metadata about the session when it ends 2. Load that metadata when a new session starts 3. Give Claude automatic context about what you were working on ## Implementation ### Hook Configuration Add hooks to `~/.claude/settings.json`: ```json { "hooks": { "SessionStart": [ { "matcher": "", "hooks": [ { "type": "command", "command": "$HOME/.claude/hooks/load-context.sh" } ] } ], "SessionEnd": [ { "matcher": "", "hooks": [ { "type": "command", "command": "$HOME/.claude/hooks/save-context.sh" } ] } ] } } ``` The `matcher` field can filter by working directory pattern. Empty string matches all directories. ### Save Context Hook The `SessionEnd` hook receives JSON on stdin with session metadata. We extract the working directory and find recently modified files: ```bash #!/bin/bash # ~/.claude/hooks/save-context.sh # Save lightweight session metadata on session end INPUT=$(cat) CWD=$(echo "$INPUT" | jq -r '.cwd // empty') SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') REASON=$(echo "$INPUT" | jq -r '.reason // "unknown"') if [ -n "$CWD" ]; then CONTEXT_FILE="$CWD/.claude/last-session.json" mkdir -p "$CWD/.claude" # Get recently modified files (last 30 min) RECENT_FILES=$(find "$CWD" -type f \ \( -path "*/src/*" -o -path "*/.claude/*" -o -name "*.md" \) \ -mmin -30 2>/dev/null \ | grep -v node_modules \ | grep -v ".git/" \ | head -20 \ | jq -R -s 'split("\n") | map(select(length > 0))') # Save metadata cat > "$CONTEXT_FILE" << EOF { "timestamp": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")", "session_id": "$SESSION_ID", "exit_reason": "$REASON", "cwd": "$CWD", "recent_files": $RECENT_FILES, "note": "Review these files to restore context from previous session" } EOF fi exit 0 ``` This creates a `.claude/last-session.json` file in each project: ```json { "timestamp": "2024-12-12T22:45:00Z", "session_id": "abc123", "exit_reason": "exit", "cwd": "/Users/dev/my-project", "recent_files": [ "/Users/dev/my-project/src/index.ts", "/Users/dev/my-project/CLAUDE.md" ], "note": "Review these files to restore context from previous session" } ``` ### Load Context Hook The `SessionStart` hook checks for saved context and outputs a reminder: ```bash #!/bin/bash # ~/.claude/hooks/load-context.sh # Load previous session context on session start INPUT=$(cat) CWD=$(echo "$INPUT" | jq -r '.cwd // empty') SOURCE=$(echo "$INPUT" | jq -r '.source // "startup"') CONTEXT_FILE="$CWD/.claude/last-session.json" # Only load on fresh startup, not resume/compact if [ "$SOURCE" = "startup" ] && [ -f "$CONTEXT_FILE" ]; then TIMESTAMP=$(jq -r '.timestamp // empty' "$CONTEXT_FILE") RECENT_FILES=$(jq -r '.recent_files // [] | join(", ")' "$CONTEXT_FILE") # Check if context is less than 24 hours old if [ -n "$TIMESTAMP" ]; then EPOCH_TIME=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$TIMESTAMP" +%s 2>/dev/null || echo 0) CONTEXT_AGE=$(( $(date +%s) - $EPOCH_TIME )) if [ "$CONTEXT_AGE" -lt 86400 ]; then # Format: "Thu Dec 12 at 10:45 PM" READABLE_DATE=$(date -j -f "%Y-%m-%dT%H:%M:%SZ" "$TIMESTAMP" "+%a %b %d at %I:%M %p" 2>/dev/null || echo "$TIMESTAMP") echo "Previous session ended $READABLE_DATE. Recently modified files: $RECENT_FILES" fi fi fi exit 0 ``` Key details: - Only triggers on `startup`, not `resume` or `compact` (which preserve context) - Ignores context older than 24 hours - Outputs human-readable text that Claude sees as context ### Making Hooks Executable ```bash chmod +x ~/.claude/hooks/save-context.sh chmod +x ~/.claude/hooks/load-context.sh ``` ## How It Works The hook system passes data via stdin (JSON input) and stdout (context output): ``` ┌─────────────────────────────────────────────────────────────┐ │ SessionEnd Hook │ │ │ │ stdin (JSON): │ │ { │ │ "session_id": "abc123", │ │ "cwd": "/Users/dev/project", │ │ "reason": "exit", │ │ "transcript_path": "~/.claude/projects/.../session.jsonl"│ │ } │ │ │ │ Hook saves: .claude/last-session.json │ │ │ └─────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────┐ │ SessionStart Hook │ │ │ │ stdin (JSON): │ │ { │ │ "session_id": "def456", │ │ "cwd": "/Users/dev/project", │ │ "source": "startup" │ │ } │ │ │ │ stdout (added to Claude's context): │ │ "Previous session ended Thu Dec 12 at 10:45 PM. │ │ Recently modified files: src/index.ts, CLAUDE.md" │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ## Why Not Save the Full Transcript? Claude Code stores full conversation transcripts at `transcript_path`. You might be tempted to save and reload these directly, but there are issues: 1. **Size**: Transcripts grow large quickly. Loading a huge context on startup wastes tokens and can exceed limits. 2. **No compaction**: The transcript includes every message, even superseded ones. Claude's `/compact` command creates summaries, but there's no way to trigger it from a hook. 3. **Stale context**: Yesterday's debugging session about a bug you've since fixed isn't helpful—it's confusing. The lightweight approach (just file paths and timestamps) gives Claude enough to ask intelligent questions or proactively read relevant files, without the baggage. ## Extending the Approach ### Add Task Summaries Modify `save-context.sh` to prompt for a summary: ```bash # Add to save-context.sh if [ -t 0 ]; then read -p "Session summary (optional): " SUMMARY # Include $SUMMARY in the JSON output fi ``` ### Project-Specific Context Use the `matcher` field to run different hooks per project: ```json { "hooks": { "SessionStart": [ { "matcher": "*/my-special-project", "hooks": [ { "type": "command", "command": "$HOME/.claude/hooks/special-project-context.sh" } ] } ] } } ``` ### Track Git State Include branch and uncommitted changes: ```bash GIT_BRANCH=$(cd "$CWD" && git branch --show-current 2>/dev/null) GIT_STATUS=$(cd "$CWD" && git status --porcelain 2>/dev/null | head -10) ``` ## Limitations - **No automatic compaction**: You still need to manually run `/compact` for long sessions - **macOS date syntax**: The `date -j` flag is macOS-specific; Linux needs different syntax - **Hook failures are silent**: If a hook errors, Claude Code continues without the context ## Conclusion Claude Code's hook system enables lightweight session persistence without complex infrastructure. By saving just enough context—recently modified files and timestamps—we can restore working memory across restarts. The full code is available in this post. Drop the scripts in `~/.claude/hooks/`, update your settings, and your next session will know where you left off. ---