ahead-pi 0.2.0 → 0.3.0

package/generated/reference/docs/rationale.md

@@ -0,0 +1,210 @@
+# Why AHEAD
+
+## Human-led engineering, amplified by AI
+
+AI can make software engineering faster. It can search broadly, synthesize information, identify omissions, generate alternatives, produce routine code, explain unfamiliar systems, and review more material than a person can inspect unaided.
+
+Those capabilities create real leverage. They also create a temptation to optimize for the visible artifact—an answer, design, plan, or code change—while weakening the human understanding that makes the artifact trustworthy.
+
+AHEAD exists because software engineering is not merely the production of code. It is the development and application of judgment under incomplete information. Engineers frame problems, construct mental models, decide which tradeoffs matter, test explanations, recognize abnormalities, and remain accountable when systems affect other people.
+
+The goal is therefore not maximum AI autonomy. It is a stronger combined engineering system in which automation increases human capability without displacing the thinking required to direct, evaluate, and improve it.
+
+The central principle is:
+
+> **Human thinks first → AI amplifies and challenges → Human decides.**
+
+## The Toyota lesson
+
+In 2014, Bloomberg reported that Toyota was putting skilled people back into selected production processes that had been automated. The objective was not nostalgia or the wholesale rejection of robots. Toyota wanted workers to deepen their manual knowledge of how parts were made so they could discover improvements and build better processes and machines.
+
+Toyota's own description of the Toyota Production System gives the broader principle. Its concept of *jidoka* is commonly described as “automation with a human touch.” Toyota explains that people first need to understand work well enough to perform it, detect abnormalities, remove waste and inconsistency, and then embody that learning in machinery. Automation handles repeatable work, while people supply judgment and *kaizen*—continuous improvement.
+
+Toyota has continued to describe its approach as automation centered on people. Its position is not that machines are undesirable. It is that machines do not independently determine what improvement means. Human skill and technological capability must develop together.
+
+That is the analogy AHEAD applies to software engineering.
+
+AI can generate an implementation without possessing the team's lived understanding of its customers, constraints, architecture, operations, risk tolerance, or long-term intent. If engineers become reviewers of artifacts they did not reason toward, they may gradually lose the ability to recognize subtle errors, challenge framing, diagnose novel failures, or improve the engineering process itself.
+
+AHEAD therefore keeps humans engaged in the parts of engineering that create and exercise judgment. AI is used aggressively where it expands human reach, but not in ways that turn engineers into passive supervisors of a process they no longer understand.
+
+The analogy has limits. Software development is not an assembly line, generative AI is not an industrial robot, and Toyota's experience does not prove a particular software methodology. The useful lesson is narrower: **capability that is fully delegated can stop developing, and people need direct contact with the work to recognize abnormalities and invent better ways of doing it.**
+
+Sources:
+
+- [Humans Replacing Robots Herald Toyota's Vision of Future — Bloomberg, 2014](https://www.bloomberg.com/news/articles/2014-04-06/humans-replacing-robots-herald-toyota-s-vision-of-future)
+- [Toyota Production System — Toyota Motor Corporation](https://global.toyota/en/company/vision-and-philosophy/production-system/)
+- [Skilled Manufacturing Key to the Future — Toyota Motor Corporation](https://global.toyota/en/newsroom/corporate/35433493.html)
+
+## Understanding is productive capacity
+
+An engineer's mental model is part of the organization's productive capacity. It enables the engineer to:
+
+- determine whether the requested solution addresses the real problem;
+- recognize when a generated answer is plausible but wrong;
+- reason about behavior that is not represented in the immediate prompt;
+- debug unfamiliar or emergent failures;
+- make safe changes under time pressure;
+- explain and defend architectural decisions;
+- teach teammates and improve tools and processes;
+- remain accountable for the result.
+
+Code produced quickly without corresponding understanding can create hidden debt. The organization receives an artifact, but it may lose the ability to operate and evolve that artifact safely. AHEAD treats understanding as a required engineering outcome rather than incidental overhead.
+
+## Why humans think first
+
+AI suggestions are influential even when they are weak. Once an apparently coherent answer is present, people tend to evaluate that answer instead of exploring the problem independently. The question can quietly change from “What do we think is right?” to “Can we find a reason to accept or reject what the AI proposed?”
+
+AHEAD asks the human to contribute first where independent judgment matters:
+
+- define the problem and desired outcome;
+- state an initial understanding or set of questions;
+- propose at least one option before AI expands the option space;
+- select debugging hypotheses and tests;
+- choose the decision and accept its tradeoffs;
+- write the first-pass implementation or remediation plan;
+- own the implementation; for lasting changes, a different human performs the final engineering review.
+
+The first human contribution does not need to be polished or complete. Its purpose is to make the person's current mental model visible before AI influences it. AI can then do what it is particularly good at: broaden the search, find contradictions, identify omissions, generate counterarguments, and expose assumptions.
+
+## Why AI still matters
+
+Human-led does not mean AI-last, AI-light, or manually performing every task. Refusing useful automation would also weaken engineering.
+
+AI can improve the process by:
+
+- researching internal and external sources;
+- compiling evidence and tracing claims back to sources;
+- identifying missing questions and contradictory information;
+- proposing additional options after the human has framed the space;
+- arguing against a preferred approach;
+- generating debugging hypotheses and discriminating tests;
+- assisting with bounded implementation, tests, and mechanical changes;
+- reviewing correctness, security, architecture, test coverage, and plan compliance;
+- comparing observed outcomes with original intent;
+- preserving and connecting engineering knowledge.
+
+The correct boundary is not “human work” versus “AI work.” It is **human accountability and judgment supported by appropriately scoped AI capabilities**.
+
+## Why decisions remain human
+
+Engineering decisions are rarely determined by technical facts alone. They encode product priorities, acceptable risk, reversibility, organizational capability, operational burden, opportunity cost, and obligations to users.
+
+AI can make those considerations visible, but it cannot legitimately accept their consequences for the organization. AHEAD therefore requires humans to select approaches, record rationale and tradeoffs, accept unresolved uncertainty, and approve consequential actions.
+
+This is not ceremonial approval. If a human cannot explain the decision and the evidence behind it, the workflow has produced an approval record without producing accountable engineering.
+
+## Why debugging remains human-led
+
+Debugging is not simply locating a suspicious line of code. It is an iterative process of constructing and correcting a model of reality:
+
+```text
+Facts → mental model → hypothesis → test
+→ updated evidence → revised model → conclusion
+```
+
+AI can generate many plausible explanations and suggest evidence to collect. Humans still choose which explanations are credible enough to test, authorize safe experiments, interpret results in context, and decide when the evidence justifies a conclusion or intervention.
+
+This matters even more for operational systems. A production failure may not be a software bug. It may arise from reconciliation behavior, configuration drift, capacity, an external provider, timing, data, or an emergent interaction between individually functioning components. Investigation requires an understanding of desired versus actual state, timelines, control loops, scope, and recovery signals. AHEAD supports that human reasoning rather than reducing every failure to AI-assisted source-code search.
+
+## Why AI review does not replace human review
+
+AI review and human review provide different defenses.
+
+AI can consistently compare a large changeset against requirements, plans, common defect patterns, security concerns, and missing tests. It can revisit the work without fatigue and produce useful challenges.
+
+Human reviewers understand organizational context, implicit architectural boundaries, operational history, product consequences, and whether the implementation is one the team is willing and able to own. They also carry accountability that an AI system cannot.
+
+AHEAD uses AI review before final human review. For a lasting engineering change, that final review is performed by a person other than the implementer. The AI broadens scrutiny; the independent human reviewer makes the final engineering judgment. In an emergency, review may be deferred to restore service, but it remains due after stabilization.
+
+## The failure modes AHEAD is designed to prevent
+
+### Artifact without understanding
+
+The AI produces a persuasive design or implementation, but nobody can adequately explain why it is correct or how it will behave outside the happy path.
+
+### Automation bias
+
+The first generated answer anchors the team's thinking, narrowing the options and hypotheses they seriously consider.
+
+### Accountability theater
+
+A human clicks approve after inspecting output but did not own the framing, decision, or reasoning that produced it.
+
+### Skill atrophy
+
+Engineers increasingly supervise generated work while exercising less of the problem solving, debugging, and system modeling needed for novel situations.
+
+### Self-confirming automation
+
+AI proposes the approach, implements it, generates its tests, and reviews its own assumptions. Multiple artifacts create the appearance of independent checks while sharing the same blind spots.
+
+### Process theater
+
+Required documents and gates are completed to satisfy tooling, but they do not record real reasoning or improve decisions.
+
+AHEAD must resist all six. Its workflows should create useful moments for thought, challenge, evidence, and decision—not merely more generated paperwork.
+
+## What AHEAD optimizes for
+
+AHEAD does not optimize for lines of AI-generated code or the percentage of a workflow performed autonomously. It optimizes for:
+
+- better problem framing;
+- broader and better-supported option sets;
+- explicit decisions and tradeoffs;
+- stronger human mental models;
+- faster access to relevant evidence;
+- safer implementation and operations;
+- independent challenge before consequential actions;
+- earlier detection of incorrect assumptions;
+- durable, inspectable engineering knowledge;
+- learning that improves both people and automation.
+
+Delivery speed matters. AHEAD's claim is that sustainable speed comes from combining human understanding with AI leverage, not from maximizing automation at every step.
+
+## The intended relationship
+
+The relationship between an engineer and AI should resemble a strong engineering partnership, with an important asymmetry: the human is accountable.
+
+The human supplies intent, context, judgment, and responsibility. AI supplies reach, recall, variation, synthesis, and challenge. Each compensates for limitations of the other, but only the human can decide what the organization should do and own what happens next.
+
+That is why AHEAD means **Assisted Human Engineering and Development**. The adjective is “assisted.” The subject is human engineering.
+
+## How AHEAD expects engineers to work
+
+AHEAD's philosophy applies beyond explicit workflow gates. Engineers should:
+
+- care about the quality and consequences of their work;
+- think deliberately rather than operate on autopilot;
+- understand the user, domain, constraints, and system before optimizing a solution;
+- make assumptions, evidence, decisions, and uncertainty visible;
+- prefer simple, local, independently changeable parts over convenient but entangled designs;
+- prototype to learn without quietly turning exploratory code into production code;
+- automate repeatable mechanics while retaining mastery of the work being automated;
+- design for testing, failure, diagnosis, and recovery;
+- use version control, traceable decisions, and durable engineering records;
+- fix problems without turning investigation into blame;
+- communicate from genuine understanding and state uncertainty honestly;
+- keep learning, including learning when a favored tool or practice does not improve outcomes.
+
+The detailed [engineering-practice guide](engineering-practice.md) traces these recommendations to empirical research, standards, and practitioner sources. Not every useful craft principle has experimental support; AHEAD labels the source and strength instead of presenting all advice as settled science.
+
+## Acceptable use of AI
+
+AI use is appropriate when it expands human reach without replacing the human reasoning, knowledge, or accountability the work requires. Typical uses include research, bounded boilerplate, candidate tests after a human defines expected behavior, examples and fixtures, explanations, proposed refactorings, documentation drafts based on supplied facts, structured meeting notes, additional design options, debugging hypotheses, and first-pass review.
+
+Full vibe coding is also appropriate for explicitly disposable, isolated prototypes built to answer a learning question quickly. The prototype may demonstrate feasibility or reveal how an idea feels, but it is not production evidence. Useful learning is preserved; prototype code is discarded. Anything retained must re-enter the ordinary human-led engineering workflow.
+
+AI use is not acceptable when it defines business behavior, substitutes for learning or codebase knowledge, makes a consequential decision, produces core business logic on the engineer's behalf, hides uncertainty, invents evidence, impersonates human authorship, performs final approval, uses unauthorized sensitive context, or produces code the responsible engineer cannot explain, test, maintain, debug, and change.
+
+The boundary depends on risk. AI may assist with security, authorization, cryptography, data migrations, infrastructure, CI/CD, or production operations, but such work requires explicit human design, authorization, and independent verification. Workflow permission never grants operational permission.
+
+The full [acceptable-use policy](acceptable-ai-use.md) records the conditions, heightened-review areas, prohibited uses, and evidence behind these boundaries.
+
+## Evidence posture
+
+AHEAD is evidence-informed; it is not yet an experimentally validated methodology. No single study establishes that the complete AHEAD sequence is optimal. Some principles have direct support from empirical software-engineering research, some draw on adjacent cognitive research or consensus standards, and some—especially the exact “human first” sequencing—remain design hypotheses that AHEAD must test.
+
+The existing evidence also resists simplistic claims about AI. A randomized field study across 4,867 developers found increased completed tasks with access to an AI coding assistant, while a smaller randomized study of experienced open-source developers working in familiar repositories found that the available AI tools increased completion time. The responsible conclusion is that AI's effect depends on the people, task, system, tool, and outcome being measured—not that AI is inherently productive or unproductive.
+
+AHEAD will maintain a [research map](evidence/research-map.md) that records the evidence and limitations behind each important process choice. Its [evidence standard](evidence/evidence-standard.md) defines how claims are classified and how the methodology should be revised when better evidence appears.

package/generated/reference/docs/recommended-skills.md

@@ -0,0 +1,19 @@
+# Recommended Skills
+
+Status: reviewed catalog v0.1
+
+AHEAD may recommend independently maintained agent skills when they strengthen an active phase. Recommendations are references, not bundled code or silent dependencies. A human chooses whether to inspect and install one, and AHEAD's workflow, authority boundaries, and gates remain controlling.
+
+The machine-readable catalog is `recommendations/skills-v0.1.json`. Every entry pins the exact revision AHEAD reviewed, supplies an inspectable source URL and install command, identifies applicable workflows and phases, and records compatibility constraints. Updating a recommendation requires reviewing the new revision before changing the pin.
+
+## Ponytail
+
+[Ponytail](https://github.com/DietrichGebert/ponytail/tree/2ed6c52c9d7e5e56942508591085fd45dea277d3/skills/ponytail) is recommended as an optional persistence and problem-solving aid for difficult implementation, corrective debugging, and investigation work. AHEAD does not adopt Ponytail's authority model: the human still leads, its suggestions remain subject to the active phase, and a quick version is not production-ready merely because it works.
+
+Inspect the pinned source, then opt in with:
+
+```sh
+npx skills add https://github.com/DietrichGebert/ponytail/tree/2ed6c52c9d7e5e56942508591085fd45dea277d3/skills/ponytail --agent pi
+```
+
+The Pi integration exposes this catalog but never runs the command itself. Future editor adapters should render the same canonical catalog through their native UI.

package/generated/reference/docs/references/pragmatic-programmer-page-index.md

@@ -0,0 +1,113 @@
+# *The Pragmatic Programmer* Page Index
+
+Status: submitted source notes
+
+## Edition and use
+
+This index preserves the page-level provenance from the original AHEAD engineering-practice notes for:
+
+> David Thomas and Andrew Hunt, *The Pragmatic Programmer: Your Journey to Mastery*, 20th Anniversary Edition, ISBN 9780135957059.
+
+Page numbers are edition-specific and may not match an ebook or another printing. The titles and locators below are the submitter's reading notes, retained so AHEAD's distilled guidance remains traceable. They are not presented as scientific evidence; the [research map](../evidence/research-map.md) separately records empirical support.
+
+Two submitted locators look like transcription errors but are intentionally preserved pending a check against the physical edition:
+
+- tips 1 and 2 use `xlx`, which is not standard Roman-numeral notation;
+- tip 40 uses p. 15, although it occurs between notes for pp. 151 and 156.
+
+## Tip locators
+
+| No. | Submitted tip title | Page |
+|---:|---|---:|
+| 1 | Care About Your Craft | xlx |
+| 2 | Think! About Your Work | xlx |
+| 3 | Provide Options, Don't Make Lame Excuses | 3 |
+| 4 | Don't Live With Broken Windows | 5 |
+| 5 | Be a Catalyst for Change | 8 |
+| 6 | Remember the Big Picture | 8 |
+| 7 | Make Quality a Requirements Issue | 11 |
+| 8 | Invest Regularly in Your Knowledge Portfolio | 14 |
+| 9 | Critically Analyze What You Read and Hear | 16 |
+| 10 | It's Both What You Say and the Way You Say It | 21 |
+| 11 | DRY—Don't Repeat Yourself | 27 |
+| 12 | Make It Easy to Reuse | 33 |
+| 13 | Eliminate Effects Between Unrelated Things | 35 |
+| 14 | There Are No Final Decisions | 46 |
+| 15 | Use Tracer Bullets to Find the Target | 49 |
+| 16 | Prototype to Learn | 54 |
+| 17 | Program Close to the Problem Domain | 58 |
+| 18 | Estimate to Avoid Surprises | 64 |
+| 19 | Iterate the Schedule with the Code | 69 |
+| 20 | Keep Knowledge in Plain Text | 74 |
+| 21 | Use the Power of Command Shells | 80 |
+| 22 | Use a Single Editor Well | 85 |
+| 23 | Always Use Source Code Control | 88 |
+| 24 | Fix the Problem, Not the Blame | 91 |
+| 25 | Don't Panic When Debugging | 91 |
+| 26 | “select” Isn't Broken | 96 |
+| 27 | Don't Assume It—Prove It | 97 |
+| 28 | Learn a Text Manipulation Language | 100 |
+| 29 | Write Code That Writes Code | 103 |
+| 30 | You Can't Write Perfect Software | 107 |
+| 31 | Design with Contracts | 111 |
+| 32 | Crash Early | 120 |
+| 33 | Use Assertions to Prevent the Impossible | 122 |
+| 34 | Use Exceptions for Exceptional Problems | 127 |
+| 35 | Finish What You Start | 129 |
+| 36 | Minimize Coupling Between Modules | 140 |
+| 37 | Configure, Don't Integrate | 144 |
+| 38 | Put Abstractions in Code, Details in Metadata | 145 |
+| 39 | Analyze Workflow to Improve Concurrency | 151 |
+| 40 | Design Using Services | 15 |
+| 41 | Always Design for Concurrency | 156 |
+| 42 | Separate Views from Model | 161 |
+| 43 | Use Blackboards to Coordinate Workflow | 169 |
+| 44 | Don't Program by Coincidence | 175 |
+| 45 | Estimate the Order of Your Algorithms | 181 |
+| 46 | Test Your Estimates | 182 |
+| 47 | Refactor Early, Refactor Often | 186 |
+| 48 | Design to Test | 192 |
+| 49 | Test Your Software, or Your Users Will | 197 |
+| 50 | Don't Use Wizard Code You Don't Understand | 199 |
+| 51 | Don't Gather Requirements—Dig for Them | 202 |
+| 52 | Work with a User to Think Like a User | 204 |
+| 53 | Abstractions Live Longer than Details | 209 |
+| 54 | Use a Project Glossary | 210 |
+| 55 | Don't Think Outside the Box—Find the Box | 213 |
+| 56 | Start When You're Ready | 215 |
+| 57 | Some Things Are Better Done than Described | 218 |
+| 58 | Don't Be a Slave to Formal Methods | 220 |
+| 59 | Costly Tools Don't Produce Better Designs | 222 |
+| 60 | Organize Team Around Functionality | 227 |
+| 61 | Don't Use Manual Procedures | 231 |
+| 62 | Test Early. Test Often. Test Automatically. | 237 |
+| 63 | Coding Ain't Done 'Til All the Tests Run | 238 |
+| 64 | Use Saboteurs to Test Your Testing | 244 |
+| 65 | Test State Coverage, Not Code Coverage | 245 |
+| 66 | Find Bugs Once | 247 |
+| 67 | English Is Just a Programming Language | 248 |
+| 68 | Build Documentation In, Don't Bolt It On | 249 |
+| 69 | Gently Exceed Your Users' Expectations | 255 |
+| 70 | Sign Your Work | 258 |
+
+## Checklist locators
+
+| Submitted checklist | Page |
+|---|---:|
+| The Wisdom Acrostic | 20 |
+| How to Maintain Orthogonality | 34 |
+| Things to Prototype | 53 |
+| Architectural Questions | 55 |
+| Debugging Checklist | 98 |
+| Law of Demeter for Functions | 141 |
+| How to Program Deliberately | 172 |
+| When to Refactor | 185 |
+| Cutting the Gordian Knot | 212 |
+
+The submitted “Aspects of Testing” checklist did not include a page locator, so this index does not invent one.
+
+The complete submitted checklist bodies and the additional post-Pragmatic tips and practices are retained in the [submitted engineering notes](submitted-engineering-notes.md).
+
+## Maintenance rule
+
+When AHEAD guidance derived from these notes is reorganized or condensed, retain the page-level reference either at the point of use or through a link to this index. If a locator is corrected against the referenced print edition, record the correction in the commit rather than silently replacing the submitted value.

package/generated/reference/docs/references/submitted-engineering-notes.md

@@ -0,0 +1,306 @@
+# Submitted Engineering Notes
+
+Status: submitted source notes
+
+## Purpose and provenance
+
+This document preserves submitted engineering tips, checklists, and practices that are intentionally condensed in the [AHEAD Engineering Practice](../engineering-practice.md) guide. It is a source record, not a claim that every item is an experimentally validated rule.
+
+Tips 1–70 and their submitted page locators from *The Pragmatic Programmer* are retained in the [edition-specific page index](pragmatic-programmer-page-index.md). Their accompanying submitted meanings are retained below, followed by the additional tips and the full submitted checklist and practice content. The submitted language-learning list is intentionally omitted.
+
+## *The Pragmatic Programmer* tip notes
+
+The page index is authoritative for the submitted locators. These concise notes preserve the submitted meaning associated with each title.
+
+| No. | Submitted meaning |
+|---:|---|
+| 1 | Care about doing software development well. |
+| 2 | Turn off autopilot; continually critique and appraise the work. |
+| 3 | Offer viable options instead of excuses or an unsupported claim that something cannot be done. |
+| 4 | Correct bad designs, wrong decisions, and poor code when they are found. |
+| 5 | Catalyze change by showing people a possible future and helping them participate in creating it. |
+| 6 | Keep checking the larger context rather than becoming trapped in implementation detail. |
+| 7 | Involve users in deciding the quality the project actually requires. |
+| 8 | Make continuous learning a regular investment. |
+| 9 | Critically evaluate vendor claims, media, received wisdom, and dogma in the context of the actual project. |
+| 10 | Effective communication depends on both the idea and how it is expressed. |
+| 11 | Give each piece of knowledge one unambiguous, authoritative representation, while avoiding premature abstraction; use the rule of three as a judgment prompt rather than dogma. |
+| 12 | Create an environment in which reuse is easy. |
+| 13 | Design self-contained, independent components with a single well-defined purpose. |
+| 14 | Treat decisions as revisable and plan for change. |
+| 15 | Use tracer implementations to test direction and progressively find the target. |
+| 16 | Treat prototypes as learning artifacts whose value lies in lessons rather than retained code. |
+| 17 | Design and code using the language of the problem domain and its users. |
+| 18 | Estimate before starting so potential problems become visible early. |
+| 19 | Refine schedules with the experience gained during implementation. |
+| 20 | Preserve knowledge in plain text so it remains portable, inspectable, testable, and debuggable. |
+| 21 | Use command shells when graphical interfaces do not provide enough leverage. |
+| 22 | Learn one configurable, extensible, programmable editor deeply enough that it becomes an extension of the hand. |
+| 23 | Always use source control so work and decisions can be recovered and revisited. |
+| 24 | Focus on fixing the problem rather than assigning blame. |
+| 25 | Do not panic while debugging; stop and think about plausible causes. |
+| 26 | Bugs are more often in the application than in foundational tools, but likelihood is not proof. |
+| 27 | Test assumptions in the real environment with realistic data and boundary conditions. |
+| 28 | Learn a text-manipulation language so repetitive text work can be automated. |
+| 29 | Use code generation to improve consistency and reduce duplicated mechanics. |
+| 30 | Perfect software is impossible; protect code and users from inevitable errors. |
+| 31 | Use contracts to state and verify what code promises and requires. |
+| 32 | Fail early when continuing would cause more damage or hide the real fault. |
+| 33 | Use assertions to validate assumptions and prevent impossible states from proceeding unnoticed. |
+| 34 | Reserve exceptions for exceptional conditions so control flow remains readable and maintainable. |
+| 35 | Where possible, make the code that acquires a resource responsible for releasing it. |
+| 36 | Minimize coupling and follow the principle of least knowledge. |
+| 37 | Express technology choices as configuration rather than baking them into unrelated implementation. |
+| 38 | Put general abstractions in code and variable details in metadata. |
+| 39 | Analyze user workflows to find genuine opportunities for concurrency. |
+| 40 | Design around independent, concurrent services behind consistent interfaces. |
+| 41 | Designing for concurrency can produce cleaner interfaces with fewer timing assumptions. |
+| 42 | Separate models from views where useful; this principle is broader than the MVC pattern. |
+| 43 | Use blackboards to coordinate facts and agents while preserving their independence and isolation. |
+| 44 | Do not rely on accidental behavior or confuse coincidence with deliberate design. |
+| 45 | Estimate algorithmic order before implementation to understand likely scaling behavior. |
+| 46 | Mathematical estimates are incomplete; measure behavior in the target environment. |
+| 47 | Refactor early and repeatedly when the system needs it, addressing the underlying problem rather than its surface arrangement. |
+| 48 | Think about testing before implementation so the design is observable and testable; this does not mandate or reject test-driven development. |
+| 49 | Test aggressively rather than relying on users to discover defects. |
+| 50 | Do not incorporate generated or wizard-produced code that the engineer does not understand. |
+| 51 | Discover requirements beneath assumptions, misconceptions, and organizational pressures rather than merely collecting surface statements. |
+| 52 | Work with users to understand how the system will actually be used. |
+| 53 | Invest in stable abstractions rather than transient implementation details. |
+| 54 | Maintain one authoritative glossary for project-specific vocabulary. |
+| 55 | When a problem appears impossible, identify the real constraints and question whether the assumed method or task is necessary. |
+| 56 | Respect accumulated experience and unresolved doubts when deciding whether the work is ready to begin. |
+| 57 | Avoid an endless specification spiral; some understanding emerges only by doing the work. |
+| 58 | Evaluate formal methods in the context of the team's practices and capabilities rather than following them blindly. |
+| 59 | Expensive tools and vendor prestige do not guarantee better designs; judge tools on their merits. |
+| 60 | Organize teams around delivered functionality instead of isolating design, coding, testing, and data work. |
+| 61 | Replace repeatable manual procedures with inspectable automation that executes consistently. |
+| 62 | Run automated tests early and frequently, preferably with every build. |
+| 63 | Coding is not complete until all required tests run. |
+| 64 | Deliberately introduce defects in an isolated copy to verify that tests can detect them. |
+| 65 | Test significant program states, not only executed lines. |
+| 66 | Preserve a reliable automated regression check after a human discovers a defect. |
+| 67 | Treat documentation like code by applying authoritative sources, metadata, separation of model and view, and generation where useful. |
+| 68 | Keep documentation close to the system so it is less likely to become incorrect or stale. |
+| 69 | Understand user expectations and then exceed them gently rather than surprising users with unrequested complexity. |
+| 70 | Take accountable pride in the work and be willing to sign it. |
+
+## Additional tips
+
+### 71. Create simple solutions, not easy ones
+
+Take time to find the simplest solution. The easy solution may use a familiar tool or pattern, but familiarity can conceal complexity and deprive the engineer of learning.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### 72. KISS — Keep It Simple, Stupid
+
+Simplicity is the ultimate sophistication. Simpler solutions are generally easier to understand, maintain, and extend.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### 73. The Locality of Behavior principle
+
+The behavior of a unit of code should be as obvious as possible from that unit. Separation of concerns may favor splitting behavior into separate pieces, while locality of behavior may favor keeping the tasks for a feature or component together. Some designs can satisfy both; others require an explicit tradeoff.
+
+No external source locator was included with this submitted note.
+
+### 74. Judge tools by the artifacts they produce
+
+Do not choose a language, library, framework, or pattern only because it is pleasant or familiar to use. Judge it by the long-lived software it helps create: reliability, changeability, debuggability, and the incidental complexity it leaves behind.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### 75. Avoid complecting independent concerns
+
+Complexity comes from braiding together things that could be reasoned about independently. Watch for value tied to time, function tied to state, policy tied to mechanism, meaning tied to order, and implementation details leaking across boundaries.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### 76. Isolate state
+
+State ties value to time. Keep mutable state explicit, minimal, and behind interfaces that let the rest of the system work with stable values when possible.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### 77. Prefer values, data, and functions
+
+Prefer immutable values, plain data, functions, queues, set operations, declarative queries, and explicit rules where they fit. These can create simpler artifacts than objects, mutable variables, inheritance, loops, object-relational mapping, and scattered conditionals.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### 78. Modular does not automatically mean simple
+
+Separate files, classes, modules, or services can still be deeply entangled. The real test is whether each part needs to know only stable abstractions rather than the hidden details or assumptions of other parts.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### 79. Tests are guardrails, not steering
+
+Tests and type checkers help catch mistakes, but they do not replace design clarity or reasoning. A production defect already passed the checks that existed, so the program must remain simple enough to understand.
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+## Submitted checklists
+
+### The Wisdom Acrostic
+
+- **W**hat do you want them to learn?
+- What is their **I**nterest in what you have to say?
+- How **S**ophisticated are they?
+- How much **D**etail do they want?
+- Whom do you want to **O**wn the information?
+- How can you **M**otivate them to listen?
+
+Submitted locator: *The Pragmatic Programmer*, p. 20.
+
+### How to maintain orthogonality
+
+- Design independent, well-defined components.
+- Keep code decoupled.
+- Avoid global data.
+- Refactor similar functions.
+
+Submitted locator: *The Pragmatic Programmer*, p. 34.
+
+### Things to prototype
+
+- Architecture.
+- New functionality in an existing system.
+- The structure or contents of external data.
+- Third-party tools or components.
+- Performance issues.
+- User-interface design.
+
+The submitted note emphasizes that prototype code is intended to be thrown away and may be fully vibe coded under the AHEAD disposable-prototype policy.
+
+Submitted locator: *The Pragmatic Programmer*, p. 53.
+
+### Architectural questions
+
+- Are responsibilities well defined?
+- Are collaborations well defined?
+- Is coupling minimized?
+- Can potential duplication be identified?
+- Are interface definitions and constraints acceptable?
+- Can modules access the data they need when they need it?
+
+Submitted locator: *The Pragmatic Programmer*, p. 55.
+
+### Simplicity and complecting review
+
+- Is this design simple, or only easy because it is familiar?
+- What concepts are tied together that could vary independently?
+- What incidental complexity are we accepting from the selected tools, libraries, frameworks, or patterns?
+- Can this part be understood without loading the rest of the system into your head?
+- Is state explicit, minimized, and isolated?
+- Are policies and rules gathered somewhere clear, or scattered through unrelated code paths?
+- Are we choosing this approach for authoring convenience or for the quality of the artifact it creates?
+- Do tests support our reasoning, or are we depending on them to compensate for unclear design?
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### Abstraction questions
+
+- What is the operation or capability?
+- Who owns the data or entity?
+- How is the implementation separated from the interface?
+- When does this happen, and is timing unnecessarily coupled to the caller?
+- Where does this run, and is location unnecessarily coupled to the caller?
+- Why does this rule or policy exist, and can it be represented declaratively?
+
+Source: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.
+
+### Debugging checklist
+
+- Is the reported problem a direct result of the underlying defect, or merely a symptom?
+- Is the defect really in the compiler, operating system, or another platform component—or is it in the application? Treat likelihood as a starting point and prove the conclusion.
+- If you explained the problem in detail to a coworker, what would you say? Rubber-duck debugging can help make the model explicit.
+- If the suspect code passes its unit tests, are the tests complete enough? What happens with different data?
+- Do the conditions that caused this defect exist elsewhere in the system?
+
+Submitted locator: *The Pragmatic Programmer*, p. 98. The submitted note also references [Rubber Duck Debugging](https://rubberduckdebugging.com/).
+
+### Law of Demeter for functions
+
+An object's method should call only methods belonging to:
+
+- itself;
+- parameters passed to it;
+- objects it creates;
+- its component objects.
+
+Submitted locator: *The Pragmatic Programmer*, p. 141.
+
+### How to program deliberately
+
+- Stay aware of what you are doing.
+- Do not code blindfolded.
+- Proceed from a plan.
+- Rely only on reliable things.
+- Document assumptions.
+- Test assumptions as well as code.
+- Prioritize effort.
+- Do not be a slave to history.
+
+Submitted locator: *The Pragmatic Programmer*, p. 172.
+
+### When to refactor
+
+- A violation of the DRY principle is discovered.
+- Things could be made more orthogonal.
+- Knowledge improves.
+- Requirements evolve.
+- Performance needs improvement.
+
+Submitted locator: *The Pragmatic Programmer*, p. 185.
+
+### Cutting the Gordian knot
+
+When a problem appears impossible, ask:
+
+- Is there an easier way?
+- Am I solving the right problem?
+- Why is this a problem?
+- What makes it hard?
+- Must it be done this way?
+- Must it be done at all?
+
+Submitted locator: *The Pragmatic Programmer*, p. 212.
+
+### Aspects of testing
+
+- Unit testing.
+- Integration testing.
+- Validation and verification.
+- Resource exhaustion, errors, and recovery.
+- Performance testing.
+- Usability testing.
+- Testing the tests themselves.
+
+No page locator was included with this submitted checklist.
+
+## Submitted practices
+
+### Simplicity pass before implementation
+
+- Before building a long-lived feature, separate concerns that do not need to be tied together.
+- Prefer more small, straight, independent pieces over fewer pieces tied into a knot.
+- Name the parts representing problem complexity and those representing incidental complexity.
+
+### Complexity ledger
+
+- For meaningful design decisions, record the benefit, byproducts, what the choice ties together, and why the tradeoff is acceptable.
+- Revisit the ledger when the system becomes difficult to change or debug.
+
+### Quarantine state
+
+- Make mutable state rare, named, easy to find, and surrounded by a simpler interface.
+- Do not pass mutable references through the system when a stable value will do.
+
+### Disentangle during refactoring
+
+- Trace what is tied together, identify the separate concerns, and separate one concern at a time.
+- Refactoring should reduce what a reader must hold in mind rather than merely moving code into different files.
+
+Source for these submitted practices: Rich Hickey, [*Simple Made Easy*](https://www.youtube.com/watch?v=SxdOUGdseq4), Strange Loop 2011.