lgtm-specs 0.0.4

package/docs/meta/industry_best_practices.md

@@ -0,0 +1,555 @@
+# Engineering Best Practices & Master Rule List
+
+This document is the "Source of Truth" for all engineering standards enforced by LGTM. It groups principles by their intellectual lineage and provides primary source references.
+
+**Table of Contents**
+
+1. [SOLID Principles](#1-solid-principles)
+2. [A Philosophy of Software Design](#2-a-philosophy-of-software-design)
+3. [Universal Fundamentals](#3-universal-fundamentals)
+4. [Pragmatic Programmer & Code Health](#4-pragmatic-programmer--code-health)
+5. [Systems Theory & Dynamics](#5-systems-theory--dynamics)
+6. [Formal Methods & Correctness](#6-formal-methods--correctness)
+7. [Distributed Systems](#7-distributed-systems)
+8. [Classic Engineering Wisdom](#8-classic-engineering-wisdom)
+9. [Security Engineering](#9-security-engineering)
+10. [Testing & Verification](#10-testing--verification)
+11. [Observability & Operations](#11-observability--operations)
+12. [Performance & Efficiency](#12-performance--efficiency)
+13. [Data Engineering](#13-data-engineering)
+14. [Delivery & Evolution](#14-delivery--evolution)
+15. [Dependency Management](#15-dependency-management)
+16. [API Design](#16-api-design)
+17. [Privacy & Compliance](#17-privacy--compliance)
+18. [Operational Reliability](#18-operational-reliability)
+
+---
+
+# 1. SOLID Principles
+
+_Source: [Robert C. Martin (Uncle Bob)](https://en.wikipedia.org/wiki/SOLID)_
+A framework for managing dependencies and structural complexity in object-oriented design.
+
+## 1.1 Single Responsibility Principle (SRP)
+
+**Definition**: A module should have one, and only one, reason to change.
+
+- **Requirement**: A class handling business logic must NOT handle database queries directly.
+- **Requirement**: All methods in a class should operate on the same set of state variables (High Cohesion).
+- **Requirement**: Separate "Policy" (Business Rules) from "Mechanism" (IO/Frameworks).
+
+## 1.2 Open/Closed Principle (OCP)
+
+**Definition**: Software entities should be open for extension but closed for modification.
+
+- **Requirement**: Use interfaces or abstract classes to allow behavior changes.
+- **Requirement**: Do not modify stable classes to add features if Inheritance or Decorators can be used.
+- **Requirement**: Prefer injecting a Strategy object over adding `if/else` blocks for new cases.
+
+## 1.3 Liskov Substitution Principle (LSP)
+
+**Definition**: Subtypes must be substitutable for their base types without altering correctness.
+
+- **Requirement**: A subclass must accept the same inputs and guarantee the same post-conditions.
+- **Requirement**: A subclass must not throw exceptions that are not part of the parent's contract.
+
+## 1.4 Interface Segregation Principle (ISP)
+
+**Definition**: Clients should not be forced to depend on interfaces they do not use.
+
+- **Requirement**: Split "God Interfaces" (e.g., `IUserHandler`) into role-specific ones (`IUserReader`).
+- **Requirement**: Functions should accept the smallest interface possible (e.g., `func(Reader)` not `func(File)`).
+
+## 1.5 Dependency Inversion Principle (DIP)
+
+**Definition**: High-level modules should not depend on low-level modules. Both should depend on abstractions.
+
+- **Requirement**: Dependencies must be passed in (Dependency Injection), not instantiated internally.
+- **Requirement**: Imports in domain logic should point to `types/` or `interfaces/`, not `infrastructure/`.
+
+---
+
+# 2. A Philosophy of Software Design
+
+_Source: [John Ousterhout](https://web.stanford.edu/~ouster/cgi-bin/aposd.php)_
+A tactical approach to managing complexity by focusing on module depth and information hiding.
+
+## 2.1 Deep Modules
+
+**Definition**: Interfaces must be significantly simpler than their implementations.
+
+- **Requirement**: Maximize the amount of work done per line of interface code.
+- **Requirement**: Reject "Shallow Modules" that add layers (cognitive load) without hiding significant complexity.
+- **Requirement**: Reject pass-through methods that just delegate to another object with the same signature.
+
+## 2.2 Information Hiding
+
+**Definition**: Design decisions should be encapsulated within modules and hidden from the outside.
+
+- **Requirement**: Hide complex algorithms, data structures, and implementation details.
+- **Requirement**: Avoid "Information Leakage" where internal choices are exposed through the interface.
+
+## 2.3 General-Purpose vs. Special-Purpose
+
+**Definition**: Modules should be designed to be somewhat general-purpose to reduce the total number of modules.
+
+- **Requirement**: Ask "What is the simplest interface that could solve this _and_ similar future problems?"
+- **Requirement**: Avoid over-specialization that leads to a massive number of tiny, shallow classes.
+
+## 2.4 Defining Errors Out of Existence
+
+**Definition**: The best way to handle errors is to design APIs so the error condition is impossible or part of the normal flow.
+
+- **Requirement**: Use sensible defaults (e.g., empty string instead of error).
+- **Requirement**: Design interfaces so the "error case" is a valid branch of logic.
+
+## 2.5 Design Twice
+
+**Definition**: The first design is rarely the best. Always consider at least two distinct approaches.
+
+- **Requirement**: For significant changes, document at least one alternative considered and rejected.
+
+## 2.6 Comment the Why, not the How
+
+**Definition**: Comments should explain high-level intent and abstractions, not repeat the code.
+
+- **Requirement**: Comments must reside at the Interface level (Docstrings).
+- **Requirement**: Delete comments that merely restate the variable name or logic.
+
+---
+
+# 3. Universal Fundamentals
+
+_Source: Various / First Principles_
+Core axioms that transcend specific languages.
+
+## 3.1 Principle of Least Astonishment (POLA)
+
+_Source: [POLA Definition](https://en.wikipedia.org/wiki/Principle_of_least_astonishment)_
+**Definition**: The behavior of a component should match the user's reasonable expectations.
+
+- **Requirement**: Avoid "Magic" behavior (implicit side effects).
+- **Requirement**: Naming must strictly match behavior (`get()` should not mutate).
+
+## 3.2 Locality of Behavior (LoB)
+
+_Source: [htmx (Carson Gross)](https://htmx.org/essays/locality-of-behavior/)_
+**Definition**: The behavior of a unit of code should be as obvious as possible by looking only at that unit.
+
+- **Requirement**: Keep related code collocated.
+- **Requirement**: Avoid "Action at a Distance" (modifying global state from a deep subroutine).
+
+## 3.3 Orthogonality
+
+_Source: [The Pragmatic Programmer](https://en.wikipedia.org/wiki/The_Pragmatic_Programmer)_
+**Definition**: Changes in one part of the system should not affect unrelated parts.
+
+- **Requirement**: Decouple modules. A change to the UI rendering logic must not break the database query logic.
+- **Requirement**: Use pure functions where possible to eliminate side effects.
+
+## 3.4 Idempotency
+
+_Source: [API Design Principles](https://en.wikipedia.org/wiki/Idempotence)_
+**Definition**: An operation can be applied multiple times without changing the result beyond the initial application.
+
+- **Requirement**: Retries of failed operations must be safe.
+- **Requirement**: APIs modifying state should ideally be idempotent.
+
+## 3.5 Explicitness
+
+_Source: [Zen of Python](https://peps.python.org/pep-0020/)_
+**Definition**: Magic is the enemy of maintainability. Implicit behavior increases mental load.
+
+- **Requirement**: Explicit is better than implicit. No global state.
+- **Requirement**: Dependencies and side effects must be visible in signatures.
+
+---
+
+# 4. Pragmatic Programmer & Code Health
+
+_Source: [Hunt & Thomas](https://en.wikipedia.org/wiki/The_Pragmatic_Programmer) / [Atul Gawande](https://en.wikipedia.org/wiki/The_Checklist_Manifesto)_
+Tactical rules for maintaining code quality over time.
+
+## 4.1 The Boy Scout Rule
+
+_Source: [Robert C. Martin](https://en.wikipedia.org/wiki/Robert_C._Martin)_
+**Definition**: Always leave the code cleaner than you found it.
+
+- **Requirement**: Fix existing lint warnings and bad names in the immediate context of your change.
+
+## 4.2 Broken Windows Theory
+
+_Source: [Pragmatic Programmer](https://en.wikipedia.org/wiki/The_Pragmatic_Programmer)_
+**Definition**: Bad designs left unrepaired encourage more bad designs.
+
+- **Requirement**: Do not tolerate "hacks" in the core path. Fix or encapsulate immediately.
+
+## 4.3 Cognitive Limits (Batch Size)
+
+_Source: [SmartBear Analysis](https://smartbear.com/learn/code-review/best-practices-for-peer-code-review/)_
+**Definition**: Human review quality drops sharply as batch size increases.
+
+- **Requirement**: Pull Requests should stay under 400 lines of code.
+- **Requirement**: A single PR must tell a single, coherent story.
+
+## 4.4 The Checklist
+
+_Source: [The Checklist Manifesto](https://en.wikipedia.org/wiki/The_Checklist_Manifesto)_
+**Definition**: Rote verification should be offloaded to machines.
+
+- **Requirement**: Automate formatting, linting, and imports.
+
+---
+
+# 5. Systems Theory & Dynamics
+
+_Source: [Melvin Conway](https://en.wikipedia.org/wiki/Conway%27s_law) / [Jay Forrester](https://en.wikipedia.org/wiki/System_dynamics)_
+Understanding software development as a complex adaptive system.
+
+## 5.1 Shift Left
+
+_Source: [Industrial Dynamics](https://en.wikipedia.org/wiki/Shift-left_testing)_
+**Definition**: Verification activities should happen as early as possible.
+
+- **Requirement**: Perform dependency impact analysis before writing code.
+
+## 5.2 Socio-Technical Congruence
+
+_Source: [Conway's Law](https://en.wikipedia.org/wiki/Conway%27s_law)_
+**Definition**: Code structure must align with team communication structure.
+
+- **Requirement**: Flag tight coupling between modules owned by different teams.
+
+## 5.3 The Rework Cycle
+
+_Source: [System Dynamics Modeling](https://en.wikipedia.org/wiki/The_Mythical_Man-Month)_
+**Definition**: Hidden defects destroy velocity.
+
+- **Requirement**: Prioritize paying down technical debt (Refactoring) to keep velocity stable.
+
+---
+
+# 6. Formal Methods & Correctness
+
+_Source: [Type Theory](https://en.wikipedia.org/wiki/Type_theory) / [Jon Postel](https://en.wikipedia.org/wiki/Robustness_principle)_
+Ensuring code behaves correctly by construction.
+
+## 6.1 Safety by Design
+
+**Definition**: Illegal states should be unrepresentable.
+
+- **Requirement**: Use Algebraic Data Types (Unions) for state.
+- **Requirement**: Prefer immutable data structures.
+
+## 6.2 Command-Query Separation (CQS)
+
+_Source: [Bertrand Meyer](https://en.wikipedia.org/wiki/Command%E2%80%93query_separation)_
+**Definition**: Methods must either perform an action (Command) or return data (Query).
+
+- **Requirement**: A method returning a value should be "Pure" (no observable side effects).
+
+## 6.3 Postel's Law
+
+_Source: [Robustness Principle](https://en.wikipedia.org/wiki/Robustness_principle)_
+**Definition**: Be conservative in what you do, liberal in what you accept.
+
+- **Requirement**: Validate external inputs at the boundary.
+- **Requirement**: Return strictly-typed structures.
+
+---
+
+# 7. Distributed Systems
+
+_Source: [Eric Brewer](https://en.wikipedia.org/wiki/CAP_theorem) / [L. Peter Deutsch](https://en.wikipedia.org/wiki/Fallacies_of_distributed_computing)_
+Rules for code that crosses network boundaries.
+
+## 7.1 CAP & PACELC
+
+_Source: [CAP Theorem](https://en.wikipedia.org/wiki/CAP_theorem) / [PACELC](https://en.wikipedia.org/wiki/PACELC_theorem)_
+**Definition**: Distributed systems must explicitly choose between Consistency and Availability.
+
+- **Requirement**: Document the consistency model for every distributed component.
+
+## 7.2 Fallacies of Distributed Computing
+
+_Source: [The 8 Fallacies](https://en.wikipedia.org/wiki/Fallacies_of_distributed_computing)_
+**Definition**: False assumptions that L. Peter Deutsch and colleagues identified as the root of most distributed system failures.
+
+- **Requirement**: You must actively design mitigation for _each_ of these false assumptions:
+  1.  **The network is reliable.** (Mitigation: Retries, Acknowledgements)
+  2.  **Latency is zero.** (Mitigation: Batching, Parallelism, Caching)
+  3.  **Bandwidth is infinite.** (Mitigation: Compression, Binary Formats)
+  4.  **The network is secure.** (Mitigation: TLS, Zero Trust, Authentication)
+  5.  **Topology doesn't change.** (Mitigation: Service Discovery, DNS)
+  6.  **There is one administrator.** (Mitigation: Decoupling, Versioning, Permissions)
+  7.  **Transport cost is zero.** (Mitigation: Serialization efficiency)
+  8.  **The network is homogeneous.** (Mitigation: Standards-based protocols, Interoperability)
+
+---
+
+# 8. Classic Engineering Wisdom
+
+_Source: [Extreme Programming](https://en.wikipedia.org/wiki/Extreme_programming) / [Lockheed Skunk Works](https://en.wikipedia.org/wiki/KISS_principle)_
+
+## 8.1 KISS (Keep It Simple, Stupid)
+
+_Source: [Kelly Johnson](https://en.wikipedia.org/wiki/KISS_principle)_
+**Definition**: Complexity is a cost; avoid it unless justified by value.
+
+- **Requirement**: Do not build a factory for a single implementation.
+
+## 8.2 YAGNI (You Aren't Gonna Need It)
+
+_Source: [YAGNI Definition](https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it)_
+**Definition**: Do not implement functionality until it is necessary.
+
+- **Requirement**: Remove unused functions, variables, or files (Dead Code).
+- **Requirement**: Reject "Extensibility Hooks" that have no immediate use case.
+
+## 8.3 DRY (Don't Repeat Yourself)
+
+_Source: [The Pragmatic Programmer](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself)_
+**Definition**: Every piece of knowledge must have a single, authoritative representation.
+
+- **Requirement**: Data schemas must be defined once (Single Source of Truth).
+- **Exception**: Tolerate "Accidental Duplication" if the reasons for change differ.
+
+## 8.4 Law of Demeter
+
+_Source: [Law of Demeter](https://en.wikipedia.org/wiki/Law_of_Demeter)_
+**Definition**: A module should not know about the innards of the objects it manipulates.
+
+- **Requirement**: Avoid method chaining that traverses structure (`a.b().c()`).
+
+---
+
+# 9. Security Engineering
+
+_Source: [OWASP](https://owasp.org/www-project-top-ten/) / [Saltzer and Schroeder](https://en.wikipedia.org/wiki/Saltzer_and_Schroeder%27s_design_principles)_
+
+## 9.1 Principle of Least Privilege
+
+**Definition**: A subject should be given only those privileges needed for it to complete its task.
+
+- **Requirement**: Services must run with minimal IAM permissions.
+- **Requirement**: Database users must not have `DROP` privileges unless required for migrations.
+
+## 9.2 Defense in Depth
+
+**Definition**: Redundant security controls to mitigate failure of a single control.
+
+- **Requirement**: Do not rely solely on the firewall; authenticate internally (Zero Trust).
+- **Requirement**: Validate input at both the API Gateway and the Service level.
+
+## 9.3 Secure Defaults
+
+**Definition**: Systems should be secure "out of the box".
+
+- **Requirement**: Ports should be closed by default.
+- **Requirement**: Passwords must be hashed (bcrypt/argon2) by default.
+
+## 9.4 Input Validation
+
+**Definition**: Never trust external input.
+
+- **Requirement**: Validate logic at the earliest entry point.
+- **Requirement**: Use allow-lists (valid chars) over deny-lists.
+
+---
+
+# 10. Testing & Verification
+
+_Source: [The Test Pyramid](https://martinfowler.com/articles/practical-test-pyramid.html)_
+
+## 10.1 The Test Pyramid
+
+**Definition**: Balance test types for speed and confidence (Unit > Integration > E2E).
+
+- **Requirement**: Logic-heavy modules must have unit tests covering all branches.
+- **Requirement**: Integration tests verify the contract between modules.
+
+## 10.2 Determinism & Isolation
+
+**Definition**: Tests must produce the same result every run, regardless of order or environment.
+
+- **Requirement**: Mock network calls and randomness (Time, UUIDs) in unit tests.
+- **Requirement**: Tests must clean up their own data (no leaking state).
+
+## 10.3 Property-Based Testing
+
+**Definition**: Verify general properties (invariants) over generated inputs rather than specific examples.
+
+- **Requirement**: Use fuzzing/property testing for parsers and critical logic.
+
+---
+
+# 11. Observability & Operations
+
+_Source: [Google SRE Book](https://sre.google/sre-book/monitoring-distributed-systems/)_
+
+## 11.1 Telemetry by Design
+
+**Definition**: You cannot operate what you cannot see.
+
+- **Requirement**: Every service must emit standard metrics (Latency, Traffic, Errors, Saturation).
+- **Requirement**: Use structured logging (JSON) with correlation IDs for tracing.
+
+## 11.2 Alert Hygiene
+
+**Definition**: Alerts should be actionable and urgent.
+
+- **Requirement**: Alert on symptoms (User Pain), not causes (High CPU).
+- **Requirement**: Every alert must have a link to a Runbook.
+
+---
+
+# 12. Performance & Efficiency
+
+_Source: [Knuth](https://en.wikipedia.org/wiki/Donald_Knuth) / [Brendan Gregg](https://www.brendangregg.com/)_
+
+## 12.1 Algorithmic Complexity (Big O)
+
+**Definition**: Understanding how resource usage scales with input size.
+
+- **Requirement**: Avoid N+1 query problems in loops.
+- **Requirement**: Identify and mitigate O(n^2) or worse algorithms in hot paths.
+
+## 12.2 Caching Strategy
+
+**Definition**: Storing results to avoid repeated work.
+
+- **Requirement**: Every cache must have an eviction policy (TTL/LRU).
+- **Requirement**: Handle cache stampedes (locking or probabilistic expiry).
+
+## 12.3 Profiling First
+
+**Definition**: Optimization without measurement is premature.
+
+- **Requirement**: Do not optimize code without a profile showing it is a bottleneck.
+
+---
+
+# 13. Data Engineering
+
+_Source: [Database Reliability Engineering](https://shop.oreilly.com/product/0636920059714.do)_
+
+## 13.1 Schema Evolution
+
+**Definition**: Data outlives code. Schemas must evolve without downtime.
+
+- **Requirement**: Migrations must be backward-compatible (Add column -> Deploy Code -> Drop column).
+- **Requirement**: Avoid `SELECT *` to allow schema expansion.
+
+## 13.2 Data Integrity
+
+**Definition**: Ensuring accuracy and consistency of data.
+
+- **Requirement**: Use Foreign Keys and Constraints to enforce integrity at the DB level.
+- **Requirement**: Define clear transactional boundaries (ACID) for critical mutations.
+
+---
+
+# 14. Delivery & Evolution
+
+_Source: [Accelerate (DORA)](https://dora.dev/)_
+
+## 14.1 Feature Flags
+
+**Definition**: Decoupling deployment from release.
+
+- **Requirement**: Wrap new features in flags to allow safe rollback and incremental rollout.
+- **Requirement**: Delete flags once the feature is stable (Flag Debt).
+
+## 14.2 Semantic Versioning
+
+**Definition**: Version numbers convey meaning about compatibility.
+
+- **Requirement**: Breaking changes must bump the Major version.
+- **Requirement**: Public APIs must be stable within a Major version.
+
+## 14.3 Deprecation Policy
+
+**Definition**: Managing the end-of-life of features.
+
+- **Requirement**: Mark deprecated features with a clear warning and a removal date.
+- **Requirement**: Provide an automated migration path where possible.
+
+---
+
+# 15. Dependency Management
+
+_Source: [Supply Chain Levels for Software Artifacts (SLSA)](https://slsa.dev/)_
+
+## 15.1 Dependency Hygiene
+
+**Definition**: Minimizing risk from external code.
+
+- **Requirement**: Pin versions using lockfiles.
+- **Requirement**: Regularly audit for security vulnerabilities (e.g., `npm audit`).
+
+## 15.2 Supply Chain Integrity
+
+**Definition**: Ensuring build artifacts are trustworthy.
+
+- **Requirement**: Generate Software Bill of Materials (SBOMs).
+- **Requirement**: Verify checksums of downloaded packages.
+
+---
+
+# 16. API Design
+
+_Source: [Microsoft REST API Guidelines](https://github.com/microsoft/api-guidelines)_
+
+## 16.1 Contract Stability
+
+**Definition**: An API is a promise.
+
+- **Requirement**: Do not change public signatures without a major version bump.
+- **Requirement**: Use "Consumer-Driven Contracts" to verify integrations.
+
+## 16.2 Versioning Strategy
+
+**Definition**: Managing change over time.
+
+- **Requirement**: Use explicit versioning in URL or Header (`/v1/resource`).
+- **Requirement**: Maintain at least one previous version for a deprecation period.
+
+---
+
+# 17. Privacy & Compliance
+
+_Source: [GDPR](https://gdpr-info.eu/) / [Privacy by Design](https://en.wikipedia.org/wiki/Privacy_by_design)_
+
+## 17.1 Data Minimization
+
+**Definition**: Collect only what is absolutely necessary.
+
+- **Requirement**: Do not store PII (Personally Identifiable Information) unless critical.
+- **Requirement**: Define retention policies for all data.
+
+## 17.2 PII Handling
+
+**Definition**: Protecting user data.
+
+- **Requirement**: Encrypt PII at rest and in transit.
+- **Requirement**: Log anonymized IDs, never raw user data (e.g., email).
+
+---
+
+# 18. Operational Reliability
+
+_Source: [Netflix Engineering](https://netflixtechblog.com/)_
+
+## 18.1 Backpressure & Load Shedding
+
+**Definition**: Protecting the system from overload.
+
+- **Requirement**: Reject excess traffic gracefully (HTTP 429) rather than crashing.
+- **Requirement**: Implement client-side exponential backoff.
+
+## 18.2 Chaos Engineering
+
+**Definition**: Proactive testing of failure modes.
+
+- **Requirement**: Verify system behavior when dependencies go down.
+- **Requirement**: Test rollback procedures regularly.

package/docs/meta/languages/README.md

@@ -0,0 +1,8 @@
+# Language Standards (Meta)
+
+This directory contains the "Source of Truth" meta-documents for specific languages. These documents aggregate knowledge from official style guides, engineering blogs, and seminal books.
+
+## Index
+
+- **[Go](go/README.md)**: Based on _Effective Go_ and _btcwallet_.
+- **[TypeScript](typescript/README.md)**: Based on _Total TypeScript_ and _Google Style Guide_.

package/docs/meta/languages/go/01-concurrency.md

@@ -0,0 +1,37 @@
+# Concurrency Architecture (The Actor Model)
+
+**Source**: [btcwallet Engineering Guide](https://github.com/btcsuite/btcwallet/blob/master/docs/developer/ENGINEERING_GUIDE.md)
+
+## 1. The Core Philosophy
+
+> "Do not communicate by sharing memory; instead, share memory by communicating."
+
+Instead of protecting shared state with complex locks (which lead to deadlocks and race conditions), we isolate state within a single, long-running goroutine (the "Actor"). This Actor owns its data exclusively and processes requests sequentially via channels.
+
+## 2. Patterns
+
+### The Pipeline
+
+Break complex processing into linear stages.
+
+- **Structure**: `Source -> Stage A -> Stage B -> Sink`
+- **Example**: Reading a file, parsing JSON, validating data, and saving to DB should be separate stages connected by channels.
+
+### Fan-Out / Fan-In
+
+Parallelize work by distributing it to a pool of workers.
+
+- **Fan-Out**: A distributor sends jobs to `N` worker goroutines.
+- **Fan-In**: A single collector aggregates results from the workers.
+- **Constraint**: Always use a bounded channel or a semaphore to prevent unbounded concurrency.
+
+## 3. Lifecycle Safety
+
+**Rule**: Never start a goroutine without knowing how it will stop.
+
+- **Mechanism**: Every long-running loop must check `ctx.Done()` or a `quit` channel.
+- **Anti-Pattern**: `go func() { for { ... } }()` (This is a leak).
+
+## 4. Modern Patterns (Go 1.22+)
+
+- **Loop Variables**: Go 1.22+ fixed the loop variable capture bug. Do NOT use `v := v` inside loops anymore.

package/docs/meta/languages/go/02-api-design.md

@@ -0,0 +1,30 @@
+# API & Package Design
+
+**Source**: [btcwallet Engineering Guide](https://github.com/btcsuite/btcwallet/blob/master/docs/developer/ENGINEERING_GUIDE.md)
+
+## 1. Clean Packages
+
+- **Naming**: A package name must describe _what it provides_, not _what it contains_.
+  - **Bad**: `utils`, `common`, `helpers` (Buckets of junk).
+  - **Good**: `cryptography`, `httpclient`, `auth`.
+- **Structure**: Use `internal/` for any code that is not part of your public stability contract.
+
+## 2. Interface Design
+
+**Rule**: "Accept Interfaces, Return Structs."
+
+- **Why**: Accepting an interface allows the caller to pass any implementation (mock, file, network). Returning a struct allows you to add methods to the result later without breaking consumers.
+- **Example**:
+
+  ```go
+  // Bad: Returns an interface, locking the implementation
+  func NewStore() Storage { ... }
+
+  // Good: Returns a concrete type, accepts an interface
+  func Save(w io.Writer, data []byte) { ... }
+  ```
+
+## 3. Documentation (Godoc)
+
+- **Requirement**: Every exported symbol must have a comment starting with the symbol name.
+- **Style**: Explain _why_, not just _what_. "Returns ErrNotFound" is better than "Returns error."

package/docs/meta/languages/go/03-resilience.md

@@ -0,0 +1,27 @@
+# Resilience Patterns
+
+**Source**: [btcwallet Engineering Guide](https://github.com/btcsuite/btcwallet/blob/master/docs/developer/ENGINEERING_GUIDE.md)
+
+## 1. Context Propagation ("The Red Thread")
+
+Every function that performs I/O or long-running work **MUST** accept `context.Context` as its first argument.
+
+- **Usage**: Use it for timeouts, deadlines, and cancellation.
+- **Group Management**: Use `golang.org/x/sync/errgroup` to manage a set of goroutines. If one fails, the context is canceled, and all others abort.
+
+## 2. Circuit Breakers & Rate Limiting
+
+- **Circuit Breakers**: If a dependency is down, fail fast. Do not wait for a 30s timeout on every request.
+- **Rate Limiting**: Protect your own resources. Reject requests if you are overloaded (`golang.org/x/time/rate`).
+
+## 3. Retry with Backoff
+
+Never retry immediately in a loop (Thundering Herd).
+
+- **Requirement**: Use exponential backoff (e.g., 1s, 2s, 4s) with jitter.
+
+## 4. Observability (Slog)
+
+- **Standard**: Use `log/slog` (Go 1.21+).
+- **Structure**: Log machine-readable key-values, not formatted strings.
+- **Levels**: `Info` (State change), `Error` (Actionable), `Debug` (Granular).

package/docs/meta/languages/go/04-errors.md

@@ -0,0 +1,27 @@
+# Error Handling
+
+**Source**: [btcwallet Engineering Guide](https://github.com/btcsuite/btcwallet/blob/master/docs/developer/ENGINEERING_GUIDE.md)
+
+## 1. Contextual Wrapping
+
+Never return a raw error from a dependency. The caller needs to know _where_ and _why_ it failed.
+
+- **Bad**: `return err`
+- **Good**: `return fmt.Errorf("failed to parse config file %s: %w", filename, err)`
+
+## 2. Sentinel Errors
+
+Define specific errors as variables so callers can check for them using `errors.Is`.
+
+- **Example**: `var ErrUserNotFound = errors.New("user not found")`
+
+## 3. Zero Errors
+
+Design APIs where errors are impossible for common cases.
+
+- **Pattern**: Instead of returning an error on a cache miss, return `(value, found)` boolean.
+
+## 4. Modern Patterns
+
+- **Check**: Use `errors.Is(err, Target)` and `errors.As(err, &Target)`. Never use `==` or type assertions on errors directly.
+- **Aggregation**: Use `errors.Join(err1, err2)` (Go 1.20+) for defer cleanup errors.