{"slug": "dual-graph-drift-detection-for-solo-devs-what-happens-when-your-docs-and-your-to", "title": "Dual-Graph Drift Detection for Solo Devs: What Happens When Your Docs and Your Code Start Talking to Each Other", "summary": "A self-taught developer in Taiwan who built an ERP system for their coffee brand with AI assistance has documented a workflow where documentation and code audit each other to catch data drift. The developer created governance artifacts such as governance-guard.mjs and a tech-debt backlog after encountering recurring bugs caused by mismatches between specs and code. The approach includes rules like querying the database first for value-mismatch bugs, and the developer reports that governance awareness emerged during a particularly intense month of development.", "body_md": "I'm a coffee roaster in Taiwan who taught myself to code with AI over the past 8 months. I built a full vertical-integration ERP for my coffee brand — from green bean inventory to roasting orders to e-commerce checkout. Along the way I ran into something nobody on the internet seems to be writing about: a way for the **prose* I've written (docs, specs, governance rules) and thecodeI've shipped to literally audit each other. This is that workflow.*\n\nPeople ask me, *\"When did you start caring about governance?\"*\n\nI can answer with 14-hour precision.\n\n**April 21, 2026, 11:41 AM.** That was the first time I wrote `governance-guard`\n\ninto a prompt to Claude Code:\n\n\"Should we put these 3 audit rules into governance-guard? Yes. Then can you do a targeted scan based on these and report potential errors back to me?\"\n\nLater that afternoon at 15:08, I doubled down:\n\n\"Option B (CI layer): governance-guard adds a rule to scan all relative / alias import paths... fail = block ——> do this.\"\n\n**14 hours later, April 22, 1:12 AM**, I used the word *\"governance\"* for the first time:\n\n\"Should we save all the fixes and rules we discussed as a 'skill', so future projects can reuse them? I'm worried that once my attention returns to MVP launch, all this governance work will be forgotten and turn into hidden risk. I don't know how a solo developer is supposed to allocate this kind of work.\"\n\nIn the same Claude Code session (`70aa7ce0`\n\n), in those 14 hours, three governance artifacts were born:\n\n`governance-guard.mjs`\n\n`TECH-DEBT-BACKLOG.md`\n\n`skill`\n\nfilesThese 14 hours are the precise moment my governance awareness was born. Before this, I asked AI *\"fix this.\"* After this, I asked *\"fix this **+ prevent it from happening again**.\"* The question went from one-dimensional to two-dimensional.\n\n**April 2026 was the most brutal month of my 8 months of development** — I accumulated 348 git commits, the highest single-month count in the project's history.\n\nIt went like this: I'd fix one order bug, fix it, realize the same pattern showed up elsewhere, fix that, fix again, then the first one would break.\n\nThe most dramatic prompt came at 8:39 AM on April 29:\n\n\"I'm dumbfounded. Why is the previous balance showing 0? We've fixed it five or six versions already — go look at git. This should be a really simple problem for you. Why has it taken so many tries?\"\n\nThat wasn't a technical question. **It was the scream of a governance problem.**\n\nThe root cause (which I later turned into one of 14 data-drift debugging records):\n\n| Layer | What was written |\n|---|---|\n`CLAUDE.md` Rule 21 (spec) |\nSSOT — frontend may not override DB truth; `single_price` is the canonical source |\n`single_price` (DB schema) |\nExists |\n`useOrderAggregation.js` (code) |\nUses `product.single_price \\ |\n{% raw %}`Reports.vue` (code) |\nUses a different legacy fallback chain |\n`AdminPOS.vue` (code) |\nRecalculates totals on the frontend |\n\n**The docs said \"single_price is SSOT\", the code used a 5-layer fallback, and the UI was still recalculating.** Fix one location, the other four kept dropping. By the fifth attempt I realized — **I'm not fixing a bug, I'm fixing a governance problem**.\n\nThat prompt became the entire motivation for `CLAUDE.md`\n\nRule 17 Step 0: *\"For value-mismatch bugs, the first step MUST be a SQL query against the DB. Do not guess in code.\"*\n\nLooking back at that month's prompts, I noticed a very consistent pattern in how I asked things. I call it my **governance terminology birth engine**.\n\nThe canonical example (also April 29, 6:03 AM):\n\n\"Help me find all of them. Is there an industry term for this phenomenon? Use it to do a comprehensive search.\"\n\nThe structure is always the same:\n\nEvery governance term in my codebase was born this way — `skill`\n\nfiles, Type A/B/C drift classification, Layer 1-6 defense, SSOT, `governance-guard`\n\n, `TECH-DEBT-BACKLOG`\n\n, \"data-drift debugging records.\" Each name has a prompt like this behind it.\n\n**Converting daily pain into indexable abstract terminology** — that's the seed crystal that governance systems grow around. I didn't suddenly understand governance one day. I had 8 months of AI repeatedly asking me, *\"Does the concept you're describing have a name in your project?\"*\n\nWhat's more interesting — **on the same day, I had two completely opposite attitudes toward AI**.\n\nApril 21, 2:20 AM:\n\n\"Please... synthesize everything you're about to say to me into markdown — but as questions you ask me back, not as answers. Let's go from divergent to convergent.\"\n\nThis is the **soft inquiry mode** — treat AI as Socrates, force me to think through it myself.\n\nSame day, 11:41 AM:\n\n\"Should we put these 3 audit rules into governance-guard? Yes.\"\n\nThis is the **hard blocking mode** — use a CI script to fence AI (and my future self) out of mistakes.\n\nThat's when I realized — **two opposite attitudes on the same day, mapping exactly to the human need for freedom vs. discipline**:\n\nThe greatest discipline of a one-person founder — **knowing when to loosen the reins and when to lock them down**. This dual-attitude toward AI is the most precious methodology I've developed in 8 months.\n\nMy `CLAUDE.md`\n\nhas 26 rules. Rule 21 (\"SSOT Five-Layer Defense\") is the most-cited one. But you should know — **it originally had only 4 layers**.\n\nI can date the exact moment it gained a 6th: **May 2, 2026, 3:14 AM**.\n\nThat day I was fixing a roast-degree display bug — the orders list mixed Chinese and English: \"medium roast\", \"medium\", \"medium_light\", \"medium_dark\". The same field was being handled three different ways across RPC, normalizeOrder, and UI — classic drift.\n\nThe prompt:\n\n\"Should I write this skill and update CLAUDE.md Rule 21 to add Layer 6? Yes, do it. Also, I just noticed — why are some roast degrees in Chinese and some in English? They're clearly not being read from the SSOT.\"\n\nThat was the moment of expansion from 4 to 6 layers. The two new layers:\n\n28 minutes later at 3:42 AM, I asked:\n\n\"Is there a way to do a comprehensive scan that proactively finds where else this kind of problem might occur?\"\n\n**Rules grow in geological layers.** Each layer is a specific frustration that crystallized into a fossil. Layer 5 is the pain of fixing balance_before five times. Layer 6 is the pain of roast degrees being handled three different ways.\n\nIf you see my CLAUDE.md grow a Layer 7 or Layer 8 in the future — **that will absolutely be another specific frustration that forced it out**. Not because I read a \"treasure hunt defense design guide\" first.\n\nStarting that month I did three things:\n\n`governance-guard.mjs`\n\n`CLAUDE.md`\n\nrulesBut it wasn't enough. governance-guard can only scan **known** violations — the ones I've written rules for. **Drifts I haven't written into rules are invisible to it**.\n\nThe deeper problem is — **even rules I've written, I forget**. 6 months ago I wrote Rule 9 (no raw `system_role`\n\ncompare), but in a new Claude session this month, neither I nor the AI remembered.\n\n**GitNexus** is a powerful tool. It turns my codebase into a graph of **23,280 symbols / 45,727 edges** — every function, every call, every import.\n\nAsk it, *\"What's the blast radius of fn_create_order_atomic?\"* — perfect answer, lists which functions break at distance d=1, d=2, d=3.\n\nBut ask it, *\"Is CLAUDE.md Rule 9 (no raw system_role compare) still being respected, 6 months after I wrote it?\"* —\n\nThis is the ceiling of code-graphs — **they can only tell you \"what code is doing now\", not \"how much that has drifted from what I originally intended\"**.\n\n**Graphify** ([covered in detail in T10](https://dev.to/content/graphify-knowledge-graph-from-markdown)) turns my 50+ `.md`\n\nfiles into a graph of **7,230 concept nodes**. It helps me find cross-file surprising connections I never consciously made.\n\nBut ask it, *\"This RPC I designed 2 months ago — did the code actually return the fields I said it would?\"* — **it can't answer**. It only sees docs, not whether code quietly never implemented them.\n\nThis is the ceiling of doc-graphs — **they can only tell you \"what intent I wrote\", not \"whether the code caught up\"**.\n\nThe most honest admission — May 15, 2026 morning, I was fixing a roasting batch display anomaly when I said:\n\n\"This isn't a single-batch problem. This is **systemic data drift. Why didn't the previous root-cause analysis catch this serious failure? **Did graphify and gitnexus both fail to help?\"\n\nThat moment I realized — **graphify can catch \"the same concept appearing similarly in different files\", but it can't catch \"a structural data drift distributed across 5 files as 5 different symptoms\"**. Each file only contains part of the symptom; there's no complete pattern to detect.\n\nThis is why **just chaining two graphs isn't enough** — you need a third layer, `governance-guard`\n\n, which explicitly writes \"symptom patterns\" as rules to enable reverse scanning.\n\nWhile drafting this article, **I just realized my admin UI is missing the \"assign series\" interface**.\n\nMy blog post schema (`content_pages`\n\ntable) **has had series_slug and series_order columns for weeks**. I've manually filled in values for 4 posts (via SQL console direct UPDATE).\n\nBut the admin content management page **has no UI for editing series**. I'd been changing it via SQL the whole time. I literally forgot, \"oh, I never built that UI.\"\n\nThis is a 100% live case of doc-as-spec × code-as-reality drift:\n\n| Layer | State |\n|---|---|\n| DB schema | ✅ `series_slug` + `series_order` exist |\n| DB data | ✅ 4 posts have values (filled manually via SQL) |\n| Admin UI | ❌ No edit field built |\n| Public series cards (frontend) | ❌ Probably also not built |\n\n**If graphify + gitnexus + governance-guard were chained and auto-reconciling**:\n\n`series`\n\nconcept appearing in `.md`\n\n/ spec files`series_slug`\n\n`series_slug`\n\n, but 0 admin UI components reference it\"This would've been blocked the first time. **I wouldn't have only noticed today that \"oh, I never built that UI.\"**\n\nMid-article, I tried re-running `npx gitnexus analyze`\n\nto get the latest numbers. **First attempt failed instantly** — DuckDB's `COPY`\n\ncommand on Windows with a Chinese path tried to encode in `cp950`\n\nand crashed.\n\nMy reaction (with AI's help) was *\"oh, must be UTF-8 issue\"* — ran `chcp 65001 + LC_ALL=UTF-8 + Console.OutputEncoding=UTF8`\n\nthree-layer enforcement. **Still failed**, because DuckDB internal IO looks at Windows system locale, not console codepage.\n\nFinally I checked memory and realized — **I had solved this exact problem 17 days earlier**, using an NTFS junction (`C:\\gn-cssaas`\n\n) to give the project an ASCII-only path.\n\nThe most ironic part — **my graphify-out vault already had a community labeled 183 documenting this**:\n\n`Gitnexus zh-TW cp950 Codepage Failure → chcp 65001 + LC_ALL UTF-8 fix`\n\nIf doc↔code drift detection were running, **today's first error would have been caught by graphify, surfacing the message \"you wrote a solution 17 days ago in reference_gitnexus_setup.md\"**.\n\nWhat actually happened — **I (with AI) just walked into the trap. Failure #1, failure #2, then checked memory for the solution**. 20 minutes of tuition.\n\nThis is the real cost of dev-time drift — **not the big-bang bugs, but the 20-minutes × 365 days = 122 hours/year of low-grade friction**.\n\nChain graphify (doc-graph) + gitnexus (code-graph) + governance-guard (auditor), and **you can auto-detect four kinds of drift**:\n\n| Drift Type | Example | Detection Method |\n|---|---|---|\nIntention drift |\nDocs say it exists, code didn't implement it | doc-graph has node + code-graph empty |\nUndocumented knowledge |\nCode works fine, docs never described it | code-graph has node + doc-graph empty |\nConcept gap |\nDocs link A→B, code never imports | doc-graph has edge + code-graph missing edge |\nHidden complexity |\nCode has complex flow, docs give zero explanation | code-graph node degree high + doc-graph corresponding node low |\n\nAll four I've stepped on. **Series UI absence = Intention drift**. **cp950 solution forgotten = Undocumented knowledge** (solution was in `memory.md`\n\nbut `governance-guard`\n\ndidn't know about it).\n\nI did web research. Conclusion: **the community isn't doing this**. Someone is doing code-graph routing ([Sidharth Satapathy's 17-agent crew](https://www.sidharthsatapathy.com/blog/gitnexus-dual-graph-engine-token-savings/) uses dual-graph for problem routing), but **nobody is doing drift detection**.\n\nSeveral structural reasons:\n\n**Stack these 6 conditions. The number of people who simultaneously have all 6 isn't large.** I'm not discovering a new continent. **I just happen to stand in the only spot where this landscape is visible.**\n\nHow I'm trying to make this combo run (incomplete, still experimenting):\n\n`git commit`\n\n`graphify-out/needs_update`\n\n, the ritual reminds me to re-run`TECH-DEBT-BACKLOG.md`\n\nhigh-priority items + `needs_update`\n\nflag`gitnexus_impact`\n\nfirst to see blast radius`governance-guard.mjs`\n\nto see new violations`.md`\n\nmention this concept?) and gitnexus (are there UI components referencing this field?)Honestly, **this workflow isn't fully formed yet**. Item 5 I only realized I needed today (because of the series UI absence). **But the scaffolding is there**, what's missing is the orchestration script that wires three tool outputs together.\n\nWalking through the 4-22 governance awakening, the 4-29 \"I'm dumbfounded\" moment, and the 5-02 Layer 6 expansion, my definition of governance has evolved.\n\nThe most dramatic moment was 2026-05-15 afternoon:\n\n\"Chain these three governance skills together: data-flow-audit + data-contract-propagation-audit + workstation-button-interaction — the same production bug simultaneously triggered all three abstract governance skills.\"\n\nThat moment I realized — **governance is no longer about \"how many rules I've written\"**. It's about **\"how many of my written skills the same bug triggers simultaneously\"**.\n\nDrawn as a diagram:\n\n```\n              Production Bug\n                   │\n        ┌──────────┼──────────┐\n        ↓          ↓          ↓\n  data-flow-   data-contract  workstation-\n  audit.md   propagation     button-\n             -audit.md       interaction.md\n        ↓          ↓          ↓\n        └─── 3 governance skills resonate ──┘\n                       ↓\n              Fix once, prevent thrice\n```\n\nGraphify already knew, during community detection, that these three skills belong to the same community. They share `surprising_similar_to`\n\nedges. **But only when I query \"what skills relate to this bug?\" does graphify return all three**.\n\nPut another way — the highest form of governance is **not the count of rules, but the network resonance between them**.\n\nI also have to say — **this combo isn't cheap**:\n\nNot something to do during MVP phase.\n\n**Should**:\n\n`.md`\n\nfiles**Shouldn't**:\n\n`.md`\n\nfiles (doc-graph has nothing to extract)If you also want to start building this combo, the minimum steps I'd recommend:\n\n`.md`\n\nto 20+ before adding graphify**Don't combo for combo's sake**. Each tool comes in to solve a specific pain. Not because \"it sounds cool to chain them\".\n\nFor me personally, this combo is **how I turn that April governance trauma into something systemic**.\n\nBefore, bug-fixing felt like whack-a-mole — fix one, another pops up. Then I built `governance-guard`\n\nand it felt like inventory — I knew what violations existed but didn't know when they'd detonate.\n\nThe vision now — **let all the .md I've written (past me), all the code I've shipped (present me), and the governance rules (my promises to future me) talk to each other**.\n\nIt's not about letting AI write faster. It's about letting **past me and present me stop fighting each other**.\n\nThose 348 commits in April — **if this combo had been running, maybe only 100 would have been needed. The other 248 were tuition for \"I'd already written the solution but forgot.\"**\n\nOne last meta moment: writing this article was itself a reconciliation mechanism. While auditing my own GRAPH_REPORT numbers for the T10 article, I finally saw clearly that the god-nodes were minified noise — 50 minutes to clean up 4,549 noise nodes. The cleanup record lives at\n\n`治理深度整合紀錄/dist2_cleanup_meta_moment_2026-05-22.md`\n\n.\n\n*I'm coffeeshooters — a coffee roaster building software because there wasn't anything off-the-shelf that fit my real workflow. If this resonates: my full dev toolkit is public, and you can also support my coffee brand at coffeeshooters.com.*", "url": "https://wpnews.pro/news/dual-graph-drift-detection-for-solo-devs-what-happens-when-your-docs-and-your-to", "canonical_source": "https://dev.to/dexterlung/dual-graph-drift-detection-for-solo-devs-what-happens-when-your-docs-and-your-code-start-talking-522h", "published_at": "2026-08-16 13:05:11+00:00", "updated_at": "2026-08-16 13:12:14.301562+00:00", "lang": "en", "topics": ["developer-tools", "ai-tools", "artificial-intelligence"], "entities": ["Claude Code", "Taiwan"], "alternates": {"html": "https://wpnews.pro/news/dual-graph-drift-detection-for-solo-devs-what-happens-when-your-docs-and-your-to", "markdown": "https://wpnews.pro/news/dual-graph-drift-detection-for-solo-devs-what-happens-when-your-docs-and-your-to.md", "text": "https://wpnews.pro/news/dual-graph-drift-detection-for-solo-devs-what-happens-when-your-docs-and-your-to.txt", "jsonld": "https://wpnews.pro/news/dual-graph-drift-detection-for-solo-devs-what-happens-when-your-docs-and-your-to.jsonld"}}