Wanted to share a relevant short by Matt Pocock: https://www.youtube.com/shorts/Fj8DKMbdIzU ## TLDR: He talks about the tradeoff between asking an agent to understand a system through docs vs code. He doesn't like the idea of using docs as the source of truth, but as higher level knowledge base (e.g. glossary, architectural decision) and helping agents navigate the codebase. ## Discussion Question: What information have you found is better represented in the code vs in docs? ## Key Points: 1. Code should b be self explanatory for an AI agent to understand directly. 2. Docs are not executable and testable. 3. Docs can drift out of sync and no longer match code, causing conflicting sources of truth. 4. Docs should hold higher level context such as discussions and cross functional decisions (e.g. design and architectural decisions) 5. Use a thin layer of docs to help navigate the codebase ( insert ICM here) 6. Docs as the source of truth where reading them to understand the code is not ideal ## Relevance to my work: I am trying to understand how to implement ICM for ongoing app management and improvement (read as software factory). This tradeoff between holding truth in code vs docs is top of mind. For example, I'm currently doing a significant amount of UI work. In ICM, i have defined relevant user workflows and linked them to their relevant components. The workflow documentation provides higher level context and intent. However, I am still trying to determine how much documentation is enough. I want to keep reasoning behind decisions so future work respects them, without creating a second representation of the app. Some simple examples where the rationale is not always obvious from implementation: - We display a timestamp here because that level of granularity is important for this workflow. - We use green rather than blue here to distinguish completion vs continuation action. - We place this data together on the same row to reinforce their connection.

Gather round, Clief Notes crew — we’re opening The Legends: a classroom on the Frontier built around two gunslingers who deliver real systems, not hype. Each legend has a dedicated folder packed with signature builds, frameworks, and battle-tested wisdom. Start where the dust is thickest for you. 📐 Bas Rosario – The Wise Architect’s Library Master planner and blueprint boss. Bas designs for deep understanding and human–AI collaboration so you stay in control — frameworks, systems thinking, responsible AI, and work that still feels human. 👷‍♂️ Don Roy – The Master Builder’s Forge Hammer in hand, fire in the forge. Don turns ideas into working tools: automation, quality control, content systems, Remotion + AI builds, and anti-slop standards that keep what you ship durable. These two are the heartbeat of this classroom — grinding, growing, and lifting the whole crew. Your move: Pick a folder. Open it. Start forging. https://www.skool.com/cliefnotes/classroom/b5143824?md=61c684c877384eefbd11c804f83aac05 Who are you riding with first — Architect or Builder? Drop a 🤠 below and go make something that lasts.

TLDR: An agent was running an entire data workflow and performing work that a script should have been doing. Splitting the steps into code and keeping the agent for real judgement made the workflow faster, cheaper, more deterministic. Anyone else splitting workflows into code? ## Context I recently read the argument we need to use code more in our AI workflows since its fast, deterministic, and costs 0 tokens to run 🥳. I revisited a slow and token expensive workflow to see if any improvement can be made (Hint: there was), here is my story. ## The workflow I built a workflow to enrich data on a directory site I am building. 1. Find records to enrich 2. Discover the official source ( e.g. company website) 3. Extract information 4. Decide what needs adding or fixing 5. Write it back into the directory 6. Open a PR My first instinct was to throw (possibly too hard) an agent at the whole thing, one smart loop. It was slow and had some performance issues (skill issue I know). Some steps were obvious to switch: - Deciding which records to process is a filter, not a decision. - Writing changes to a database is an API call, not a choice. I was tolerating token cost and hallucination risk for steps a script does perfectly, every time, for free. Side note: I didn't run token cost comparison or analysis of many tokens were used for orchestration vs actual work. ## Reframing the workflow The workflow has 3 actors: - Code - You - Agents Thinking about it this way, the agent only touches the part a script structurally can't do. Some problems it solved: 1. The agent didn't try loading the entire database of options into context 2. It kept extracting a value the schema had no column for, and improvising a workaround every time ## Insights The big insight for me is: if an agent is solving the same structural problem repeatedly instead of once, it's not doing judgment work, it's doing the job code should've done from the start. The LLM brain works on the decision steps.

ICM for existing workflows is well discussed in the paper. What I’m trying to understand is how ICM could be applied to new feature development, where the workflow can be non-linear. A possible ICM pipeline could be: - 01_problem_definition - 02_requirements - 03_solution_options - 04_feature_spec - 05_technical_plan - 06_implementation - 07_tests_review But I'm not sure thats the right way to think about it (reusable staged workflow vs custom stage structure per feature). Has anyone used ICM for this?

That's the leap most people never take. Roughly 90% of our members are still on the other side: scrolling, saving, getting value, never saying a word. Not a knock. Just the math. Lurking isn't failure. It's the default. But you showed up. And that shift compounds fast. The classroom teaches you the tools. The community teaches you how to think with them. When you participate, you get compression — months of grinding folded into a thread someone else already broke so you don't have to. Less friction. Faster outcomes. Personal growth and business growth in the same lane. You don't need a hot take. You need a real question. Give before you extract. Your lurker era wasn't wasted — you were loading context. Welcome to Level 2. A few of you just made the jump, and I want to call it out: • @Vamsi Acharya • @Stacey Lubowa • @Martin Brion • @Mark Benjamin • @Keith Langskov • @Patti Wilcox • @Novus Vella • @Tony Rhodes @Cain Gray If you're still lurking — go check out what they're posting. Real builds. Real questions. No fluff. That's the energy we want in here. And if I missed you — my bad. Drop your name below. We'll get you in the next round. The reward for showing up isn't points. It's speed. You stop duct-taping alone. You stop renting confusion. Your stack starts to click because other people's scars are now in your context. What finally made you break the ice? ───