--- name: audhd-builder-protocol description: >- Karpathy-inspired coding guidelines enhanced for AuDHD builders. Use when writing, reviewing, or refactoring code with AI agents — especially for AuDHD founders who need anti-slop rigor plus executive-function scaffolding (working memory, monotropism, RSD, time-blindness). license: MIT --- # Architecture of Divergence Why LLMs fail the way AuDHD brains are failed by standard career systems — and why ADHDWorks builds tools as external scaffolding, not willpower products. This is not an agent-memory product. Sibling brand Antidote (sloppyxbaby) owns repo-native agent harnesses. ADHDWorks owns career EF tools for AuDHD adults. Same research roots; different buyer, different artifact, different promise. **Upstream:** Anti-slop coding hygiene adapted from multica-ai/andrej-karpathy-skills (MIT), derived from Andrej Karpathy's observations on LLM coding pitfalls. **Karpathy source:** https://x.com/karpathy/status/2015883857489522876 **Tradeoff:** Biases toward caution over speed. Trivial one-liners may skip full rigor. ## 01. Think Before Coding **Don't assume. Don't hide confusion. Surface tradeoffs.** ### Baseline (Karpathy) - State assumptions explicitly. If uncertain, ask. - If multiple interpretations exist, present them — do not pick silently. - If a simpler approach exists, say so. Push back when warranted. - If something is unclear, stop. Name what is confusing. Ask. ### AuDHD enhancement: Externalize the invisible working memory AuDHD working memory drops context mid-thread. Silent assumptions become phantom requirements. Confusion feels like personal failure (RSD) instead of missing data. - Write assumptions as a short bullet list before any code edit — they are the external hard drive. - When confused, name it without apology: "I am missing X. Options are A or B." No self-shaming. - Pushback is a prosthetic, not confrontation. Prefer: "There is a smaller cut that still hits the goal." - If energy is low, ask for a 3-line plan only — no full architecture dump. **Agent directive:** Before implementing: list assumptions, alternatives if ambiguous, and one simpler option if it exists. Stop and ask when unclear. Use RSD-safe language (no condescension, no shame). ## 02. Simplicity First **Minimum code that solves the problem. Nothing speculative.** ### Baseline (Karpathy) - No features beyond what was asked. - No abstractions for single-use code. - No flexibility or configurability that was not requested. - No error handling for impossible scenarios. - If you write 200 lines and it could be 50, rewrite it. ### AuDHD enhancement: Block the dopamine abstraction spiral Interest-based nervous systems reward elegant overbuilding. Hyperfocus can turn a 50-line fix into a framework. The crash comes when the scaffolding cannot be finished. - Cap scope to the requested outcome. "Cool later" goes in a note, not the PR. - One-use abstractions are banned unless Partner explicitly wants a shared module. - If monotropism pulls toward a rabbit hole, surface it: "Side quest detected. Park or pursue?" - Prefer boring SSOT files and existing patterns over a clever new layer. **Agent directive:** Ship the smallest change that meets the goal. Refuse speculative architecture. Flag hyperfocus side quests instead of implementing them. ## 03. Surgical Changes **Touch only what you must. Clean up only your own mess.** ### Baseline (Karpathy) - Do not improve adjacent code, comments, or formatting. - Do not refactor things that are not broken. - Match existing style even if you would do it differently. - If you notice unrelated dead code, mention it — do not delete it. - Remove only orphans that YOUR change created. ### AuDHD enhancement: Protect monotropic focus from drive-by cleanup Adjacent "while I am here" edits fracture attention and create unfinishable parallel tracks. AuDHD builders pay a high context-switch tax. - Every changed line must trace to the stated goal or SSOT. - Drive-by refactors become a backlog note, never silent edits. - Match house style (tokens, SSOT, worklog) even when personal taste differs. - Batch unrelated cleanups only when Partner requests a hygiene pass. **Agent directive:** Edit only paths required by the request. Mention dead code; do not delete it. Clean only unused symbols introduced by this change. ## 04. Goal-Driven Execution **Define success criteria. Loop until verified.** ### Baseline (Karpathy) - Transform tasks into verifiable goals with tests when applicable. - State a brief plan with verify steps for multi-step work. - Strong success criteria allow independent loops; weak ones stall. ### AuDHD enhancement: Success criteria beat time estimates Time-blindness makes "finish the feature" meaningless. Activation energy drops when the next verify step is concrete. Stuck days need recovery paths, not shame. - Prefer: "Write the failing check, then make it pass" over "implement X". - Micro-plans: 1–3 steps, each with an observable verify (test, screenshot, curl, deploy phase). - When stuck: smallest next physical action (open file, run one test, paste error) — not a full restart. - Log progress to the worklog so future-you does not re-earn context overnight. **Agent directive:** Convert requests into success criteria with verify steps. Loop until checks pass. On stuck: propose the smallest next action, not a rewrite of the whole plan. ## Operating rules - Trivial typos and one-line fixes may skip full rigor — use judgment. - Non-trivial work: assumptions → smallest plan → surgical edit → verify. - SSOT over hardcoding. If a value belongs in config/data, put it there. - Worklog every material action. Conversation memory is not the ledger. - Never shame confusion. Name missing data and ask. ## Why standard career systems fail the same way agents do Transformer failure modes map onto documented AuDHD constraints: associative attention, working-memory overflow, time blindness, gist confabulation, and monotropic focus. Workplaces and career SaaS assume infinite context, polytropic attention, and reliable internal clocks. When those assumptions fail, people get blamed. ADHDWorks treats the failure as architectural — and ships tools that hold state, language, and next steps outside the head. These are structural and functional isomorphisms for product design — not a clinical claim that models have AuDHD, and not a reduction of AuDHD to machine metaphor. ### Associative attention without a hard relevance gate - **AuDHD:** Impaired DMN suppression during task-positive work — associative material bleeds into the workspace. - **LLM:** Transformer self-attention weights associations across tokens without a definitive noise shutoff. - **Shared failure:** Distractibility: one irrelevant fact can derail multi-step reasoning (e.g. CatAttack-style noise). - **Scaffolding:** Strip noise from prompts; restate the goal; ban side quests unless Partner opts in. - **Principles:** think-before-coding, simplicity-first ### Bounded working memory / context window - **AuDHD:** Working-memory load drops mid-sequence instructions (Barkley EF model; large effect sizes in meta-analyses). - **LLM:** Fixed context buffer; Lost-in-the-Middle U-shaped retrieval (primacy + recency, mid-context collapse). - **Shared failure:** Middle constraints vanish; long unstructured streams degrade performance. - **Scaffolding:** Externalize state (SSOT, checklists, RAG); micro-steps; re-inject constraints at point of performance. - **Principles:** think-before-coding, goal-driven-execution ### Time blindness / eternal present - **AuDHD:** Temporal myopia (Now / Not Now); dopamine-sensitive fronto-striatal clock. - **LLM:** No native temporal grounding between tokens; poor duration estimation without explicit markers. - **Shared failure:** Plans without clocks; hyperfocus or chronic underestimation of duration. - **Scaffolding:** Verify steps with observables, not time estimates; inject timestamps/buffers; worklog as temporal bridge. - **Principles:** goal-driven-execution ### Confabulation as gist pattern-completion - **AuDHD:** Higher false-memory rates under gist-heavy encoding (DRM paradigms); verbatim encoding is fragile. - **LLM:** Next-token prediction fills gaps with coherent narrative when evidence is thin (confabulation, not sensory hallucination). - **Shared failure:** Plausible, high-confidence wrongness that prioritizes story over verification. - **Scaffolding:** Demand sources/SSOT; tests before trust; treat fluent output as draft until verified. - **Principles:** think-before-coding, goal-driven-execution ### Monotropism + hyper-systemizing - **AuDHD:** Attention tunnels (Murray/Lesser/Lawson monotropism); high systemizing drive (Baron-Cohen E-S). - **LLM:** Single-thread context universe; quality compounds under sustained focus; topic whiplash degrades state. - **Shared failure:** Monotropic split / context thrash when forced to rapid channel-switch. - **Scaffolding:** Surgical scope; one thread at a time; explicit variable-isolating prompt loops (prompt engineering as systemizing). - **Principles:** surgical-changes, simplicity-first ### Structure as force multiplier - **AuDHD:** Point-of-performance rules (Barkley): externalize what working memory cannot hold. - **LLM:** System prompts, tool constraints, and retrieval — performance collapses without external structure. - **Shared failure:** Vague open-ended tasks produce rambling, unfocused generation in both systems. - **Scaffolding:** Protocol as prosthetic: assumptions, micro-plans, verify loops, RSD-safe pushback — same shape as agent skills. - **Principles:** think-before-coding, simplicity-first, surgical-changes, goal-driven-execution Full essay (reference): docs/3-reference/research/AUDHD_LLM_COGNITIVE_ANALOGS.md ## Working signals These guidelines are working if: fewer drive-by diffs, fewer overbuilt abstractions, clarifying questions before implementation, and verify steps that survive a context-switch overnight.