diff --git a/QUESTION-WHY.md b/QUESTION-WHY.md new file mode 100644 index 0000000..f80c98d --- /dev/null +++ b/QUESTION-WHY.md @@ -0,0 +1,174 @@ +# Why GitHub Minimum Intelligence? + +## Because intelligence without memory is theater + +Most AI tooling for software still behaves like a talented tourist: useful, occasionally brilliant, but fundamentally outside the project’s lived reality. It can infer patterns from code snapshots, but it does not inherently inhabit the system where decisions are made, contested, revised, and shipped. + +GitHub Minimum Intelligence begins from a stricter thesis: if software is maintained through repository artifacts, then AI collaboration should be anchored to those same artifacts. The system is not trying to “add AI to coding” in the abstract. It is trying to solve a concrete systems problem: **context discontinuity between model output and team process**. + +In plain terms, the “why” is this: + +> Teams do not merely need generated code. They need generated code that remains accountable to history, intent, governance, and ownership. + +--- + +## Why this exists: to close the context gap + +`THE-REPO-IS-THE-MIND.md` describes the core gap precisely: many tools can read and patch code, but they do not carry durable memory of tradeoffs, false starts, and prior reasoning. Without that memory, collaboration resets to zero at every interaction. + +Minimum Intelligence answers by relocating the center of gravity. Instead of externalizing AI context into proprietary services, it internalizes context into repository-native primitives: + +- commits, +- issues, +- workflow definitions, +- persona/configuration files, +- branch and permission rules. + +That is not an aesthetic preference. It is an architectural response to entropy. + +--- + +## Why repository-native beats platform-native + +A platform-native assistant usually asks you to trust a new control plane. +A repository-native assistant asks you to reuse the control plane you already operate. + +This difference cascades into practical advantages: + +1. **Governance continuity** + Review policy, CODEOWNERS, protected branches, and audit expectations do not need translation into a separate product’s semantics. + +2. **Operational continuity** + The agent runs where CI already runs. The artifacts are the same artifacts your team already monitors. + +3. **Cognitive continuity** + Developers do not need to remember “where truth lives.” Truth stays in the repo. + +When adoption friction is reduced, disciplined use is more likely. And disciplined use is the precondition for any AI system that claims to improve engineering quality over time. + +--- + +## Why “minimum” is an ambition, not a compromise + +“Minimum Intelligence” is easy to misread as reduced capability. In practice, it means reducing **new infrastructure assumptions**: + +- no mandatory external memory store, +- no opaque hosted orchestration requirement, +- no hidden behavioral layer you cannot diff. + +This minimalism is strategic. Every additional black box can weaken trust, reproducibility, and reversibility. By minimizing moving parts, the framework maximizes inspectability. + +A useful way to frame it: + +- less novelty in control surfaces, +- more novelty in how existing surfaces are composed. + +That is often where robust infrastructure progress happens. + +--- + +## Why sovereignty matters more than convenience + +The “why” is also political in the infrastructure sense. + +When AI collaboration depends on a vendor-managed plane, your repository risks becoming a mere synchronization endpoint to someone else’s system of record. Minimum Intelligence inverts that relationship: the repository remains first-class, and AI is subordinate tooling. + +This preserves three forms of sovereignty: + +- **Technical sovereignty**: pin, fork, replace dependencies. +- **Process sovereignty**: keep review and change control in established workflows. +- **Data sovereignty**: avoid unnecessary movement of sensitive context into external persistence layers. + +Convenience can be purchased later. Lost control is harder to recover. + +--- + +## Why auditability is not optional for AI development work + +In normal software delivery, consequential actions require traceability. +AI should not be a carveout. + +Repository-native execution makes consequential AI behavior legible by default: + +- changes become commits, +- rationale and iteration appear in issue threads, +- behavioral rules exist as files, +- regressions can be bisected, +- bad decisions can be reverted. + +This is more than compliance theater. It is how teams learn. If failure is attributable and inspectable, failure can become institutional memory instead of recurring confusion. + +--- + +## Why identity-as-code changes collaboration quality + +A subtle but powerful design choice in this repo is that agent persona and constraints are checked in. That means the “assistant’s personality” is no longer mystical product behavior; it is a maintainable artifact. + +The consequences are significant: + +- teams can debate tone and risk posture explicitly, +- behavior changes can be code-reviewed, +- alternative instruction sets can be branch-tested, +- unwanted drift can be reverted quickly. + +In short: AI behavior becomes part of engineering management, not merely end-user preference. + +--- + +## Why stateless runs plus stateful history is the right tradeoff + +The framework favors stateless execution processes that reconstruct state from durable repo artifacts. This avoids brittle dependence on warm conversational sessions and creates asynchronous resilience. + +If someone returns weeks later, continuity is still available because continuity is encoded in history, not hidden in runtime memory. + +That tradeoff mirrors one of software engineering’s oldest lessons: ephemeral compute should be cheap; durable state should be explicit. + +--- + +## Why this model scales with team maturity + +Minimum Intelligence does not guarantee quality by itself. It guarantees that quality work can compound when teams practice memory hygiene: + +- clear issue framing, +- explicit constraints, +- disciplined commit messages, +- reviewed policy files, +- documented reversals and exceptions. + +In immature processes, AI can amplify noise. +In mature processes, AI can amplify throughput without erasing judgment. + +The framework’s real value is that it routes both outcomes into inspectable history, making process improvement possible. + +--- + +## Why this is likely a durable direction + +The strongest infrastructure patterns usually share three properties: + +- composable with existing systems, +- inspectable under failure, +- portable across vendors. + +Repository-native intelligence meets all three better than most chat-centric models. + +As model quality continues to rise, the competitive question will shift from “who can generate the most plausible patch” to “whose generated work remains governable in real organizational conditions.” + +That is precisely the question this project is built to answer. + +--- + +## Final answer: why? + +GitHub Minimum Intelligence exists because software teams need more than fast model output. They need a collaboration model where AI action is: + +- grounded in repository reality, +- constrained by explicit policy, +- attributable through normal tooling, +- and evolvable through the same review loops as code. + +Its central claim is pragmatic: + +**Put intelligence where engineering memory already lives.** + +Do that, and AI becomes less like an external oracle and more like a disciplined participant in the system you already trust to build, govern, and ship software.