<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Peter Heller on Medium]]></title>
        <description><![CDATA[Stories by Peter Heller on Medium]]></description>
        <link>https://medium.com/@peter.heller?source=rss-23637872e95b------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/1*ZEwgL11HIZ0jGN-gA10OcA.jpeg</url>
            <title>Stories by Peter Heller on Medium</title>
            <link>https://medium.com/@peter.heller?source=rss-23637872e95b------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sat, 21 Nov 2026 11:37:09 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@peter.heller/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Jurisdiction, Not Inheritance — Why Agents Are Citizens, Not Subclasses]]></title>
            <link>https://medium.com/@peter.heller/jurisdiction-not-inheritance-why-agents-are-citizens-not-subclasses-3fe12bc1886a?source=rss-23637872e95b------2</link>
            <guid isPermaLink="false">https://medium.com/p/3fe12bc1886a</guid>
            <category><![CDATA[software-architecture]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[programming]]></category>
            <category><![CDATA[pair-programming]]></category>
            <category><![CDATA[engineering-management]]></category>
            <dc:creator><![CDATA[Peter Heller]]></dc:creator>
            <pubDate>Thu, 30 Apr 2026 12:25:32 GMT</pubDate>
            <atom:updated>2026-04-30T12:54:27.597Z</atom:updated>
            <content:encoded><![CDATA[<h3>The Navigator/Driver Series — Article 4</h3><p><em>Peter Heller | Adjunct Lecturer in Computer Science, Queens College CUNY | Founder, Mind Over Metadata LLC</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_IhHb9T631jOi2FYs7jxCQ.jpeg" /></figure><p>Austin asked a clean question.</p><p><em>“And is an Interface a contract that an Implementation fulfills in the same way that you say the system.md is a contract?”</em></p><p>It is the right question — and it is almost exactly right. That “almost” is where Article 4 lives.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*meRB3MqVHZSUDzsuknOOyA.jpeg" /></figure><h3>The OOP Reflex</h3><p>Every developer who has written an interface reaches for that metaphor first. It feels precise. An interface declares a shape: here are the methods, here are the types, here is what any conforming implementation must expose. The compiler enforces it. The contract is mechanical, verifiable, and unambiguous.</p><p>So when I described system.md as a behavioral contract in Article 3 — <em>The Spec Is the Contract — And system.md Is Its Constitution</em> — the natural analogy was the interface. Austin made the leap immediately: agents inherit from system.md, which means agents are jurisprudences of system.md.</p><p>The instinct is correct. The vocabulary is wrong.</p><h3>Where the Metaphor Breaks</h3><p>An interface is a <strong>syntactic contract</strong>. It specifies <em>what</em> methods exist and <em>what types</em> flow through them. It says nothing about <em>how</em> the implementation reasons, or <em>under what authority</em> it acts. A sort() that sorts backwards still compiles. It satisfies the interface perfectly — and produces chaos.</p><p>A system.md is a <strong>semantic contract</strong>. It does not specify the shape of inputs and outputs. It defines the <em>boundaries of judgment</em> from which all responses emerge. It tells the agent not what it must expose, but what it must <em>be</em>.</p><p>That is a different kind of contract entirely.</p><h3>Governed, Not Derived</h3><p>Austin’s formulation — <em>agents inherit from system.md</em> — imports the wrong metaphor at the most critical point.</p><p>Inheritance implies a type hierarchy. The child extends the parent. The child can override. In Java, you can override a method and completely replace what the parent defined. Inheritance is a structural relationship between types — and it is, by design, negotiable.</p><p>Governance is not negotiable.</p><p>A citizen does not override the Constitution. A citizen does not extend it. The citizen operates within it — or violates it. There is no third state.</p><p>This is what makes the behavioral contract <em>stronger</em> than an interface. An interface permits any conforming implementation. A system.md constrains the reasoning space from which all responses emerge. The Field Guardian is not implementing IFieldGuardian. It is operating under a charter that makes its assumptions visible, its authority bounded, and its failures interpretable.</p><p>That is not implementation. That is jurisprudence.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zZ_lrMN-Y-E9Hs4mK_kAvA.jpeg" /></figure><h3>The Compiler Cannot Help You Here</h3><p>In software, the compiler enforces the interface. If your class fails to implement a required method, the build fails. The violation is caught before it runs.</p><p>Agentic systems have no such compiler. The LLM will respond to any prompt with something. The question is not whether it responds — it is whether it responds <em>within its authority</em>. A vague prompt produces a vague agent: capable, perhaps, but ungoverned. It will drift. It will hallucinate scope. It will fill the vacuum of unspecified boundaries with inference — and inference is not governance.</p><p>The system.md is what replaces the compiler. Not mechanically — <em>constitutionally</em>. It makes every assumption explicit. It names the mission, the authorities, the termination conditions, the cost model, the boundaries. It does not prevent the agent from receiving any input. It governs what the agent <em>is allowed to become</em> in response.</p><p>If your agent can be talked out of its system.md by a sufficiently clever prompt, you do not have a behavioral contract. You have a suggestion.</p><h3>The Config File Mistake</h3><p>A common treatment of the behavioral file — one that appears across Medium, GitHub READMEs, and practitioner forums — reduces it to configuration. A settings block. A prompt with better formatting.</p><p>This is the canonical mistake — and it is precisely the mistake the interface analogy enables. If system.md is an interface, then it is a technical artifact. Something the implementation satisfies and then moves past. Something the LLM reads once and then answers around.</p><p>A constitution is not a config file. You do not satisfy a constitution and move on. You operate within it permanently, for the lifetime of the agent, across every input, every session, every invocation. The constitution is not the starting state. It is the invariant.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ezpX1mZdzsgbblafd8tGLw.jpeg" /></figure><h3>Logic Legos, Swim Lanes, and the Stitch</h3><p>Austin landed on another instinct worth keeping: <em>logic legos</em>.</p><p>Each lego is an agent. Each agent has one system.md — one charter, one mission, one bounded authority. That is SRP made agentic. That is KISS made structural. And each agent has one LLM — selected for the task, matched to the cost model, specified in the charter. The LLM is not the agent. The system.md is the agent. The LLM is the engine it runs on.</p><p>This distinction matters because LLMs are reusable. The same qwen3 instance can power the Extract agent in one pipeline and the Summarize agent in another. The charter changes. The engine does not. This is WORM — <strong>Write Once Reuse Many</strong> — applied to agentic architecture. The system.md is written once, governed permanently, and reused across sessions, pipelines, nodes, and team members without mutation. The lego snaps into any board that accepts its shape.</p><p>The swim lanes are the stitching — the Fabric pipeline that chains agents in sequence, passing governed output from one bounded authority to the next. The lego does not reach across the lane. It does not inherit the neighboring agent’s context. It receives a structured input, executes within its charter, and hands a structured output to the next lane.</p><p>That chain is not inheritance. It is <strong>agentic chaining</strong> — each agent sovereign within its swim lane, each handoff governed by the contract between lanes. The Navigator designs the lanes. The Driver executes within them. The system.md is the wall between lanes — not a suggestion, not a preference, not a base class to override. A wall.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*hEjDkjGgXKTjQM4PXIDDIQ.jpeg" /></figure><h3>The Siamese Twin</h3><p>Article 3 established the spec as the contract at the methodology layer — the SDD principle that governs what gets built and why.</p><p>Article 4 closes the pair: system.md is the behavioral contract at the implementation layer — the constitutional document that governs what the agent <em>is</em> while it builds.</p><p>They are siamese twins. They share the same spine. One cannot live without the other. The spec without the behavioral contract is philosophy. The behavioral contract without the spec is a prompt.</p><p>Together, they are a governed agentic system.</p><h3>The Definition of Governed Authority</h3><p>Every developer who has built a system reaches for the interface analogy — and they should. It is the right instinct, reaching for the wrong tool. An interface tells a class what it must expose; a system.md tells an agent what it must <em>be</em> — and what it cannot become, regardless of what it is asked. The difference is not syntactic. It is constitutional. A subclass overrides. A citizen cannot. That is not a limitation — that is the definition of governed authority.</p><p><em>Peter Heller teaches CSCI 331 and CSCI 381 at Queens College CUNY and is the founder of Mind Over Metadata LLC. He writes about the Navigator/Driver model, agentic architecture, and the governance of AI systems. Article 3 in this series — “The Spec Is the Contract — And system.md Is Its Constitution” — is available on Medium.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3fe12bc1886a" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Spec Is the Contract — And system.md Is Its Constitution]]></title>
            <link>https://medium.com/@peter.heller/the-spec-is-the-contract-and-system-md-is-its-constitution-4ad5505320ff?source=rss-23637872e95b------2</link>
            <guid isPermaLink="false">https://medium.com/p/4ad5505320ff</guid>
            <category><![CDATA[technology]]></category>
            <category><![CDATA[future-of-work]]></category>
            <category><![CDATA[leadership]]></category>
            <category><![CDATA[education]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <dc:creator><![CDATA[Peter Heller]]></dc:creator>
            <pubDate>Wed, 01 Apr 2026 18:30:39 GMT</pubDate>
            <atom:updated>2026-04-01T18:30:39.615Z</atom:updated>
            <content:encoded><![CDATA[<p><em>What you never do is hand a crew a vague idea and say: figure it out. That is not building. That is hoping.</em></p><p><em>How Occam’s Razor, a Scarecrow, and three little pigs explain the architecture most AI developers are missing.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1016/1*OQYELCztN29miNFrLTiRAQ.png" /><figcaption><em>Pre-Think is governance. Vibe coding is hope. Only one of them produces a certificate of occupancy.</em></figcaption></figure><h3>Before We Talk About Architecture — Let’s Talk About a House</h3><p>You want to build a two-family house. You have the land. You have the vision. You have the budget.</p><p>What do you do first?</p><p>If you are wise — if you have ever lived through the consequence of not being wise — you do not buy lumber. You do not hire a crew. You do not start hammering nails into wood based on a picture in your head.</p><p>You sit down with an architect and you think.</p><p>You describe what you need. Two separate entrances. Shared utilities or separate — that is a decision, not an assumption. Three bedrooms upstairs, two down. Zoning compliance. Fire separation requirements between units. HVAC routing. Load-bearing walls. The architect asks questions you did not know you needed to answer. You answer them. Assumptions become explicit. Decisions get made. The picture in your head — imprecise, optimistic, full of things you have not thought about yet — becomes a blueprint.</p><p>That blueprint is not documentation of the house.</p><p>It is the house — in its most governable form.</p><p>Every contractor works from it. Every inspector verifies against it. Every subcontractor — electrician, plumber, framer — takes their scope from it. The blueprint is the contract between you and everyone who builds on your behalf. Nothing gets built that is not in it. Nothing gets changed without a signed change order — dated, attributed, traceable.</p><p>And behind every blueprint is something the client rarely sees — the architect’s project journal. Every conversation. Every decision considered and rejected. Every constraint that shaped a room dimension. The journal is not the blueprint. It is the institutional memory behind the blueprint. Twenty months from now, when someone asks why the load-bearing wall is where it is, the journal answers. The blueprint shows what was decided. The journal shows why.</p><p>What you never do is hand a crew a vague idea and say “figure it out.”</p><p>That is not building. That is hoping. And hoping does not produce a certificate of occupancy.</p><p>Now replace the architect with a Navigator. Replace the blueprint with a specification. Replace the contractor with an AI Driver. Replace the change order with an Architecture Decision Record (ADR) committed to git. Replace the project journal with a knowledge vault.</p><p>You have just described Spec-Driven Development (SDD).</p><p>The two-family house and the governed agentic system share the same architecture. Conceptualization first. Specification second. Implementation third. In that order. Always.</p><p>The industry has a name for what happens when you skip steps one and two and go straight to three. They call it vibe coding — generating code from impulse, from a prompt, from a picture in your head that has not yet been forced into the precision of a blueprint. It produces software the way an unlicensed contractor produces a house — fast, cheap, and full of things that will fail inspection.</p><p>The spec is the blueprint. The git commit is the signed contract. The Navigator is the architect. The Driver builds exactly what the spec governs — no improvisation, no scope creep, no “I thought you meant something else.”</p><p>Pre-Think is not a methodology preference. It is a governance gate.</p><p>In its most evolved form — currently being validated — the Navigator loads prior session artifacts from the knowledge vault into Claude Code’s Think mode before a single line of code is written. The vault becomes the governing brief. The spec governs the plan. The plan governs the code. Vibe coding is not just replaced — it is architecturally impossible.</p><p>This is the Proof of Concept (POC) that closes the loop between Navigator governance and Command Line Interface (CLI) execution. The architecture is sound. The validation is underway.</p><p>The blueprint does not become obsolete when the spec is written. It becomes the spec — translated into the language machines govern and git commits make immutable.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*zisW9CYh7GOeWD6nt5lg4A.png" /><figcaption><em>Blueprint to behavioral contract — the same governing intent, translated into the language machines execute and git commits make immutable.</em></figcaption></figure><p>The spec and the behavioral contract are Siamese twins — bound at birth, inseparable in function, but operating at different layers of the system. Confuse them and you will build a very sophisticated prompt. Understand them and you will build a governed system.</p><p>That is the thesis. Everything that follows is the proof.</p><h3>Occam’s Razor — The Blade That Cuts to Governance</h3><p>William of Ockham — the 14th century English friar and philosopher — gave us the principle that bears his name: <em>among competing explanations, the one with the fewest assumptions is preferred.</em> Cut away everything unnecessary. What remains is the truth.</p><p>Occam’s Razor applied to agentic architecture produces a statement that sounds almost too simple to be profound:</p><p><strong>The simplest explanation of what governs an AI agent is also the most precise one: a file.</strong></p><p>Not a process. Not a framework. Not a meeting. Not a methodology document that lives in Confluence and dies the day it is written.</p><p>A file. Version controlled. Human readable. Machine governable. Committed to git. Immutable after merge.</p><p>That file is system.md — the behavioral contract. And the principle that gives it authority is SDD — the governance architecture where the specification is the contract, and the git commit is the notarized signature.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jiDRwh093613oGFYaIJ4DA.png" /><figcaption>The simplest explanation of what governs an AI agent is also the most precise one: a file.</figcaption></figure><p>“The blueprint parallel makes sense. The Navigator as architect makes sense. But when I open a session with an AI Driver, what exactly is the blueprint? What is the governing document that plays the role the spec plays in this methodology?”</p><p>That is precisely the right question. And the answer requires two concepts that most developers treat as synonyms but are not — and confusing them is exactly why most agentic systems fail the inspection.</p><p>Let me show you the distinction with a blade.</p><h3>The Blade — Metaphor vs. Analogy</h3><p>Most technical writers use these words interchangeably. They should not.</p><p>A metaphor says one thing <em>is</em> another. “The Scarecrow is an agentic agent.” Full stop. It collapses the distance between two things to illuminate one of them.</p><p>An analogy says one thing is <em>like</em> another in specific ways. “The Scarecrow is like an agentic agent because he has a defined role, operates within constraints, and defers to a governing authority when his boundaries are exceeded.” An analogy is a comparison instrument — it tells you the precise dimensions of the similarity.</p><p>Why does this matter? Because the entire problem of AI agent design lives in that gap.</p><p>When developers say “just tell the AI what to do,” they are using metaphor thinking — they believe the prompt is the instruction. When architects say “the behavioral contract governs the agent,” they are using analogy thinking — they understand the specific dimensions of the relationship between the agent and the rules that bind it.</p><p>This is Occam’s Razor at work. The metaphor feels simpler — one word, prompt, covers everything. But it carries hidden assumptions that collapse the moment the system scales. The analogy feels more complex — but it is actually simpler, because it makes every assumption explicit. Explicit assumptions can be governed. Hidden ones cannot.</p><p>The behavioral contract is not a metaphor for governance. It is governance — at the implementation layer. Let me show you what that means.</p><p>This is KISS — Keep It Simple and Standard — applied not as a simplification strategy but as a governance philosophy. Make every assumption explicit. Leave nothing hidden. Spell out what the agent is and what it cannot be. The same principle that governs a behavioral contract governs every sentence in this article.</p><h3>The Scarecrow as a Governed Agent</h3><p>Consider the Scarecrow from The Wizard of Oz not as a literary character but as a systems architecture problem.</p><p>He has a role: guard the cornfield. He has authorities: he can wave his arms, make noise, move within the field. He has constraints: he cannot leave the field, cannot harm the crows, cannot redefine his own mission. He has a termination condition: his job ends when the harvest is complete or when Dorothy arrives. He has a failure mode: when the crows figure out he is not real, he reports the failure — he does not improvise a new identity.</p><p>Now look at what you just read. That is not a prompt. That is not a description. That is a behavioral contract — a complete specification of what the agent is, what it can do, what it cannot do, and what happens at the boundaries of its authority.</p><p>A prompt would say: “You are a scarecrow. Scare the crows.”</p><p>A behavioral contract says: “You are the Field Guardian agent. Your mission is crop protection. Your authorized tools are physical deterrence within the designated perimeter. You do not negotiate with crows. You do not expand your perimeter. You report anomalies to the Navigator. You terminate on harvest completion.”</p><p>The prompt tells the agent what to do. The behavioral contract tells the agent what it <em>is</em> — and therefore what it cannot be.</p><p>Occam’s Razor again: the behavioral contract looks more complex. It is not. It is simpler — because every assumption is visible. The prompt looks simpler. It is not. It is a governed system waiting to collapse under the weight of its hidden assumptions.</p><p>That is the distinction that floats over most people’s heads. Let me make it structural.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/736/1*3EGjI768tKsFYsg-ntPQ0Q.png" /><figcaption>A prompt says: scare the crows. A behavioral contract says: here is everything you are — and everything you cannot become.</figcaption></figure><h3>The Technical Breakdown</h3><p>Before the table — one clarification that will save you from the most common mistake in agentic system design.</p><p>A persona is not a behavioral contract. It is one component of one.</p><p>A persona answers: who is this agent? It lives in the Identity section — the first of six components. Developers who stop at persona have named their agent. They have not governed it. They know who the agent is. They have no idea what it cannot do, when it stops, what it costs, or what happens when it exceeds its authority.</p><p>The dangerous interpretation: “behavioral contract” is just a fancy synonym for “persona.” It produces agents with identity but no governance — agents that know who they are and have no constitution to tell them who they cannot become.</p><p>A persona is the larval stage. The behavioral contract is the adult form. Every behavioral contract contains a persona. No persona contains a behavioral contract. They are parent and child — not synonyms.</p><p>When we formalized the behavioral contract in a production Navigator/Driver system, we formalized the behavioral contract into six components. Every governed agent has all six. An agent missing any one of them is not governed — it is prompted. This is the line between a persona and a behavioral contract — a distinction that matters more than most developers realize.</p><p>Every one of these components is explicitly defined in system.md — the behavioral contract file that governs every governed agent in a Navigator/Driver system.</p><p>Here is a fragment of a real behavioral contract from a production Navigator/Driver session:</p><pre># Identity<br>You are the Wisdom Extraction agent for Mind Over Metadata LLC.<br>Role: Content Intelligence Pipeline</pre><pre># Mission<br>Extract structured wisdom from unstructured content using a<br>multi-vendor Fabric pattern pipeline. Terminate when all five<br>pipeline steps complete and output artifacts are written.</pre><pre># Authorities<br>Authorized tools: fabric patterns, ollama local inference,<br>gemini API, claude API. You do not write to any path outside<br>the designated output directory.</pre><pre># Lifecycle<br>Pre-tool-call hook validates vendor selection.<br>Post-tool-call hook writes ADR-009 cost entries.<br>Task-complete hook commits the session total.</pre><p>This is not a prompt. This is a constitutional document.</p><h3>The Siamese Twins — Where Most People Get Lost</h3><p>Here is where the two concepts become inseparable.</p><p>“The Spec Is the Contract” — this is the governing principle of the methodology introduced above. It operates at the methodology layer. It means: before a line of code is written, before an agent is instantiated, before a Driver types a single command — the specification is the binding agreement between the Navigator and the system. The spec is not documentation. It is the acceptance criterion. It is the court of record. The git commit that contains the spec IS the signed contract.</p><p>system.md is the behavioral contract — this operates at the implementation layer. It is how the spec becomes executable. It is the translation of the Navigator’s intent into the governing logic that constrains every action the agent takes.</p><p>They are Siamese twins because:</p><p>The spec without the behavioral contract is philosophy. You have decided what the system should do, but nothing enforces it at execution time.</p><p>The behavioral contract without the spec is a sophisticated prompt. The agent is governed in the moment, but there is no immutable record of why it was designed that way.</p><p>Together they form a governed system. The spec is the WHY and the WHAT. The behavioral contract is the HOW and the GOVERN. They share the same bloodstream — the Fully Qualified Skill Name (FQSN), which is the repository path that connects the spec record to the behavioral contract file.</p><pre>Spec repo commit          system.md file<br>(The contract signed)     (The constitution enforced)<br>        ↓                         ↓<br>   git blame                  agent execution<br>   Who decided this?          What governs now?<br>   When?                      What can it touch?<br>   Why?                       What happens at the boundary?<br>        └──────────────────────────┘<br>                the repository path as the shared key</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/656/1*AKxjQel8Kv3hK1VpOMz5qQ.png" /><figcaption>The spec is the WHY. The behavioral contract is the HOW. The repository path is the bloodline they share.</figcaption></figure><p>Occam’s Razor one final time: you do not need a governance framework, a compliance team, a review board, or an audit process. You need a file, a path, and a commit. Everything else is overhead.</p><h3>Why This Matters for Multi-Agent Systems</h3><p>In a single-agent system, the distinction between prompt and behavioral contract is a quality-of-life concern. Your agent is more predictable, more auditable, more governable. Nice to have.</p><p>In a multi-agent system, it is not a concern. It is a survival requirement.</p><p>When your Scarecrow agent calls your Research agent which calls your Cost Model agent which calls your Principal System Architect agent — and one of them starts doing something unexpected — you need to be able to answer four questions instantly:</p><ol><li>What was this agent authorized to do?</li><li>Did its behavior exceed that authorization?</li><li>Who decided on that authorization and when?</li><li>What is the governance path for changing it?</li></ol><p>Without behavioral contracts, you cannot answer any of these questions. You have a multi-agent system the way a crowd is a system — loosely coupled, emergent behavior, no governance.</p><p>With behavioral contracts, you can answer all four questions by reading the system.md file and the git log. The commit hash is the timestamp. The repository path is the identity. The authorities section is the authorization record. The Architecture Decision Record (ADR) is the change governance path.</p><p>The most sophisticated practitioners in the field have arrived at a version of this pattern independently. They maintain persistent configuration files that accumulate corrections over time — every mistake the agent makes gets encoded as a rule, every session gets smarter than the last. They call it compounding engineering. It is impressive discipline. And it is entirely reactive. Every rule in the file originated from something that went wrong.</p><p>The behavioral contract inverts that sequence. Governance is not the accumulation of corrections — it is the specification of boundaries before the first session opens. The mistake does not happen. The correction is never needed. The compounding is not of failures fixed — it is of decisions made deliberately, by a Navigator, before the Driver types a single command.</p><p>Reactive correction compounds debt. Proactive governance compounds authority.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1016/1*SCMzOZzGtAmelRzqHiR2mg.png" /><figcaption><em>Straw burns. Sticks splinter. Brick holds — not because it has more rules, but because it has structure.</em></figcaption></figure><p>Consider the three little pigs — not as a children’s story but as a stress test. The first pig built with straw. Fast. Cheap. Done before lunch. The wolf came and it collapsed. The second pig built with sticks. More careful. More rules. More time. The wolf came and it collapsed too. The third pig built with brick. It took longer. It required deliberate design. It required knowing, before the first brick was laid, exactly what the structure needed to withstand. The wolf came. The house stood. Not because the wolf was weaker. Because the material was structural — not advisory.</p><p>Most agentic systems are built with straw. The best-maintained ones are built with sticks — carefully, with accumulated corrections, with compounding discipline. The behavioral contract is brick. It does not accumulate corrections. It specifies structure. The wolf is the edge case, the adversarial input, the multi-agent cascade where one agent’s ungoverned output becomes the next agent’s governing assumption. Straw burns. Sticks splinter. Brick holds — not because it has more rules, but because it has structure.</p><p>This is not theoretical. This is the architecture that governs every Navigator/Driver session.</p><h3>The Constitutional Parallel Is Precise</h3><p>I want to be careful here because the word “constitutional” is easy to dismiss as rhetorical flourish. It is not.</p><p>A constitution does four things:</p><ol><li>Defines the identity and purpose of the governed entity</li><li>Enumerates the authorities of each component</li><li>Establishes the limits beyond which no component may act</li><li>Provides a mechanism for amendment — with a higher bar than ordinary decisions</li></ol><p>system.md does all four:</p><ul><li>Identity and Mission sections define who the agent is and what it exists to do</li><li>Authorities section enumerates what tools and actions are permitted</li><li>Constraints are explicit — what the agent does not do is as important as what it does</li><li>Amendment requires a Navigator correction committed as an Architecture Decision Record (ADR) — the same governance bar as any architectural decision</li></ul><p>The prompt does none of these things. The prompt is a letter of instruction. The behavioral contract is the constitution.</p><p>A letter of instruction tells you what to do today. A constitution tells you who you are — and who you cannot become, no matter what anyone tells you.</p><h3>The Three-Layer Governance Stack</h3><p>When you put this together with the methodology, you get a governance stack that has no gaps.</p><pre>┌─────────────────────────────────────────┐<br>│  Layer 1: The Spec                      │<br>│  What must be built. Why.               │<br>│  Navigator authored. Git committed.     │<br>│  Immutable after merge.                 │<br>├─────────────────────────────────────────┤<br>│  Layer 2: The Behavioral Contract       │<br>│  How the agent behaves. What it can     │<br>│  touch. When it stops. What it costs.   │<br>│  system.md - version controlled.        │<br>├─────────────────────────────────────────┤<br>│  Layer 3: The ADR Record                │<br>│  Why any behavioral decision was made.  │<br>│  Every Navigator correction committed   │<br>│  as a formal Architecture Decision      │<br>│  Record - timestamped, traceable,       │<br>│  immutable.                             │<br>└─────────────────────────────────────────┘</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/653/1*Swpz28uYf5f2CsCvjsC0pg.png" /><figcaption><em>Three layers. No gaps. The gap between Layer 1 — The Spec — and Layer 2 — The Behavioral Contract — is where most agentic systems collapse.</em></figcaption></figure><p>The gap that kills most agentic systems is between Layer 1 — The Spec — and Layer 2 — The Behavioral Contract. The organization writes a spec. The developers build an agent. But there is no governing document that connects the spec decision to the agent’s runtime behavior. The spec says “the agent should only access customer data.” The agent accesses whatever it needs to. Nobody is lying. The gap just exists.</p><p>system.md closes the gap. The Authorities section of the behavioral contract is the direct implementation of the spec constraint. The repository path in git is the traceable link between the spec commit and the behavioral contract file. The ADR is the amendment record when the constraint changes.</p><p>No gap. No emergent behavior. No “the AI went off the rails” post-mortems.</p><h3>What True Governance Looks Like in Practice</h3><p>Here is a real question from a real multi-agent session:</p><p>“Was the decision to use Gemini for extraction and Claude for synthesis a design decision or an operational convenience?”</p><p>Without governance: nobody knows. It works, so nobody asks. Until it does not work — then nobody can explain why it was designed this way.</p><p>With the behavioral contract and the ADR record:</p><p>system.md — Cost Model section — from a real Navigator/Driver session:</p><pre>vendor_strategy: multi-vendor<br>extraction: google/gemini-2.5-flash  # high context, low cost<br>synthesis: anthropic/claude-sonnet   # quality reasoning required</pre><p>ADR-009–2026–03–14:</p><pre>Decision: gemma3:12b for YAML generation (12s vs 23s, better quality)<br>Supersedes: qwen3:8b default<br>Navigator: [Navigator]<br>Commit: a3f7c91</pre><p>The question answers itself. The design decision is in the behavioral contract. The rationale is in the ADR. The timestamp is the git commit. The Navigator is identified.</p><p>That is governance. Not a process. Not a meeting. Not a document that nobody reads. A commit.</p><p>But notice what is not in the Architecture Decision Record. The commit records what was decided. It does not record the session behind the decision — the Pre-Think deliberation, the alternatives considered, the Navigator’s reasoning that took hours to reach and thirty seconds to commit. That context lives somewhere else. Not in git — git is for decisions, not deliberations. In a vault. A living brief that accumulates session by session, Architecture Decision Record by Architecture Decision Record, Pre-Think by Pre-Think.</p><p>The governed system is only as durable as the institutional knowledge behind it. Without that knowledge, you have governance without context. Law without precedent. A constitution with no case history.</p><p>The vault is the architect’s project journal — translated into the language of a governed agentic system.</p><h3>The One Sentence</h3><p>I promised this article would give you the one sentence that makes the concept land.</p><p>Here it is:</p><p><strong>A prompt tells an agent what to do. A behavioral contract tells an agent what it is — and a governed system is one where those two things are the same.</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/636/1*vDAcRbAzacGsy3BrecKIXg.png" /><figcaption><em>A prompt tells an agent what to do. A behavioral contract tells an agent what it is.</em></figcaption></figure><p>When the spec and the behavioral contract are Siamese twins — when the WHY lives in the git history and the HOW lives in system.md and they share the same repository path as their common bloodline — you do not have an AI assistant. You have a governed agent.</p><p>The difference between those two things is the difference between a tool and an architecture.</p><p>Navigator/Driver is not a better way to use AI tools.</p><p>It is a way to build governed systems with AI as the execution layer.</p><p><strong>The spec is the contract. system.md is its constitution. And every commit is a notarized signature.</strong></p><p><em>Peter Heller is the founder of Mind Over Metadata LLC, creator of the D⁴ Domain-Driven Database Design methodology, and the originator of the Navigator/Driver Spec-Driven Development model. He teaches Database Systems and Data Modeling at Queens College CUNY and has 40 years of systems architecture experience.</em></p><p><em>This is Article 3 in the Navigator/Driver series. Article 2: “One Navigator. One AI. Zero Scheduling.” Article 4: “Why Your AI Agent Is Flying Blind” — coming soon.</em></p><p><em>© 2026 Mind Over Metadata LLC. All rights reserved.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4ad5505320ff" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[One Navigator. One AI. Zero Scheduling.]]></title>
            <link>https://medium.com/@peter.heller/one-navigator-one-ai-zero-scheduling-2a4219630ed9?source=rss-23637872e95b------2</link>
            <guid isPermaLink="false">https://medium.com/p/2a4219630ed9</guid>
            <category><![CDATA[productivity]]></category>
            <category><![CDATA[agile]]></category>
            <category><![CDATA[software-engineering]]></category>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[technology]]></category>
            <dc:creator><![CDATA[Peter Heller]]></dc:creator>
            <pubDate>Tue, 24 Mar 2026 23:07:16 GMT</pubDate>
            <atom:updated>2026-03-24T23:07:16.241Z</atom:updated>
            <content:encoded><![CDATA[<p><em>How a single domain expert and an artificial intelligence (AI) Driver replaced an eight-person workshop — and delivered better artifacts in a single day.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*MtGHJNRD8mLxRtHEy4HTQA.png" /></figure><p>International Business Machines (IBM) invented Joint Application Development (JAD) in the late 1970s to solve a problem every software project still has today: business people and technical people cannot agree on what to build.</p><p>JAD put them in the same room for days. The Navigator/Driver model puts one person in both chairs at once — and delivers better artifacts in hours.</p><h3>What JAD Was Actually Solving</h3><p>Before JAD, requirements gathering was a telephone game played in slow motion.</p><p>A business analyst would interview a stakeholder. Write up what they heard. Hand it to Information Technology (IT). IT would build something based on their interpretation of the write-up. The stakeholder would see the result and say that is not what they meant. Back to the beginning. Repeat for six months before a single line of production code was written.</p><p>IBM’s insight in the late 1970s was simple but radical: stop doing the interviews sequentially and do them all at once. Put everyone in the same room — the Facilitator who guides the discussion, the Scribe who records every decision in real-time, the Executive Sponsor who holds the vision and the budget, the Subject Matter Experts (SMEs) who know the business, and the IT Representatives who know what is technically feasible. Run a structured workshop for two or three days. Emerge with a single agreed artifact that everyone helped build and therefore everyone owns.</p><p>JAD works. Fifty years of evidence confirms it. The methodology is still taught in business analysis programs and practiced in enterprise software development because the core insight never expires: when the people who need the system and the people who build the system design it together, the result is better and faster than any sequential process.</p><p>But JAD has always carried a tax. Eight people in a room means eight calendars to align. It means a facilitator who may be neutral but is never omniscient. It means a scribe who captures most of what is said but not all of it, and whose notes require a week of cleanup before they become usable artifacts. It means consensus negotiation between people with different priorities, different vocabularies, and different definitions of done.</p><p>The coordination overhead was never the point of JAD. It was always the price you paid for the collaboration.</p><p>Navigator/Driver eliminates the price while keeping the point.</p><h3>The Role Map</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*vNHrTb5x5uoqIZJZh2fy8Q.png" /></figure><p>The Navigator/Driver model describes a human Navigator who sets the direction and an AI Driver who executes it. That framing positions it as a pair programming technique — useful for writing code, designing systems, and drafting specifications.</p><p>What a recent full-day session revealed is that the model is doing something more fundamental. It is running a JAD session. With two participants playing all seven roles — and adding an eighth that traditional JAD never had.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/946/1*aKd9aIYEwCJlfT83R_onuw.png" /></figure><p>The key structural difference from traditional JAD is the Facilitator role. In JAD, the Facilitator is deliberately neutral. They guide but do not decide. They manage the conversation between people who disagree.</p><p>In Navigator/Driver, the Navigator IS the decision-maker. There is no political coordination overhead. No competing agendas. No consensus negotiation between stakeholders who want different things. The Navigator decides. The Driver captures. The artifact is produced. The only negotiation that happens is between the Navigator’s domain knowledge and the Driver’s technical proposals — and that negotiation produces better architecture, not slower decisions.</p><p>The eighth role has no equivalent in traditional JAD because traditional JAD could not produce it. Every session starts cold — a new room, a new whiteboard, notes that will take a week to clean up. Navigator/Driver sessions start with everything. Every prior decision is in the Obsidian vault, cross-linked and searchable. Every correction from every prior session is an ADR the Driver can reference. The knowledge does not reset. It compounds.</p><h3>What IBM Did Not Anticipate</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*QFlaq6wVWI4aM2j1IKjVzQ.png" /></figure><p>IBM’s JAD methodology was built on four assumptions that made the coordination overhead unavoidable in 1977. Navigator/Driver eliminates all four.</p><p><strong>Assumption one: business and IT speak different languages.</strong></p><p>Traditional JAD needs a Facilitator to translate between stakeholders who think in business outcomes and developers who think in technical implementations. The Facilitator’s job is to prevent each side from talking past the other.</p><p>Before JAD — and honestly, throughout JAD’s fifty-year history — organizations quietly relied on a person who was never formally named. If business spoke blue and IT spoke red, this was the purple person. Not a Facilitator. Not a business analyst. Not a developer. Someone who existed natively in both registers simultaneously — who could hear a business requirement and immediately see its technical expression, and vice versa. Bi-directional, not sequential. Every organization that ran successful projects had one. Most could not explain why the projects worked when that person was in the room and failed when they were not.</p><p>JAD institutionalized the need for that person but could not manufacture them. The methodology assumed the Facilitator could approximate purple. Most could not.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*x2KCywo7qQOS76zVjR0wDg.png" /></figure><p>In Navigator/Driver, the Navigator IS the purple person — not by rare talent or fortunate circumstance, but by design. The model requires it. The domain expert who runs these sessions has forty years of systems architecture experience alongside deep business knowledge in energy billing, database governance, and curriculum design. When the discussion moves from a business concept to its technical expression, no translation is needed. The Navigator holds both simultaneously and the Driver mirrors that back in formal specifications. The purple person is no longer a dependency. They are the methodology.</p><p><strong>Assumption two: requirements get lost between interviews.</strong></p><p>Traditional JAD invented the single-forum model because sequential interviews produced fragmented, inconsistent requirements. Each interview added signal but also introduced drift from the previous conversation.</p><p>In Navigator/Driver, the Driver holds the complete context of every prior session. Not just from today. From every conversation in the relationship. When a decision made three months ago becomes relevant to today’s architecture discussion, it surfaces immediately. The Driver remembers what the Scribe from last month forgot. Signal loss approaches zero.</p><p><strong>Assumption three: co-location is required.</strong></p><p>Traditional JAD needs everyone in the same physical room because the real-time negotiation between business and technical perspectives requires immediate back-and-forth. You cannot do that by email.</p><p>In Navigator/Driver, async works as well as synchronous. The session happens when the Navigator is ready to think deeply — not when eight calendars can align at the same conference room. The quality of the output is a function of the Navigator’s domain clarity, not the participants’ physical proximity.</p><p><strong>Assumption four: documentation lags the session.</strong></p><p>In traditional JAD, the Scribe captures decisions in real-time as notes and sketches. Those notes require cleanup, organization, and review before they become usable artifacts. The finalization step typically takes a week after the workshop ends.</p><p>In Navigator/Driver, the artifacts are produced within the session. Not after it. Not by a separate step. The Architectural Decision Records (ADRs), the specification documents, the product backlog updates — they emerge from the conversation itself as it happens. When the session ends, the deliverables are already complete.</p><h3>The Evidence</h3><p>One day. One Navigator. One AI Driver.</p><p>Here is what a single Navigator/Driver Joint Application Development session produced:</p><ul><li><strong>73 Product Backlog Items (PBIs)</strong> defined, prioritized, and sprint-scheduled</li><li><strong>15 Architectural Decision Records (ADRs)</strong> locked for a complete system specification</li><li><strong>3 production-ready documents</strong>: a 595-line architecture spec, a full business glossary for an energy data domain covering 7 fuel pillars, and an updated product backlog</li><li>A complete transfer of a proprietary data governance methodology from the Navigator’s knowledge to a formally documented, reproducible architecture</li><li><strong>Zero follow-up meetings needed</strong></li></ul><p>A traditional JAD session producing equivalent outputs would have required eight or more participants, two to three days of workshops, one week of artifact finalization, multiple review cycles, and sign-off meetings.</p><p>One day. Two participants — one human, one AI. Artifacts complete before the session ended.</p><p>Every artifact produced in that session lives in the Navigator’s Obsidian knowledge graph — permanently cross-linked, available to every future session, compounding in value with each Navigator/Driver JAD session that follows. The notes are not a record of the thinking. They are the thinking, immortalized.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*4lgykaBJMp6anGOmyHx4Yg.png" /></figure><h3>The 12 Corrections — Why Quality Is Navigator-Driven</h3><p>This is the most important part of the article because it directly addresses the objection that is already forming in your mind: if the artificial intelligence is doing the work, how do you know the output reflects the domain expert’s judgment and not the AI’s defaults?</p><p>The answer is the corrections.</p><p>During that single day, the session produced twelve corrections. Eleven came from the Navigator catching Driver errors. One came from the Navigator catching a Navigator error through reflection. Every correction was substantive. None were trivial. Here they are:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/954/1*pPonrrk0CfY2-y7IrOBd3Q.png" /></figure><p>Each of these corrections came from forty years of domain knowledge that the AI did not have and could not have generated without the Navigator’s input. Each correction became a formal Architectural Decision Record. Each ADR made the final artifact better than any AI-only output could have been.</p><p>The Driver proposed. The Navigator decided. The artifacts reflect the Navigator’s judgment — not the Driver’s defaults.</p><p>This is the Joint Application Development process working exactly as designed. The Facilitator corrects the direction. The Scribe captures the correction. The artifact is better for it. The only difference is that in Navigator/Driver, the Facilitator and the Scribe are not two separate people requiring coordination. They are two roles in a single session with no coordination overhead between them.</p><p>If the Navigator never corrects the Driver, the Driver is not proposing enough. The corrections are the quality mechanism. Silence is not consensus. It is missed opportunity.</p><p>The Navigator chose the Driver. The Navigator set the scope. The Navigator reviewed every output. Every artifact that emerges from a Navigator/Driver session is the Navigator’s artifact — unequivocally, without qualification, and without exception.</p><h3>The Four JAD Benefits — Scored</h3><p>IBM identified four core benefits of Joint Application Development. Here is how Navigator/Driver scores against each:</p><p><strong>Speed.</strong> Traditional JAD consolidates months of sequential interviews into days of structured workshop. Navigator/Driver consolidates days of structured workshop into hours of directed session. The session described above produced the equivalent of a multi-day JAD workshop in a single day. Advantage: Navigator/Driver.</p><p><strong>Accuracy.</strong> Traditional JAD reduces misunderstandings by having business and technical teams in the same conversation. Navigator/Driver eliminates misunderstandings because every correction becomes a permanent Architectural Decision Record with the Navigator’s exact intent formalized in writing before the session moves forward. A misunderstanding that goes undocumented in traditional JAD can resurface in implementation. In Navigator/Driver, it cannot — the correction IS the documentation. Advantage: Navigator/Driver.</p><p><strong>Shared ownership.</strong> Traditional JAD produces ownership because stakeholders helped design the solution. When you built it, you defend it. Navigator/Driver produces ownership because the Navigator IS the stakeholder — there is no one else. One hundred percent of the architectural decisions belong to the domain expert who made them. Equivalent result, different mechanism.</p><p><strong>Quality.</strong> Traditional JAD catches errors early through collaboration. Navigator/Driver catches errors earlier still — the Driver surfaces gaps and proposes structures before the Navigator has committed to them, enabling correction before artifacts are finalized rather than after they are reviewed. Advantage: Navigator/Driver.</p><p>On three of four dimensions, Navigator/Driver exceeds traditional JAD. On shared ownership, it achieves the same result by a more direct path.</p><h3>The Methodology Lineage</h3><p>Every major advance in software development methodology has addressed the same underlying problem: how do you capture what the domain expert knows and translate it into a buildable artifact without losing fidelity in the translation?</p><p>IBM’s Joint Application Development (JAD, 1977) answered by putting everyone in the same room. Stanford’s Design Thinking (1980s) answered by making the end-user central to every phase. Agile and Scrum (2001) answered by shortening the feedback loop between building and validating. Spec-Driven Development (SDD, 2024) answered by making the specification the artifact that the AI implements rather than interprets.</p><p>Navigator/Driver JAD (2026) answers by eliminating the need for a room at all. The domain expert is already in every chair. The translation happens in real-time. The artifacts emerge from the session itself. Amazon’s KIRO (2026) arrived at the same architectural conclusion from a completely different direction — a spec file as the behavioral contract governing agent execution. Two organizations. No coordination. Identical architecture. That convergence is not coincidence. It is the methodology proving itself.</p><p>Each iteration preserved the core insight of its predecessor while eliminating the coordination overhead that made it expensive.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*qHLkWf2TXA6lexXAYvDNCA.png" /></figure><p>Each iteration preserved the core insight of its predecessor while eliminating the coordination overhead that made it expensive.</p><h3>How to Run a Navigator/Driver JAD Session</h3><p>The Navigator comes with domain knowledge and a clear scope. Not a formal agenda — the scope IS the agenda. The clearer the Navigator’s mental model of the problem, the faster the session produces useful output.</p><p>The Driver comes with context from prior sessions and a disposition toward proposing rather than waiting. The Driver’s job is not to take dictation. It is to propose structures, patterns, and architectures that the Navigator can evaluate, correct, and approve.</p><p>The process:</p><ol><li>Navigator states the problem or scope</li><li>Driver proposes a structure or solution</li><li>Navigator corrects, refines, or approves</li><li>Driver captures the decision formally — as an Architectural Decision Record (ADR), a Product Backlog Item (PBI), or a specification section</li><li>Repeat until the artifact is complete</li></ol><p>The output is every decision documented, every artifact produced within the session, every correction an architectural improvement. No follow-up meetings. No finalization step. No sign-off review. The session IS the deliverable.</p><p>One rule worth remembering: if the Navigator has not corrected the Driver in a while, ask a harder question. The corrections are not a sign that something is wrong. They are the signal that the process is working.</p><h3>What Happens When the Team Scales</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*VcNGcQDIAO2zAx6x1zmlEg.png" /></figure><p>The Navigator/Driver model was designed for the solo practitioner. One Navigator. One AI Driver. One session. Artifacts complete.</p><p>But the hierarchy scales naturally — and when it does, it unifies Joint Application Development (JAD), Scrum, and Spec-Driven Development (SDD) under a single governance model.</p><p><strong>Three levels:</strong></p><p>At the top sits the Master Navigator. This is the domain expert who owns the original specification — the constitutional document that governs all derivative work. The Master Navigator is analogous to the Product Owner in Scrum, but with a critical difference: the Master Navigator is also the Chief Architect. They do not just define what to build. They define how it must be built, governed, and documented. Their specification is the single source of truth.</p><p>One level down sits the Senior Navigator. This role is the spec’s guardian — analogous to a Scrum Master combined with a Technical Lead. The Senior Navigator does not facilitate process. They enforce specification conformance. Every Domain Navigator submits artifacts for the Senior Navigator’s review. Every commit is evaluated against the Master Specification. The Senior Navigator’s merge approval IS the formal acceptance record. Not a verbal sign-off. Not a ticket status. The commit hash, timestamped and immutable, proves that the artifact conforms to the spec. Permanently. Auditably. Without a separate governance document.</p><p>At the execution level sit the Domain Navigators. Each owns a subdomain of the Master Specification. Each runs their own JAD sessions with AI Drivers. Each produces Architectural Decision Records (ADRs) and Product Backlog Items (PBIs) that roll up to the Master Backlog. The AI Driver at each level produces artifacts. The Navigator at each level corrects them. The corrections are the quality mechanism at every level of the hierarchy.</p><p>Every Navigator/Driver session at every level operates in Pre-Think Mode — the mandatory conceptualization phase that precedes all implementation. Pre-Think is not a separate meeting. It is the JAD session itself. The Navigator’s intent is resolved, formalized as a specification, and committed to the spec repo before any Driver-only tool — Claude Code, Codex, Fabric — touches implementation. When a Domain Navigator hands a spec to a Driver-only tool, that tool does not deliberate. It does not infer architecture. It does not guess at domain rules. Those decisions are already committed. Every token the Driver spends goes toward execution. None goes toward figuring out what to build.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*HMpgCkarebYctIoaBoOeZg.png" /></figure><p><strong>What this means:</strong></p><p>In traditional organizations these three functions are separate disciplines with separate tools, separate meetings, and separate overhead. Requirements gathering (JAD) hands off to sprint planning (Scrum) which hands off to governance review (Architecture Board). Each handoff is a coordination tax.</p><p>In the Navigator/Driver hierarchy, all three happen within the same governance model. The Master Navigator’s specification IS the requirements document AND the architectural standard AND the governance framework. The JAD session IS the sprint planning. The commit IS the acceptance record. Nothing is separate. Nothing is handed off. Nothing is lost in translation.</p><p>The Master Navigator writes the specification once. Every Navigator below interprets it for their domain. Every Driver implements against it. Every commit proves conformance to it.</p><p>IBM gave us the forum. Schwaber and Sutherland gave us the sprint. Spec-Driven Development gives us the specification that governs both — at every level, at every scale, without changing the underlying mechanism.</p><h3>The Reinvention</h3><p>IBM gave us Joint Application Development to bring business and IT together. It worked. For fifty years it has worked.</p><p>But the coordination overhead was always the tax. Eight people in a room. Eight calendars to align. One week to finalize what one day produced.</p><p>Navigator/Driver does not eliminate JAD. It eliminates the coordination overhead that made JAD expensive.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Pyz9qpGlpLn6cnlSRg-hyg.png" /><figcaption>Navigator\Driver does not eliminate JAD. It eliminates the coordination overhoad that made JAD expensive.</figcaption></figure><p>One domain expert playing five roles. One AI playing three roles. The artifacts of an eight-person workshop produced in a single day. The twelve corrections that traditional JAD would have surfaced in review meetings — surfaced instead in the session itself, immediately, permanently, at the moment when changing course costs nothing.</p><p>IBM would recognize the methodology. They might not recognize the participants.</p><p>But the insight is the same one they published in 1977: the people who need the system and the people who build the system should design it together.</p><p>We just finally have a way to make that one person.</p><p>The artifacts do not merely survive the session. They enter a governance architecture where every decision is committed, every correction is immutable, and every acceptance is proven by a merge — not declared by a meeting.</p><p><em>Have you run a JAD session with an AI Driver? What did the Navigator correct? The corrections are the data. Share them in the comments.</em></p><p><em>Peter Heller is the founder of Mind Over Metadata LLC, creator of the D⁴ Domain-Driven Database Design methodology, and a Database Systems Instructor at Queens College, City University of New York (CUNY). He writes about the Navigator/Driver model, Spec-Driven Development (SDD), and agentic AI systems at mindovermetadata.com.</em></p><p><em>This article is part of the Navigator + Driver series. Read the original: “The Navigator and the Driver: A New Model for AI Pair Programming.”</em></p><p><em>© 2026 Mind Over Metadata LLC</em></p><p><strong>Tags:</strong> #AIProductivity #SoftwareDevelopment #AgileMethodology #ArtificialIntelligence #TechLeadership #JAD #NavigatorDriver #SpecDrivenDevelopment</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2a4219630ed9" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The Navigator and the Driver: A New Model for AI Pair Programming]]></title>
            <link>https://medium.com/@peter.heller/the-navigator-and-the-driver-a-new-model-for-ai-pair-programming-28ad5b0ab215?source=rss-23637872e95b------2</link>
            <guid isPermaLink="false">https://medium.com/p/28ad5b0ab215</guid>
            <category><![CDATA[artificial-intelligence]]></category>
            <category><![CDATA[technology]]></category>
            <category><![CDATA[data-engineering]]></category>
            <category><![CDATA[python]]></category>
            <dc:creator><![CDATA[Peter Heller]]></dc:creator>
            <pubDate>Fri, 20 Feb 2026 22:46:48 GMT</pubDate>
            <atom:updated>2026-02-20T22:46:48.225Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/625/1*rFpXqUHonaTzJRle6o2CLQ.png" /><figcaption>The Navigator and the Driver — a Socratic dialogue between domain expertise and AI capability, with the Canonical Spec as the shared contract.</figcaption></figure><h3>How domain expertise in Analysis and Architecture transforms iterative prompt engineering into a legitimate design methodology</h3><p>What Does a Senior Developer Look Like in 2027?</p><p>Not a faster coder. That’s the Navigator.</p><p>Anthropic’s <a href="https://resources.anthropic.com/2026-agentic-coding-trends-report">2026 Agentic Coding Trends Report</a> confirms the gap: engineers use AI in roughly 60% of their work but report being able to fully delegate only 0–20% of tasks — the space between those numbers is where the Navigator operates.</p><p>Over four design sessions in February 2026, I tested this proposition by pairing with Claude Opus 4.6 — Anthropic’s most advanced model — in what I’m calling SDD (Spec-Driven Development). What emerged wasn’t planned. It was a complete framework: project management with CPM (Critical Path Method) scheduling, a universal deployment architecture spanning six AI tools — all governed by a single canonical artifact, the system.md — and a token-cost-transparent pipeline system — all through disciplined iteration.</p><p>This article documents that process. It is a work in progress, shared as findings from an active research effort.</p><p>Video 1: The Title Slide Walkthrough</p><p><a href="https://app.screencast.com/nccSvxl2COxzW">📹 Watch: Spec-Driven Development — Title &amp; Context</a></p><p>This screencast walks through the foundational framing: what SDD is, the four-session lineage (Feb 4, 8, 10, and 11, 2026), and the subtitle — “From Conversational Discovery to Executable Architecture” — which captures the entire arc. You start with a conversation and end with a deployable, machine-readable architecture. Not a document about architecture. The architecture itself.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*jwjW3ZQbpQQypvxzYVe_TQ.png" /><figcaption>Three pillars of Spec-Driven Development: People Navigate, AI Drives, Conversation = Docs.</figcaption></figure><ol><li>People Navigate. The Navigator doesn’t say “write a for-loop that iterates over tasks.” The Navigator says “I need a project management framework that supports CPM, Scrum, and Kanban without changing the underlying data structure.” That’s a 40-year sentence — it carries decades of pattern recognition about what works and what doesn’t at enterprise scale.</li><li>AI Drives. Not descriptions of what we could build. Not PowerPoint slides about the approach. Working JSON (JavaScript Object Notation) specs, React visualizers, deployment scripts, Word documents. Tangible, testable deliverables in seconds.</li><li><strong>Conversation = Docs.</strong> The most radical claim. The conversation transcript IS the requirements documentation. No separate requirements gathering phase that produces a document that then gets interpreted by developers. This eliminates the telephone game — where business requirements get distorted through layers of translation before they reach implementation. The artifact that emerges from this conversation is the system.md — a single behavioral contract that governs how every AI tool in the architecture behaves.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_mATRiXBKcaWgACr4eBRvg.png" /><figcaption>The five-step iterative cycle — a Directed Cyclic Graph that loops until the Navigator signals satisfaction.</figcaption></figure><ol><li>The Navigator states a need — often incompletely. “How do I create a project similar to MS Project for Claude Code agentically?” That’s ambiguous. It’s exactly enough to start.</li><li>The Driver proposes a working artifact, not a description of one. An actual Gantt chart with CPM scheduling — something you can look at, challenge, and correct. Every iteration produces something tangible.</li><li>The Navigator challenges. Not checking for typos — identifying structural errors, missing abstractions, conflated concepts, and architectural gaps that the Driver doesn’t have the domain experience to see.</li><li>The Driver corrects and deepens. The correction often surfaces adjacent problems. Fix the milestone conflation, and suddenly resource allocation is missing too. The Driver rebuilds and frequently exposes the next gap in the same pass.</li><li>Repeat until the Navigator signals satisfaction. There’s no fixed number of iterations. Some concepts crystallize in two passes. The DAG (Directed Acyclic Graph) vs. DCG distinction took multiple rounds across sessions.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*_mATRiXBKcaWgACr4eBRvg.png" /><figcaption>One precise Navigator correction — ‘A milestone is the aggregation of contingent tasks’ — and the Driver propagates it through the entire architecture.</figcaption></figure><p>The Navigator doesn’t need to specify every detail. One precise correction, and the Driver propagates it through the entire architecture. That’s the power of the cycle.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ivc7FpA_uy7JsUVlaURTJw.png" /><figcaption>Seven versions, seven breakthroughs — each triggered by a Navigator question, none planned in advance.</figcaption></figure><p>Every breakthrough came from domain expertise, not AI capability. The Driver could build anything — but it couldn’t know what needed building.</p><ol><li>v1 — Spec-Driven Gantt + CPM (<strong>Critical Path Method</strong>). “How do I create a project similar to MS Project?” The seed question that launched the entire architecture.</li><li>v2 — Hierarchical WBS. “A milestone is the aggregation of contingent tasks.” Forced the rebuild from flat list to a hierarchical WBS (<strong>Work Breakdown Structure)</strong>.</li><li>v3 — DAG vs. DCG Classification. “What is missing is the DCG.” Project schedules must be DAGs (<strong>Directed Acyclic Graphs</strong> — no cycles, no deadlock). Execution engines may be DCGs (<strong>Directed Cyclic Graphs</strong> — intentional cycles with exit conditions). Conflating them is a design error. This was the session’s most architecturally significant insight.</li><li>v4 — Methodology Layer. “How does Scrum evolve into this agentically?” Demanded multi-methodology support — CPM, Scrum, and Kanban — without changing the underlying data structure.</li><li>v5 — Elicitation as First-Class Phase. “How does elicitation fit into the tasks?” Revealed that requirements (<strong>Elicitation</strong>) gathering was invisible in the spec. Now it’s a tracked phase with its own deliverables.</li><li>v6 — UML Use Case Diagrams &amp; Specifications + Obsidian Knowledge Graph. “How do UML Use Case Diagrams &amp; Specifications plus Obsidian figure in?” This connected formal UML (Unified Modeling Language) discipline — use case diagrams for actor-system interactions, use case specifications with main flows, alternate flows, and exception handling — with modern knowledge management tooling.</li><li>v7 — Canonical Spec + Wrappers. “Is SKILL.md a euphemism for system.md?” Cut through naming confusion to establish tool-agnostic canonical artifacts — one behavioral</li><li>contract, multiple delivery adapters.</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*evhIswPkPsEeCVpo8d7Hew.png" /><figcaption>One canonical spec (left), one governance contract unlocking every tool (center), one Navigator at the helm (right).</figcaption></figure><p>This is not traditional pair programming where both people code and swap roles. These roles are asymmetric and non-interchangeable.</p><p>The Navigator defines the destination — not the route. “I need CPM, Scrum, and Kanban support without changing the data structure.” Every breakthrough in the seven-version evolution was triggered by a Navigator question that exposed a gap. The Navigator holds domain expertise and final architectural authority. The Driver proposes; the Navigator disposes.</p><p>The Driver — Claude Opus 4.6 — produces working artifacts in real time. Not descriptions. Not plans. JSON specs, React visualizers, deployment scripts, Word documents. When the Navigator says “a milestone is the aggregation of contingent tasks,” the Driver doesn’t file a ticket. It rebuilds the entire WBS in the same conversational turn — and surfaces adjacent issues unprompted.</p><p>Opus 4.6 holds the full architectural context across a multi-hour session — every prior decision, every constraint, every correction. The choice of model is part of the architecture.</p><p>Potential energy is stored capacity — decades of pattern recognition waiting to be released. Kinetic energy is motion — translating an insight into a working artifact in seconds. Potential without kinetic is unrealized expertise. Kinetic without potential is motion without direction. The pair needs both. Neither role produces the result alone.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*JEwnYEovb1UqZd-vlHB9eQ.png" /><figcaption>Video 2: One Canonical Spec, Deploy Everywhere</figcaption></figure><p><a href="https://app.screencast.com/FHz08WfmQoOcn">📹 Watch: One Canonical Spec — Deployment Architecture</a></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*tD-HV7gouHSkNs_Y9HkvtA.jpeg" /><figcaption>Gertrude Stein wrote, a rose is a rose is a rose — they’re all the same thing: a system.md.</figcaption></figure><p>Every AI tool has its own name for the same thing. Fabric calls it a “pattern.” Claude Code calls it a “SKILL.md.” Codex calls it an “AGENTS.md.” Gemini calls it a “GEMINI.md.” But as Gertrude Stein wrote, a rose is a rose is a rose — they’re all the same thing: a system.md.</p><p>A system.md is a behavioral contract that tells an LLM (Large Language Model) how to morph into a specific skill. Each system.md follows SRP (Single Responsibility Principle): one skill, one contract, one responsibility. The tool name changes. The behavioral contract doesn’t.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*2Z-ylBQC5e3UtWhYlVsHhw.png" /><figcaption>Six tools, six bridge files, one behavioral contract. The FQSN filesystem path IS the identifier.</figcaption></figure><p>SRP (Single Responsibility Principle) applied to prompt engineering: one behavioral contract, multiple delivery adapters. The system.md defines what a skill does. Bridge files adapt it for each tool’s runtime.</p><p>Walk through the table:</p><ul><li>Fabric — symlink layer (Go codebase expects flat directory names)</li><li>Claude Code — SKILL.md with YAML frontmatter</li><li>Codex CLI — AGENTS.md</li><li>Gemini CLI — GEMINI.md with import directives that reference system.md directly</li><li>OpenAI API — system.md content straight into the JSON messages array</li><li>Workbench — copy-paste from the canonical spec</li></ul><p>Six tools. Six bridge files. One behavioral contract. Change it once, every tool gets the update.</p><p>The identifier system mirrors D⁴ (Domain-Driven Database Design) metadata architecture:</p><p>FQSN (<strong>Fully Qualified Skill Name</strong>) follows a nested taxonomy where position in the hierarchy IS the identity:</p><ul><li>CodingArchitecture/BackupAutomation/system.md — the filesystem path IS the identifier</li><li>No lookup table needed — the filesystem IS the registry • Impact analysis becomes a filesystem operation: ls CodingArchitecture/Security/ answers “what security skills exist?” without querying a database</li><li>Fabric’s Go codebase expects flat directory names and cannot navigate the hierarchy directly, so a symlink bridges the nested taxonomy into Fabric’s flat namespace without duplicating the canonical spec</li><li>The hierarchy is the source of truth. The flat structure is derived</li></ul><p>This is FQDN (Fully Qualified Domain Name) thinking — a core principle of D⁴ — applied to AI tool governance.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*CEwcsNCBQz18yWpZNkBYIQ.png" /><figcaption>JSON for storage, TOON for transport — a 58% token reduction without changing the canonical spec.</figcaption></figure><p>TOON (<strong>Token-Optimized Object Notation</strong>) sits between JSON and CSV (<strong>Comma-Separated Values</strong>) — human-readable, but optimized for LLM (<strong>Large Language Model</strong>) context windows. The same data costs ~92 tokens in JSON and ~38 tokens in TOON — a 58% reduction.</p><p>The architectural decision: JSON for storage, TOON for transport. JSON remains the canonical format on disk — source of truth, version-controlled, schema-validated by Pydantic v2 (<strong>Python data validation library</strong>). When that spec enters an LLM context window, a TOON transformer compresses it. The LLM reasons over TOON but outputs standard JSON patches. Round-trip stays clean.</p><p>The flow: project.json → TOON transform → LLM reasons → JSON patches → project.json.</p><p>KISS (<strong>Keep It Simple and Standard</strong>) guidance: build in full JSON first. Add TOON only when context window pressure becomes a real bottleneck.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*GHGy3VOp0kjPp2EmE1pMXA.png" /><figcaption>Six nodes, two LLM calls, four zero-cost nodes. Two-thirds of this pipeline runs at zero marginal cost.</figcaption></figure><p>Most AI frameworks don’t talk about cost. They show you the pipeline, they show you the output — then you get the invoice. This slide makes cost structure transparent at the architecture level.</p><p>The command line at the top is real — not pseudocode. pbpaste | fabric -m qwen3-coder-next:cloud -p extract_article_wisdom | pandoc -o OllamaCloud.docx. That’s Fabric (Daniel Miessler’s open-source AI prompt pattern framework) stitching syntax — Fabric’s term for chaining patterns via Unix pipes.</p><p>Walk through the six nodes:</p><ul><li>Node 1 — yt-dlp extract (Shell, zero tokens): Pulls a YouTube transcript locally</li><li>Node 2 — extract_wisdom (Fabric, LLM tokens): Processes content through an LLM</li><li>Node 3 — detect_mermaid (Python, zero tokens): Checks for diagram blocks, routes conditionally</li><li>Node 4 — render_markdown (Fabric, LLM tokens): Formats output into styled Markdown</li><li>Node 5 — mmdc render (Shell, zero tokens): Renders Mermaid diagrams to images</li><li>Node 6 — pandoc output (Shell, zero tokens): Produces the final document</li></ul><p>The summary cards make the math undeniable: 6 total nodes, 2 LLM calls (Fabric only), 4 zero-cost nodes (Python + Shell), 0 MCP (Model Context Protocol) overhead — subprocess calls, not API roundtrips. Two-thirds of this pipeline runs at zero marginal cost.</p><p>The principle: LangGraph (<strong>LangChain’s stateful agent workflow framework</strong>) state transitions are zero tokens — state is a Python dict passed between nodes in memory, not an LLM call. Only Fabric/Claude/Gemini nodes cost tokens. When someone asks “how much does this pipeline cost?” you can answer precisely.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/883/1*oVYu5bfC7DofTvnoCqgr-A.png" /><figcaption>In Spec-Driven Development, the Navigator role requires domain expertise in Analysis and Architecture; the Driver is Claude Opus 4.6.</figcaption></figure><p>There’s a deeper architectural pattern at work here — one that connects this work to a 20-year evolution in the Architecture.</p><p>The problem: how do you enforce consistent data definitions across an enterprise?</p><p>D⁴ (<strong>Domain-Driven Database Design</strong>) is the architecture that emerged from that question. It is metadata modeling, not data modeling. D⁴ centers on the FQDN (<strong>Fully Qualified Domain Name</strong>) — a canonical taxonomy where the BGD (<strong>Business Glossary Domain</strong>) is an integral aspect and <strong><em>the fully qualified path </em>IS <em>the governance contract</em></strong>.</p><p>The BGD drives the FQDN bi-directionally in business semantics — all stakeholders can understand the architecture because the naming is the business language. Governance travels with the artifact, not separate from it — and inherently evolves as the design changes.</p><p>FinancialInstruments.InstrumentName is not just an identifier. It carries:</p><ol><li>Its domain categorization</li><li>Its datatype for the specific target engine</li><li>Its fully qualified named default which is used for replacing nulls with this conventional value for unknowns</li><li>Its fully qualified named check constraints enforcing two value predicate logic eliminating the unknown (null) values which leverages the default value which included within the constraint (column, table, and database level)</li><li>Standardized enterprise data typing that is baked into the metadata taxonomy and data governance</li></ol><p>Define it once in the taxonomy. Every target database in the enterprise derives from that same FQDN — one canonical definition with a one-to-many relationship to all targets.</p><p>What changes per target? Only the equivalent Unicode datatype dialect:</p><ol><li>nvarchar in T-SQL</li><li>varchar in PostgreSQL</li><li>varchar2 in Oracle</li></ol><p>The governance is identical. Only the dialect changes. SRP (Single Responsibility Principle), KISS, and reuse — scaling horizontally across the enterprise without redesign.</p><p>The SDD framework follows the identical pattern:</p><ol><li>The canonical system.md is the hub — the FQDN of the AI agent world</li><li>Every tool (Fabric, Claude Code, Codex, Gemini) is a spoke — deriving behavior from the same canonical source</li><li>Bridge files are the thinnest possible adapter layer — a symlink for Fabric, YAML frontmatter for Claude Code, an import directive for Gemini</li><li>Add a seventh tool tomorrow — it gets a bridge file. The governance scales without redesign</li></ol><p>One canonical spec, one-to-many targets. Same pattern. Same architecture. Databases to AI agents.</p><p>A follow-up Medium.com article will draw the full connection between enterprise data governance and AI agent governance.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/625/1*rFpXqUHonaTzJRle6o2CLQ.png" /><figcaption>The conversation IS the architecture — Socratic method meets AI capability, with the Canonical Spec as the bridge between 20 years of database governance and the future of AI agent design.</figcaption></figure><p>The most important takeaway from these four sessions is not any single artifact. It is that conversation itself — conducted with discipline, domain expertise, and the iterative rigor of the Navigator + Driver model — is a legitimate design methodology.</p><p>On February 4, 2026, the seed question was simple and incomplete: “<strong><em>How do I create a project similar to MS Project for Claude Code?</em></strong>” Nine days and four sessions later, the conversation had produced hierarchical project management with CPM scheduling, a universal deployment architecture spanning six AI tools, FQSN identifiers mirroring 20 years of D⁴ FQDN governance, and a token-cost-transparent pipeline system. None of it was planned. All of it was navigated.</p><p>The iterative cycle — state a need, propose a solution, challenge, correct and deepen, repeat — is not new. Socrates practiced it. What is new is pairing that cycle with an AI Driver that can translate each iteration into working artifacts in real time. Potential energy meets kinetic energy. The Navigator carries decades of architectural instinct. The Driver provides the activation energy. Neither role produces the result alone.</p><p>This is a work in progress. The methodology is evolving. But the pattern is clear: the future of software development belongs to the practitioners who can navigate — and the conversations that become the architecture.</p><p>Guiding principles: <br>· SRP (Single Responsibility Principle) <br>· KISS (Keep It Simple and Standard) <br>· D⁴ (Domain-Driven Database Design) <br>· FQSN (Fully Qualified Skill Name): <strong><em>Path</em></strong> <strong>IS</strong> <strong><em>the identifier</em></strong></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=28ad5b0ab215" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[PostgreSQL 17 Enhanced Code with UUIDv7 and Security Functions for an Enterprise Architecture]]></title>
            <link>https://medium.com/@peter.heller/postgresql-17-enhanced-code-with-uuid7-and-security-functions-for-an-enterprise-architecture-8413be325837?source=rss-23637872e95b------2</link>
            <guid isPermaLink="false">https://medium.com/p/8413be325837</guid>
            <category><![CDATA[generative-ai-tools]]></category>
            <category><![CDATA[python]]></category>
            <category><![CDATA[postgresql]]></category>
            <category><![CDATA[architecture]]></category>
            <category><![CDATA[metadata]]></category>
            <dc:creator><![CDATA[Peter Heller]]></dc:creator>
            <pubDate>Fri, 04 Apr 2025 10:44:56 GMT</pubDate>
            <atom:updated>2025-04-04T18:44:41.209Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/771/1*xVgxM_5zFlFEZhlx7UVCbg.png" /></figure><h3>Introduction</h3><p>As an educator in Database Systems, I am expanding my curriculum to incorporate PostgreSQL alongside existing content. My current focus involves migrating SQL Server 2022 databases to PostgreSQL through an innovative AI-assisted pair programming approach. In this methodology, I serve as the navigator while various Large Language Models (LLMs) function as the driver — a process I’ve termed Machine Teaching (MT). This approach employs iterative prompt engineering and aligns with NACE Competencies, benefiting both my teaching methods and student collaborative work.</p><p>Based on the reception of this work, I plan to follow with a “Comprehensive Guide to Domain-Based Data Modeling.” This upcoming article will explore fully qualified objects, particularly domains, within a taxonomy founded on SOLID Design Principles and the DRY (Don’t Repeat Yourself) principle.</p><p>This current article presents enhanced PostgreSQL 17.4 implementations, featuring a robust schema design that incorporates UUIDv7 identifiers and sequence ID obfuscation. The architecture showcases enterprise-level database design best practices which supersede vendor-specific limitations on style. For example, while my preference is PascalCase, PostgreSQL prefers snake_case. The solution is to double-quote objects, allowing the architecture to maintain enterprise-level database design best practices. This approach demonstrates standardized patterns that remain effective across heterogeneous environments while transcending vendor-specific suggestions of their tools style.</p><p>Thank you for your attention to this work.</p><h3>Key Design Elements</h3><p><strong>The schema utilizes a dual-key approach:</strong></p><ul><li>Public Primary Keys: UUIDv7-based identifiers (16 bytes) that provide globally unique, privacy-preserving values safe for external exposure</li><li>Private Sequence Objects: Integer-based internal identifiers optimized for physical storage and query performance</li></ul><p>This architecture delivers significant performance benefits while maintaining security and scalability requirements for enterprise applications.</p><h3>Enhanced Code Implementation</h3><h4>Extensions and Schema Setup</h4><pre>-- Extensions<br>CREATE EXTENSION IF NOT EXISTS &quot;uuid-ossp&quot;;  <br>CREATE EXTENSION IF NOT EXISTS pg_uuidv7; <br>CREATE EXTENSION IF NOT EXISTS pgcrypto; <br> <br>-- Create custom schemas if they don&#39;t exist<br>CREATE SCHEMA IF NOT EXISTS &quot;Sales&quot;; <br>CREATE SCHEMA IF NOT EXISTS &quot;PkSequence&quot;; <br>CREATE SCHEMA IF NOT EXISTS &quot;sdSurrogateKey&quot;; <br>CREATE SCHEMA IF NOT EXISTS &quot;sdSysTime&quot;; <br> <br>-- Create custom types<br>CREATE DOMAIN &quot;sdSurrogateKey&quot;.&quot;UUIDv7&quot; AS UUID; <br>CREATE DOMAIN &quot;sdSurrogateKey&quot;.&quot;SequenceObjectInt&quot; AS INTEGER; <br>CREATE DOMAIN &quot;sdSysTime&quot;.&quot;AuditTriggerTimestamp&quot; AS TIMESTAMP WITH TIME ZONE; </pre><h4>Sequence and Table Definitions</h4><pre>-- Create sequences<br>CREATE SEQUENCE &quot;PkSequence&quot;.&quot;OrderPrivateSequenceObjectId&quot; START 1000; <br>CREATE SEQUENCE &quot;PkSequence&quot;.&quot;OrderDetailPrivateSequenceObjectId&quot; START 2000; <br> <br>-- Create Order table<br>CREATE TABLE &quot;Sales&quot;.&quot;Order&quot; ( <br>    &quot;OrderUUID7&quot; &quot;sdSurrogateKey&quot;.&quot;UUIDv7&quot; DEFAULT <br>        uuid_generate_v7(CURRENT_TIMESTAMP) PRIMARY KEY, <br>    &quot;OrderPrivateSequenceObjectId&quot; &quot;sdSurrogateKey&quot;.&quot;SequenceObjectInt&quot; DEFAULT <br>        nextval(&#39;&quot;PkSequence&quot;.&quot;OrderPrivateSequenceObjectId&quot;&#39;), <br>    &quot;Data&quot; VARCHAR(255), <br>    &quot;DateAdded&quot; &quot;sdSysTime&quot;.&quot;AuditTriggerTimestamp&quot; DEFAULT CURRENT_TIMESTAMP, <br>    &quot;DateOfLastUpdate&quot; &quot;sdSysTime&quot;.&quot;AuditTriggerTimestamp&quot; DEFAULT <br>        CURRENT_TIMESTAMP <br>); <br> <br>-- Create unique index for Order<br>CREATE UNIQUE INDEX idx_uifd_sales_order_pky  <br>    ON &quot;Sales&quot;.&quot;Order&quot; (&quot;OrderUUIDv7&quot;, &quot;OrderPrivateSequenceObjectId&quot;); <br> <br>-- Create clustered index for Order (using CLUSTER command in PostgreSQL)<br>CREATE INDEX idx_clustered_sales_order_sequenceobject  <br>    ON &quot;Sales&quot;.&quot;Order&quot; USING btree (&quot;OrderPrivateSequenceObjectId&quot;); <br> <br>-- Make the table clustered on the index <br>CLUSTER &quot;Sales&quot;.&quot;Order&quot; USING idx_clustered_sales_order_sequenceobject; <br> <br>-- Create OrderDetail table<br>CREATE TABLE &quot;Sales&quot;.&quot;OrderDetail&quot; ( <br>    &quot;OrderUUIDv7&quot; &quot;sdSurrogateKey&quot;.&quot;UUIDv7&quot;, <br>    &quot;OrderDetailUUIDv7&quot; &quot;sdSurrogateKey&quot;.&quot;UUIDv7&quot; DEFAULT <br>        uuid_generate_v7(), -- Is generated by the CURRENT_TIMESTAMP <br>    &quot;OrderDetailPrivateSequenceObjectId&quot; &quot;sdSurrogateKey&quot;.&quot;SequenceObjectInt&quot; <br>        DEFAULT nextval(&#39;&quot;PkSequence&quot;.&quot;OrderDetailPrivateSequenceObjectId&quot;&#39;), <br>    &quot;Data&quot; VARCHAR(255), <br>    &quot;DateAdded&quot; &quot;sdSysTime&quot;.&quot;AuditTriggerTimestamp&quot; DEFAULT CURRENT_TIMESTAMP, <br>    &quot;DateOfLastUpdate&quot; &quot;sdSysTime&quot;.&quot;AuditTriggerTimestamp&quot; DEFAULT <br>        CURRENT_TIMESTAMP, <br>    CONSTRAINT PK_OrderDetail PRIMARY KEY (&quot;OrderUUIDv7&quot;, &quot;OrderDetailUUIDv7&quot;), <br>    CONSTRAINT FK_OrderDetail_Order FOREIGN KEY (&quot;OrderUUID7&quot;) REFERENCES <br>        &quot;Sales&quot;.&quot;Order&quot; (&quot;OrderUUIDv7&quot;) <br>); <br> <br>-- Create unique index for OrderDetail<br>CREATE UNIQUE INDEX idx_uifd_sales_orderdetail_pky  <br>    ON &quot;Sales&quot;.&quot;OrderDetail&quot; (&quot;OrderUUIDv7&quot;, &quot;OrderDetailUUIDv7&quot;, <br>        &quot;OrderDetailPrivateSequenceObjectId&quot;); <br> <br>-- Create clustered index for OrderDetail<br>CREATE INDEX idx_clustered_sales_orderdetail_sequenceobject  <br>    ON &quot;Sales&quot;.&quot;OrderDetail&quot; USING btree (&quot;OrderDetailPrivateSequenceObjectId&quot;); <br> <br>-- Make the table clustered on the index <br>CLUSTER &quot;Sales&quot;.&quot;OrderDetail&quot; USING <br>    idx_clustered_sales_orderdetail_sequenceobject; </pre><h3>Security Functions for Sequence Obfuscation</h3><pre>-- Create schema for security functions<br>CREATE SCHEMA IF NOT EXISTS &quot;Security&quot;; <br> <br>-- Functions for sequences under 2 billion rows (INTEGER) <br> <br>-- MD5 encryption for INTEGER<br>CREATE OR REPLACE FUNCTION &quot;Security&quot;.encrypt_sequence_md5<br>                                             (seq_id INTEGER, secret_key TEXT) <br>RETURNS TEXT AS $$ <br>BEGIN <br>    RETURN encode(hmac(seq_id::text, secret_key, &#39;md5&#39;), &#39;hex&#39;); <br>END; <br>$$ LANGUAGE plpgsql SECURITY DEFINER; <br> <br>-- MD5 validation for sequence tokens<br>CREATE OR REPLACE FUNCTION &quot;Security&quot;.validate_sequence_md5<br>                                 (seq_id INTEGER, token TEXT, secret_key TEXT) <br>RETURNS BOOLEAN AS $$ <br>BEGIN <br>    RETURN token = encode(hmac(seq_id::text, secret_key, &#39;md5&#39;), &#39;hex&#39;); <br>END; <br>$$ LANGUAGE plpgsql SECURITY DEFINER; <br> <br>-- SHA-256 encryption for INTEGER<br>CREATE OR REPLACE FUNCTION &quot;Security&quot;.encrypt_sequence_sha256<br>                                             (seq_id INTEGER, secret_key TEXT) <br>RETURNS TEXT AS $$ <br>BEGIN <br>    RETURN encode(hmac(seq_id::text, secret_key, &#39;sha256&#39;), &#39;hex&#39;); <br>END; <br>$$ LANGUAGE plpgsql SECURITY DEFINER; <br> <br>-- SHA-256 validation for INTEGER<br>CREATE OR REPLACE FUNCTION &quot;Security&quot;.validate_sequence_sha256(seq_id INTEGER, token TEXT, secret_key TEXT) <br>RETURNS BOOLEAN AS $$ <br>BEGIN <br>    RETURN token = encode(hmac(seq_id::text, secret_key, &#39;sha256&#39;), &#39;hex&#39;); <br>END; <br>$$ LANGUAGE plpgsql SECURITY DEFINER; <br> <br>-- Functions for sequences over 2 billion rows (BIGINT) <br> <br>-- MD5 encryption for BIGINT<br>CREATE OR REPLACE FUNCTION &quot;Security&quot;.encrypt_sequence_bigint_md5<br>                                              (seq_id BIGINT, secret_key TEXT) <br>RETURNS TEXT AS $$ <br>BEGIN <br>    RETURN encode(hmac(seq_id::text, secret_key, &#39;md5&#39;), &#39;hex&#39;); <br>END; <br>$$ LANGUAGE plpgsql SECURITY DEFINER; <br> <br>-- MD5 validation for BIGINT<br>CREATE OR REPLACE FUNCTION &quot;Security&quot;.validate_sequence_bigint_md5<br>                                (seq_id BIGINT, token TEXT, secret_key TEXT) <br>RETURNS BOOLEAN AS $$ <br>BEGIN <br>    RETURN token = encode(hmac(seq_id::text, secret_key, &#39;md5&#39;), &#39;hex&#39;); <br>END; <br>$$ LANGUAGE plpgsql SECURITY DEFINER; <br> <br>-- SHA-256 encryption for BIGINT<br>CREATE OR REPLACE FUNCTION &quot;Security&quot;.encrypt_sequence_bigint_sha256<br>                                              (seq_id BIGINT, secret_key TEXT) <br>RETURNS TEXT AS $$ <br>BEGIN <br>    RETURN encode(hmac(seq_id::text, secret_key, &#39;sha256&#39;), &#39;hex&#39;); <br>END; <br>$$ LANGUAGE plpgsql SECURITY DEFINER; <br> <br>-- SHA-256 validation for BIGINT<br>CREATE OR REPLACE FUNCTION &quot;Security&quot;.validate_sequence_bigint_sha256<br>                                  (seq_id BIGINT, token TEXT, secret_key TEXT) <br>RETURNS BOOLEAN AS $$ <br>BEGIN <br>    RETURN token = encode(hmac(seq_id::text, secret_key, &#39;sha256&#39;), &#39;hex&#39;); <br>END; <br>$$ LANGUAGE plpgsql SECURITY DEFINER; </pre><h3>Timestamp Synchronization</h3><p>For the timestamp fields (DateAdded and DateOfLastUpdate), we&#39;re using CURRENT_TIMESTAMP instead of explicitly extracting the timestamp from the UUID7. <br> This is simpler, but if you want exact synchronization with the UUID7 timestamp, you could create a trigger:</p><pre>CREATE OR REPLACE FUNCTION sync_timestamps_from_uuidv7()<br>RETURNS TRIGGER AS $$<br>BEGIN<br>    NEW.&quot;DateAdded&quot; = uuid_v7_to_timestamp(NEW.&quot;OrderDetailUUIDv7&quot;);<br>    NEW.&quot;DateOfLastUpdate&quot; = uuid_v7_to_timestamp(NEW.&quot;OrderDetailUUIDv7&quot;);<br>    RETURN NEW;<br>END;<br>$$ LANGUAGE plpgsql;<br><br>CREATE TRIGGER trg_sync_timestamps_from_uuidv7<br>BEFORE INSERT ON &quot;Sales&quot;.&quot;OrderDetail&quot;<br>FOR EACH ROW EXECUTE FUNCTION sync_timestamps_from_uuidv7();</pre><h3>Index Design and Dependencies</h3><h4>Unique Index Structure</h4><p>The unique indexes enforce specific relationships:</p><h4>idx_uifd_sales_order_pky:</h4><p>Ensures that each combination of OrderUUIDv7 and OrderPrivateSequenceObjectId is unique within the Order table, maintaining data integrity by preventing duplicate entries.</p><h4>idx_clustered_sales_order_sequenceobject:</h4><p>Creates a physical ordering of data based on the integer sequence, dramatically improving range query performance.</p><h4>idx_uifd_sales_orderdetail_pky: Enforces hierarchical uniqueness across three columns:</h4><ul><li>OrderUUIDv7: Links to the parent order</li><li>OrderDetailUUIDv7: Provides unique identification within the order</li><li>OrderDetailPrivateSequenceObjectId: Offers efficient physical ordering</li></ul><p>The composite key design for OrderDetail is particularly efficient as it maintains referential integrity while providing optimized physical storage patterns for common query patterns. Child rows for a specific order are physically contiguous, enabling efficient disk I/O operations.</p><h3>Performance Advantages of Sequence Objects</h3><h4>Enhanced Physical Storage Efficiency:</h4><ul><li>OrderPrivateSequenceObjectId uses only 4 bytes (INTEGER) compared to 16 bytes for UUIDv7</li><li>Tables are clustered on sequence IDs, physically organizing data for faster sequential access</li><li>This organization reduces I/O operations during range scans and indexed lookups</li></ul><h4>Query Performance Optimization:</h4><ul><li>Integer-based comparisons are computationally more efficient than UUID comparisons</li><li>B-tree indexes on sequence IDs are smaller, requiring fewer page reads</li><li>Range scans on sequence-ordered data can utilize sequential disk access patterns</li></ul><h4>Particularly Efficient for Complex Relationships:</h4><ul><li>In the “Sales”.”OrderDetail” table, the sequence object provides an optimized physical ordering mechanism</li><li>Child records can be efficiently located using the parent-child relationship with minimal I/O</li><li>Composite operations can be completed with fewer disk reads and better cache utilization</li></ul><h3>Practical Application Example</h3><h4>When retrieving all order details for a specific order:</h4><pre>-- Using UUIDv7 only (less efficient):<br>SELECT * FROM &quot;Sales&quot;.&quot;OrderDetail&quot; <br>WHERE &quot;OrderUUIDv7&quot; = &#39;01890a3c-5211-7c10-9a25-0242ac120002&#39;;<br><br>-- Using sequence object with clustered index (more efficient):<br>SELECT * FROM &quot;Sales&quot;.&quot;OrderDetail&quot; <br>WHERE &quot;OrderUUIDv7&quot; = &#39;01890a3c-5211-7c10-9a25-0242ac120002&#39;<br>ORDER BY &quot;OrderDetailPrivateSequenceObjectId&quot;;</pre><p>The second query leverages the clustered index on OrderDetailPrivateSequenceObjectId, reading physically contiguous data blocks and reducing random I/O operations, especially important for larger datasets.</p><h3>Sequence Obfuscation Implementation</h3><h4>To use sequence obfuscation in a dropdown box scenario:</h4><pre>-- When loading data for the dropdown, encrypt the sequence ID:<br>SELECT  <br>    &quot;Data&quot;, <br>    &quot;Security&quot;.encrypt_sequence_sha256<br>           (&quot;OrderPrivateSequenceObjectId&quot;, &#39;your-secret-key&#39;) AS encrypted_id <br>FROM &quot;Sales&quot;.&quot;Order&quot;; <br><br>-- When receiving the form submission, validate the encrypted value:<br>SELECT * FROM &quot;Sales&quot;.&quot;Order&quot;  <br>WHERE &quot;OrderPrivateSequenceObjectId&quot; = some_id  <br>  AND &quot;Security&quot;.validate_sequence_sha256<br>                      (some_id, &#39;received_encrypted_token&#39;, &#39;your-secret-key&#39;);</pre><h3>This approach provides several advantages:</h3><ul><li>Actual sequence values remain hidden from the UI</li><li>Applications can still utilize efficient sequence IDs internally</li><li>Eliminates the need for separate views that exclude sequence columns</li><li>Functions use SECURITY DEFINER to run with creator privileges, adding another security layer</li></ul><h3>Conclusion</h3><p>This enhanced PostgreSQL implementation offers a sophisticated approach to database design, balancing performance needs with security requirements. The dual-key architecture utilizing UUID7 for public identifiers and sequence objects for efficient physical ordering delivers the best of both worlds: globally unique, secure identifiers for external use alongside optimized internal storage structures that maximize database performance.</p><p>By implementing clustered indexes on sequence objects, the database can maintain optimal physical storage layouts that significantly enhance query performance in high-volume scenarios, particularly for parent-child relationships as demonstrated in the Order and OrderDetail tables.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=8413be325837" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Standardizing Date Manipulation in Python vs SQL-A Guide to Enhanced Data Handling]]></title>
            <link>https://medium.com/@peter.heller/standardizing-date-manipulation-in-python-vs-sql-a-guide-to-enhanced-data-handling-6ba434cce792?source=rss-23637872e95b------2</link>
            <guid isPermaLink="false">https://medium.com/p/6ba434cce792</guid>
            <dc:creator><![CDATA[Peter Heller]]></dc:creator>
            <pubDate>Tue, 20 Feb 2024 12:37:31 GMT</pubDate>
            <atom:updated>2024-02-22T00:48:33.312Z</atom:updated>
            <content:encoded><![CDATA[<h4>In the article, the goal was to mimic T-SQL scalar functions in Python, utilizing Enums and Dictionaries for enhanced functionality. Enums improve code clarity and ensure type safety by limiting values to predefined options, reducing errors, such as in date format handling. Dictionaries offer quick data access and, when combined with MappingProxyType, provide immutable data structures that maintain integrity and prevent accidental modifications. This approach not only streamlines data management but also bolsters the reliability and maintainability of the code.</h4><h4>Enums, Dictionaries and Immutability</h4><blockquote>Dictionaries Enhance Data Retrieval: They offer efficient key-based access, ideal for handling large sets of values or configurations.</blockquote><blockquote>Immutability with MappingProxyType: Wrapping dictionaries in MappingProxyType maintains data integrity, safeguarding program logic and preventing unintended side effects.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/462/1*d1mGUPIIaGYt1YM5Z9WlBQ.png" /><figcaption><a href="https://app.screencast.com/XiA5hXGGJFbiI">Link to Standardizing Date Manipulation -Enums &amp; Dict</a></figcaption></figure><p>Summary: Dictionaries are pivotal for efficient key-based data retrieval, particularly useful in managing large datasets or configurations. The use of MappingProxyType to wrap dictionaries ensures their immutability, preserving the integrity of data structures and protecting the program’s logic from unintended modifications.</p><blockquote>Versatile Date Handling Function: `parse_using_date_strptime_format` adeptly manages various date formats and separators, enhancing its utility for parsing dates from multiple sources with predefined formats. The documentation thoroughly outlines the function’s objectives, parameters, return values, and offers an in-depth explanation of the code on a line-by-line basis.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/754/1*bPWXrwAGvbhpCjjEiskPVg.png" /><figcaption><a href="https://app.screencast.com/v6unFBtb8Nvep">Link to parse_using_date_strptime_format video</a></figcaption></figure><pre>def parse_using_date_strptime_format(strp_time: StrpTime, date_separator: DateSeparator, orderdate:str) -&gt; tuple[int, int, int]:<br>    &quot;&quot;&quot;<br>    This function parses a date string (`orderdate`) using a specified format and separator, returning the month, day, and year as a tuple of integers.<br>    <br>    Args:<br>        strp_time (StrpTime):  An enumeration that specifies the format to be used for parsing the date string.<br>        date_separator (DateSeparator): An enumeration that specifies the separator used in the date string (e.g., &quot;-&quot;, &quot;/&quot;, or none).<br>        orderdate (str): The date string to be parsed.<br><br>    Returns:<br>        tuple[int, int, int]: `tuple[int, int, int]`: A tuple containing the month, day, and year extracted from the `orderdate` string.<br>    &quot;&quot;&quot;<br>    # Access the separator based on the `date_separator` enum name<br>    separator = _date_separation[date_separator.name]<br><br>    # Retrieve the date format information based on the `strp_time` enum name<br>    date_format_info = _all_date_formats[strp_time.name]<br>    <br>    # Choose the appropriate date format template based on whether a separator is used<br>    date_strptime_template = date_format_info[&#39;DATE_FORMAT_NONE&#39;] if date_separator.name == &#39;none&#39; else date_format_info[&#39;DATE_FORMAT_SEPARATOR&#39;]<br>    <br>    # Retrieve the number of separators expected in the date format<br>    number_of_separators = date_format_info[&#39;NUMBER_OF_SEPARATORS&#39;]<br><br>    # Format the date string template with the appropriate number of separators<br>    if number_of_separators == 2:<br>        # If two separators are expected, format the template with two separators<br>        date_strptime_paramterized_format = date_strptime_template.format(separator, separator)<br>    elif number_of_separators == 1:<br>    # If one separator is expected, format the template with one separator<br>        date_strptime_paramterized_format = date_strptime_template.format(separator)<br>    else:<br>    # If no separators are expected, use the template as is<br>        date_strptime_paramterized_format = date_strptime_template<br>        <br>    # Parse the `orderdate` string using the parameterized date format<br>    parsed_date = datetime.strptime(orderdate, date_strptime_paramterized_format)<br>    <br>    # Return the month, day, and year as a tuple of integers FOR unpacking into DateTime object signature is (year, month, day)<br>    return  parsed_date.year,parsed_date.month, parsed_date.day<br># Example of using the `parse_using_date_strptime_format` function<br>yyyy,mm,dd = parse_using_date_strptime_format(StrpTime.yyyymmdd, DateSeparator.slash, &#39;2021/12/31&#39;)<br>print(mm,dd,yyyy)<br><br># Output: 12 31 2021</pre><h4><strong>Date Difference Calculation Function</strong></h4><blockquote>This Python code defines a function named `datediff` that calculates the difference between two dates in various units such as years, months, days, etc. The function is designed to be flexible, allowing for different formats of date parts and date strings.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/960/1*r1fNbLOTHHBvms2YZxHF2w.png" /><figcaption><a href="https://app.screencast.com/jj52oPGJEhFak">Link to `datediff` function video</a></figcaption></figure><pre>from datetime import datetime<br>from dateutil.relativedelta import relativedelta<br><br>def datediff(date_part: DatePartUnit, strp_time: StrpTime, date_separator: DateSeparator, orderdate: str, deliverydate: str) -&gt; int:<br>    &quot;&quot;&quot;_Function to calculate the difference between two dates based on the date_part<br><br>    Args:<br>         date_part (str):<br>                            YY : Year, year, y, yy, or yyyy<br>                            QU : Quarter, quarter, qq, q<br>                            MO : Month, month, mm, m<br>                            Day: dayofyear, day, dd, d<br>                            WK : Week, week, wk, ww<br>                            HR : Hour, hour, hh<br>                            MI : Minute, minute, mi, n<br>                            SS : Second, second, ss, s<br><br>        orderdate (str):    is the starting date for the date difference<br>        deliverydate (str): is the ending date for the date difference<br><br>    Returns:<br>                       int: The date difference between the two dates <br>                       <br>    &quot;&quot;&quot;<br>    # Parse the &#39;orderdate&#39; and &#39;deliverydate&#39; strings using the specified format and separator,<br>    # and return the corresponding &#39;datetime&#39; objects for the start and end dates.<br>    start_date = datetime(*parse_using_date_strptime_format(strp_time, date_separator, orderdate))<br>    end_date =datetime(*parse_using_date_strptime_format(strp_time, date_separator, deliverydate))<br>    <br>    delta = relativedelta(end_date, start_date)<br><br>    date_part_units = {<br>        &#39;YY&#39;: lambda: delta.years,<br>        &#39;QU&#39;: lambda: (delta.years * 4) + (delta.months // 3),<br>        &#39;MO&#39;: lambda: (delta.years * 12) + delta.months,<br>        &#39;DD&#39;: lambda: (end_date - start_date).days,<br>        &#39;WK&#39;: lambda: ((end_date - start_date).days // 7),<br>        &#39;HR&#39;: lambda: ((end_date - start_date).total_seconds() // 3600),<br>        &#39;MI&#39;: lambda: ((end_date - start_date).total_seconds() // 60),<br>        &#39;SS&#39;: lambda: (end_date - start_date).total_seconds()<br>    }<br><br>    return date_part_units.get(date_part.name, lambda: None)()<br>       <br># Example of using the `datediff` function     <br>derive_the_number_units = datediff(DatePartUnit.QU, StrpTime.mmddyy,DateSeparator.slash,&#39;7/22/92&#39;, &#39;7/22/97&#39;)<br>print(f&quot;derive_the_number_units  {derive_the_number_units} and DatePartUnit {DatePartUnit.QU.name}&quot;)<br><br># Output: derive_the_number_units  20 and DatePartUnit QU</pre><h4>The dateadd function in Python is designed to calculate and return a new date by adding a specified number of time units: years, months, days, weeks, hours, minutes, and seconds—to a given start date.</h4><figure><img alt="" src="https://cdn-images-1.medium.com/max/846/1*k-Kr26pgpVus8YFM5qnceA.png" /><figcaption><a href="https://app.screencast.com/0p5AlEwW0Pges">Link to </a><a href="https://app.screencast.com/0p5AlEwW0Pges">dateadd function video</a></figcaption></figure><pre>from datetime import datetime,date<br>from dateutil.relativedelta import relativedelta<br><br>def dateadd(strp_time: StrpTime, date_separator: DateSeparator,date_part: DatePartUnit,  units_number: int, orderdate: str) -&gt; datetime:<br>    &quot;&quot;&quot;<br>    Function to calculate the units_number to a date based upon the date_part<br>    Args:<br>        date_part (str):    YY, QU, MO, Day, WK, HR, MI, SS<br>                            YY : Year, year, y, yy, or yyyy<br>                            QU : Quarter, quarter, qq, q<br>                            MO : Month, month, mm, m<br>                            Day: dayofyear, day, dd, d<br>                            WK : Week, week, wk, ww<br>                            HR : Hour, hour, hh<br>                            MI : Minute, minute, mi, n<br>                            SS : Second, second, ss, s<br><br>        units_number (int): Number of units to add<br>        orderdate (str): Starting date in &#39;M/D/YYYY&#39; or &#39;M/D/YY&#39; format<br><br>    Returns:<br>        datetime: New date after adding the specified units<br>    &quot;&quot;&quot;<br>    year, month, day = parse_using_date_strptime_format(strp_time, date_separator, orderdate)<br>    start_date = datetime(year, month, day)<br>        <br>    date_part_units = {<br>        &#39;YY&#39;: lambda: start_date + relativedelta(years=units_number),<br>        &#39;QU&#39;: lambda: start_date + relativedelta(months=units_number * 3),<br>        &#39;MO&#39;: lambda: start_date + relativedelta(months=units_number),<br>        &#39;DD&#39;: lambda: start_date + relativedelta(days=units_number),<br>        &#39;WK&#39;: lambda: start_date + relativedelta(weeks=units_number),<br>        &#39;HR&#39;: lambda: start_date + relativedelta(hours=units_number),<br>        &#39;MI&#39;: lambda: start_date + relativedelta(minutes=units_number),<br>        &#39;SS&#39;: lambda: start_date + relativedelta(seconds=units_number),<br>    }<br><br>    return date_part_units.get(date_part.name, lambda: None)()<br><br># Example of using the `dateadd` function<br>derived_date = dateadd(StrpTime.yyyymmdd, DateSeparator.none,DatePartUnit.YY,25,&#39;20000101&#39;)<br>print(f&#39;{derived_date}&#39;)<br><br># Output: 2025-01-01 00:00:00</pre><blockquote>This functionality allows for versatile date calculations across a wide range of time units, making it a useful tool for handling date and time manipulations in various applications.</blockquote><h4>The determine_quarter_and_year function in Python, which calculates the fiscal or calendar year (limited to QuarterAnchorMonth.January) and the quarter for a specified date.</h4><blockquote>It utilizes custom types such as QuarterAnchorMonth, StrpTime, and Date Separator, along with a global dictionary named QUARTER_ANCHOR_MONTH, to execute its calculations. This function is designed to provide a structured approach to identifying the fiscal or calendar quarter and year based on the input date, leveraging predefined types and a dictionary for accurate determination.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*FNYDhNQ-VwpUSyRyS1fgOw.png" /><figcaption><a href="https://app.screencast.com/kyvA2l9CaQpiU">Link to def determine_quarter_and_year function video</a></figcaption></figure><pre>from datetime import datetime<br><br>def determine_quarter_and_year(quarter_anchor_month:QuarterAnchorMonth, strp_time: StrpTime, date_separator: DateSeparator, orderdate:str) -&gt; str:<br>    <br>    year, month, day = parse_using_date_strptime_format(strp_time, date_separator, orderdate)<br>    <br>    quarter_data_tuples = QUARTER_ANCHOR_MONTH[quarter_anchor_month.name][&#39;determine_quarter_tuple&#39;]<br><br>    determined_quarter_string = &quot;FY{}: Quarter {}&quot; if quarter_anchor_month.value &gt; 1 else &quot;CY{}: Quarter {}&quot;<br>    year_plus_one = year + 1 if 1 &lt; month &lt; 13 else year<br>    <br>    # Finding the quarter number for the given month using the quarter_data_tuples WITH the next function and a generator expression<br>    quarter_number = next((quarter for start_month,middle_month, end_month, quarter in quarter_data_tuples if month in [start_month,middle_month, end_month]), None)<br>    <br>    if quarter_number is None : return f&quot;No quarter for month {month}&quot; <br>    <br>    return determined_quarter_string.format(year_plus_one,quarter_number)<br><br># # Example of using the `determine_quarter_and_year` function<br># Test the function with different dates<br>print(determine_quarter_and_year(QuarterAnchorMonth.July, StrpTime.yyyymmdd, DateSeparator.hyphen, &#39;2024-02-16&#39;))<br>print(determine_quarter_and_year(QuarterAnchorMonth.July, StrpTime.yyyymmdd, DateSeparator.hyphen, &#39;2024-05-28&#39;))<br>print(determine_quarter_and_year(QuarterAnchorMonth.July , StrpTime.yyyymmdd, DateSeparator.hyphen, &#39;2024-08-28&#39;))<br>print(determine_quarter_and_year(QuarterAnchorMonth.July, StrpTime.yyyymmdd, DateSeparator.hyphen, &#39;2024-11-28&#39;))</pre><h4>The documentation details the convert_input_date_to_new_format function, aimed at converting dates from one format to another with a focus on flexibility and error minimization.</h4><blockquote>It employs Enums to denote both input and output date formats and separators, offering a robust method for date format conversion. Additionally, the Date Format Conversion Utility is introduced, comprising two primary functions that also utilize Python Enums for defining input and output formats and separators, reinforcing the utility’s capability to efficiently manage date conversions across various formats.</blockquote><blockquote>Converting dates between different formats and separators.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/955/1*hpLbvJW9RC4d-DbF6slrJw.png" /><figcaption><a href="https://app.screencast.com/l1vZTHXQhNZkT">Link to Date Conversion Function Documentation video</a></figcaption></figure><blockquote>The documentation and utility description both outline the functionality of a date conversion system, specifically focusing on the convert_input_date_to_new_format function. This function is crafted to transform dates from one format to another, utilizing Python enums to categorize both the input and output date formats as well as their separators. This method ensures a flexible and robust approach to date format conversion, minimizing errors by clearly defining and managing the formats and separators involved in the conversion process.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*kcn5HUqJ3CGdTUKX_495yw.png" /><figcaption>Code explanation of the use of def get_date_format</figcaption></figure><pre>def get_date_format(strp_time: StrpTime, date_separator: DateSeparator) -&gt; str:<br>    &quot;&quot;&quot;<br>    Determines the date format based on the provided enums.<br><br>    Args:<br>        strp_time (StrpTime): The enum representing the date format.<br>        date_separator (DateSeparator): The enum representing the date separator.<br><br>    Returns:<br>        str: The date format string.<br>    &quot;&quot;&quot;<br>    format_info = _all_date_formats[strp_time.name]<br>    separator = DATE_SEPARATOR[date_separator.name]<br>    number_of_separators = format_info[&#39;NUMBER_OF_SEPARATORS&#39;]<br>    <br>    if number_of_separators == 2:<br>        return format_info[&#39;DATE_FORMAT_SEPARATOR&#39;].format(separator, separator)<br>    elif number_of_separators == 1:<br>        return format_info[&#39;DATE_FORMAT_SEPARATOR&#39;].format(separator)<br>    if date_separator == DateSeparator.none:<br>        return format_info[&#39;DATE_FORMAT_NONE&#39;]<br></pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*iFhCxoUCE0eJZIJ58_xA8Q.png" /><figcaption>Code explanation of the twice reuse of get_date_format in convert_input_date_to_new_format</figcaption></figure><p>The video series showcases how Python and Pandas can integrate SQL-like date handling functionalities, using Enums, Dictionaries, and MappingProxyType to offer a comprehensive and efficient alternative for data manipulation tasks. It highlights Python and Pandas’ strengths in directly importing and exporting various file formats without the need for conversion, unlike SQL. However, it also acknowledges SQL’s superiority in handling large datasets due to the power of database servers. This comparison underlines the importance of versatility in data handling tools, demonstrating both the challenges and advantages of adopting Python for data manipulation, while also emphasizing the seamless integration and expanded capabilities it introduces to Python-based projects.</p><p>I welcome suggestions for enhancements or new features that could improve the integration of SQL and Python for date handling. Your feedback is extremely helpful to refine and broaden the functionality of this comparative methods as a better learning experience for me to be shared.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=6ba434cce792" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>