mindforge-cc 8.1.0 → 8.2.0

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/skills/mindforge-system-architecture/examples.md

@@ -0,0 +1,120 @@
+# Architecture Examples
+
+Concrete good/bad examples for each core principle in SKILL.md.
+
+---
+
+## Boundaries at Real Differences
+
+**Good** - Meaningful boundary:
+```
+# Users and Billing are separate bounded contexts
+# - Different teams own them
+# - Different change cadences (users: weekly, billing: quarterly)
+# - Different compliance requirements
+
+src/
+  users/           # User management domain
+    models.py
+    services.py
+    api.py
+  billing/         # Billing domain
+    models.py
+    services.py
+    api.py
+  shared/          # Truly shared utilities
+    auth.py
+```
+
+**Bad** - Ceremony without purpose:
+```
+# UserService → UserRepository → UserRepositoryImpl
+# ...when you'll never swap the database
+
+src/
+  interfaces/
+    IUserRepository.py      # One implementation exists
+  repositories/
+    UserRepositoryImpl.py   # Wraps SQLAlchemy, which is already a repository
+  services/
+    UserService.py          # Just calls the repository
+```
+
+---
+
+## Dependencies Flow Inward
+
+**Good** - Clear dependency direction:
+```
+# Dependency flows inward: infrastructure → application → domain
+
+domain/           # Pure business logic, no imports from outer layers
+  order.py        # Order entity with business rules
+
+application/      # Use cases, orchestrates domain
+  place_order.py  # Imports from domain/, not infrastructure/
+
+infrastructure/   # External concerns
+  postgres.py     # Implements persistence, imports from application/
+  stripe.py       # Implements payments
+```
+
+---
+
+## Follow the Data
+
+**Good** - Obvious data flow:
+```
+Request → Validate → Transform → Store → Respond
+
+# Each step is a clear function/module:
+api/routes.py        # Request enters
+validators.py        # Validation
+transformers.py      # Business logic transformation
+repositories.py      # Storage
+serializers.py       # Response shaping
+```
+
+---
+
+## Design for Failure
+
+**Good** - Failure-aware design with compensation:
+```python
+class OrderService:
+    def place_order(self, order: Order) -> Result:
+        inventory = self.inventory.reserve(order.items)
+        if inventory.failed:
+            return Result.failure("Items unavailable", retry=False)
+
+        payment = self.payments.charge(order.total)
+        if payment.failed:
+            self.inventory.release(inventory.reservation_id)  # Compensate
+            return Result.failure("Payment failed", retry=True)
+
+        return Result.success(order)
+```
+
+---
+
+## Design for Operations
+
+**Good** - Observable architecture:
+```python
+@trace
+def handle_request(request):
+    log.info("Processing", request_id=request.id, user=request.user_id)
+    try:
+        result = process(request)
+        log.info("Completed", request_id=request.id, result=result.status)
+        return result
+    except Exception as e:
+        log.error("Failed", request_id=request.id, error=str(e),
+                  context=request.to_dict())  # Full context for replay
+        raise
+```
+
+Key elements:
+- Every request gets a correlation ID
+- Every service logs with that ID
+- Every error includes full context for reproduction

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/skills/mindforge-system-architecture/scaling-checklist.md

@@ -0,0 +1,76 @@
+# Scaling Checklist
+
+Concrete techniques for when the complexity checklist in SKILL.md confirms scale is a real problem. Apply in order - each level solves the previous level's bottleneck.
+
+---
+
+## Level 0: Optimize First
+
+Before adding infrastructure, exhaust these:
+
+- [ ] Database queries have proper indexes
+- [ ] N+1 queries eliminated
+- [ ] Connection pooling configured
+- [ ] Slow endpoints profiled and optimized
+- [ ] Static assets served via CDN
+
+## Level 1: Read-Heavy
+
+**Symptom**: Database reads are the bottleneck.
+
+| Technique | When | Trade-off |
+|-----------|------|-----------|
+| Application cache (in-memory) | Small, frequently accessed data | Stale data, memory pressure |
+| Redis/Memcached | Shared cache across instances | Network hop, cache invalidation complexity |
+| Read replicas | High read volume, slight staleness OK | Replication lag, eventual consistency |
+| CDN | Static or semi-static content | Cache invalidation delay |
+
+## Level 2: Write-Heavy
+
+**Symptom**: Database writes or processing are the bottleneck.
+
+| Technique | When | Trade-off |
+|-----------|------|-----------|
+| Async task queue (Celery, SQS) | Work can be deferred | Eventual consistency, failure handling |
+| Write-behind cache | Batch frequent writes | Data loss risk on crash |
+| Event streaming (Kafka) | Multiple consumers of same data | Operational complexity, ordering guarantees |
+| CQRS | Reads and writes have diverged significantly | Two models to maintain |
+
+## Level 3: Traffic Spikes
+
+**Symptom**: Individual instances can't handle peak load.
+
+| Technique | When | Trade-off |
+|-----------|------|-----------|
+| Horizontal scaling + load balancer | Stateless services | Session management, deploy complexity |
+| Auto-scaling | Unpredictable traffic patterns | Cold start latency, cost spikes |
+| Rate limiting | Protect against abuse/spikes | Legitimate users may be throttled |
+| Circuit breakers | Downstream services degrade | Partial functionality during failures |
+
+## Level 4: Data Growth
+
+**Symptom**: Single database can't hold or query all the data efficiently.
+
+| Technique | When | Trade-off |
+|-----------|------|-----------|
+| Table partitioning | Time-series or naturally partitioned data | Query complexity, partition management |
+| Archival / cold storage | Old data rarely accessed | Access latency for archived data |
+| Database sharding | Partitioning insufficient, clear shard key exists | Cross-shard queries, operational burden |
+| Search index (Elasticsearch) | Full-text or complex queries on large datasets | Index lag, another system to operate |
+
+## Level 5: Multi-Region
+
+**Symptom**: Users are geographically distributed, latency matters.
+
+| Technique | When | Trade-off |
+|-----------|------|-----------|
+| CDN + edge caching | Static/semi-static content | Cache invalidation |
+| Read replicas per region | Read-heavy, slight staleness OK | Replication lag |
+| Active-passive failover | Disaster recovery | Failover time, cost of standby |
+| Active-active multi-region | True global low-latency required | Conflict resolution, extreme complexity |
+
+---
+
+## Decision Rule
+
+Always start at Level 0. Move to the next level only when you have **measured evidence** that the current level is insufficient. Skipping levels is how you end up with Kafka for a TODO app.

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/skills/mindforge-tdd/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: tdd
+description: Strict TDD workflow (Red-Green-Refactor).
+---
+
+---
+name: tdd
+description: Test-driven development with red-green-refactor loop. Use when user wants to build features or fix bugs using TDD, mentions "red-green-refactor", wants integration tests, or asks for test-first development.
+---
+
+# Test-Driven Development
+
+## Philosophy
+
+**Core principle**: Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.
+
+**Good tests** are integration-style: they exercise real code paths through public APIs. They describe _what_ the system does, not _how_ it does it. A good test reads like a specification - "user can checkout with valid cart" tells you exactly what capability exists. These tests survive refactors because they don't care about internal structure.
+
+**Bad tests** are coupled to implementation. They mock internal collaborators, test private methods, or verify through external means (like querying a database directly instead of using the interface). The warning sign: your test breaks when you refactor, but behavior hasn't changed. If you rename an internal function and tests fail, those tests were testing implementation, not behavior.
+
+See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines.
+
+## Anti-Pattern: Horizontal Slices
+
+**DO NOT write all tests first, then all implementation.** This is "horizontal slicing" - treating RED as "write all tests" and GREEN as "write all code."
+
+This produces **crap tests**:
+
+- Tests written in bulk test _imagined_ behavior, not _actual_ behavior
+- You end up testing the _shape_ of things (data structures, function signatures) rather than user-facing behavior
+- Tests become insensitive to real changes - they pass when behavior breaks, fail when behavior is fine
+- You outrun your headlights, committing to test structure before understanding the implementation
+
+**Correct approach**: Vertical slices via tracer bullets. One test → one implementation → repeat. Each test responds to what you learned from the previous cycle. Because you just wrote the code, you know exactly what behavior matters and how to verify it.
+
+```
+WRONG (horizontal):
+  RED:   test1, test2, test3, test4, test5
+  GREEN: impl1, impl2, impl3, impl4, impl5
+
+RIGHT (vertical):
+  RED→GREEN: test1→impl1
+  RED→GREEN: test2→impl2
+  RED→GREEN: test3→impl3
+  ...
+```
+
+## Workflow
+
+### 1. Planning
+
+Before writing any code:
+
+- [ ] Confirm with user what interface changes are needed
+- [ ] Confirm with user which behaviors to test (prioritize)
+- [ ] Identify opportunities for [deep modules](deep-modules.md) (small interface, deep implementation)
+- [ ] Design interfaces for [testability](interface-design.md)
+- [ ] List the behaviors to test (not implementation steps)
+- [ ] Get user approval on the plan
+
+Ask: "What should the public interface look like? Which behaviors are most important to test?"
+
+**You can't test everything.** Confirm with the user exactly which behaviors matter most. Focus testing effort on critical paths and complex logic, not every possible edge case.
+
+### 2. Tracer Bullet
+
+Write ONE test that confirms ONE thing about the system:
+
+```
+RED:   Write test for first behavior → test fails
+GREEN: Write minimal code to pass → test passes
+```
+
+This is your tracer bullet - proves the path works end-to-end.
+
+### 3. Incremental Loop
+
+For each remaining behavior:
+
+```
+RED:   Write next test → fails
+GREEN: Minimal code to pass → passes
+```
+
+Rules:
+
+- One test at a time
+- Only enough code to pass current test
+- Don't anticipate future tests
+- Keep tests focused on observable behavior
+
+### 4. Refactor
+
+After all tests pass, look for [refactor candidates](refactoring.md):
+
+- [ ] Extract duplication
+- [ ] Deepen modules (move complexity behind simple interfaces)
+- [ ] Apply SOLID principles where natural
+- [ ] Consider what new code reveals about existing code
+- [ ] Run tests after each refactor step
+
+**Never refactor while RED.** Get to GREEN first.
+
+## Checklist Per Cycle
+
+```
+[ ] Test describes behavior, not implementation
+[ ] Test uses public interface only
+[ ] Test would survive internal refactor
+[ ] Code is minimal for this test
+[ ] No speculative features added
+```

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/skills/mindforge-tdd/deep-modules.md

@@ -0,0 +1,21 @@
+# Deep Modules in TDD
+
+Deep modules are those with complex internal logic but a simple, stable interface. In TDD, our goal is to test the **depth** of the logic through the **surface** of the interface.
+
+## Principles
+
+### 1. Test behavior, not implementation
+- Write tests against the public API of the module.
+- Avoid testing private methods or internal state directly.
+- If the internal logic is too complex to test through the public API, the module might be **too deep** or the interface **too narrow**.
+
+### 2. Isolate complexity
+- Use "Socialable Tests" for internal helper classes that are tightly coupled.
+- Use "Solitary Tests" (with mocks) for external dependencies (DB, API, etc.).
+
+### 3. Handle state transitions
+- Deep modules often manage complex state machines.
+- Use TDD to map out every valid (and invalid) state transition.
+
+## Strategy: The "Opaque Box" Approach
+Treat the module as an opaque box. Feed it inputs and verify outputs/side-effects. If the logic inside changes but the behavior remains the same, your tests should **not** break.

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/skills/mindforge-tdd/interface-design.md

@@ -0,0 +1,22 @@
+# Interface Design through TDD
+
+TDD is your best tool for designing clean, usable interfaces. By writing the test first, you are the **first consumer** of your own API.
+
+## Design Signals from Tests
+
+### "This test is too hard to setup"
+- **Signal**: Your class has too many dependencies or is doing too much (violating SRP).
+- **Fix**: Break the class into smaller, more focused components.
+
+### "I have to mock 5 things just to test one method"
+- **Signal**: Excessive coupling.
+- **Fix**: Use Dependency Injection and define clearer boundaries.
+
+### "I don't know what to name this test"
+- **Signal**: The behavior is ill-defined or the module has "Identity Crisis".
+- **Fix**: Re-evaluate the purpose of the component.
+
+## Best Practices
+- **Prefer Composition over Inheritance**: Tests are much easier to write for composed objects.
+- **Keep Interfaces Narrow**: Only expose what is absolutely necessary for the consumer (and the test).
+- **Return Meaningful Values**: Avoid `void` where possible; returning results makes assertion-based testing natural.

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/skills/mindforge-tdd/mocking.md

@@ -0,0 +1,24 @@
+# Mocking Strategies
+
+Mocking is a double-edged sword. Used correctly, it isolates your code. Used poorly, it creates brittle tests that break with every refactor.
+
+## When to Mock
+- **External Systems**: Databases, File Systems, Network APIs, 3rd-party libraries.
+- **Non-Deterministic Logic**: Time (`Date.now()`), Random numbers, GUID generation.
+- **Expensive Operations**: Heavy computations or long-running tasks that would slow down the TDD loop.
+
+## What NOT to Mock
+- **Value Objects**: Objects that only hold data.
+- **Internal Helpers**: If a helper is part of the module's logic, let the test exercise it ("Socialable Testing").
+- **Language Features**: Don't mock standard library functions unless necessary for environment isolation.
+
+## The Mocking Traps
+
+### 1. The "Mirror" Trap
+- **Problem**: Mocking internal calls so closely that the test just mirrors the implementation code.
+- **Result**: You can't refactor without breaking the test.
+- **Fix**: Assert on final outcomes or side-effects, not inner method calls.
+
+### 2. The "Over-Mocking" Trap
+- **Problem**: Mocking so many things that you aren't actually testing your code.
+- **Fix**: Use **Fakes** (real implementations of interfaces, e.g., `InMemoryDatabase`) over Mocks where possible.

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/skills/mindforge-tdd/refactoring.md

@@ -0,0 +1,21 @@
+# Refactoring with Confidence
+
+Step 3 of the TDD loop is **Refactor**. This is where we move from "working code" to "clean code".
+
+## The Refactoring Workflow
+1. **Ensure tests are Green**: Never refactor while tests are failing.
+2. **Make small changes**: One variable rename, one function extraction, or one pattern application.
+3. **Run tests after EVERY change**: If they turn red, undo immediately.
+4. **Repeat** until the code is clean.
+
+## Refactoring-Safe Tests
+Tests that facilitate refactoring have the following traits:
+- **Implementation Agnostic**: They don't care *how* the result is calculated.
+- **Explicit**: They clearly state the business rule being protected.
+- **Fast**: They run in milliseconds, allowing for frequent execution.
+
+## Signs You Need to Refactor
+- Duplicated code logic.
+- Long methods (> 20 lines).
+- Large classes with multiple responsibilities.
+- Hard-coded values that should be configuration.

package/.mindforge/mirrors/mirror-sre-776a1cf9/.agent/skills/mindforge-tdd/tests.md

@@ -0,0 +1,28 @@
+# Writing Effective TDD Tests
+
+Your tests are the specification for your system. Treat them as first-class citizens.
+
+## The Test Anatomy: AAA
+
+- **Arrange**: Set up the environment, dependencies, and inputs.
+- **Act**: Call the method/function being tested.
+- **Assert**: Verify the result or state change.
+
+## High-Quality TDD Tests
+
+### 1. Single Responsibility
+Each test should verify exactly **one** requirement. If a test has "and" in its name, it's likely two tests.
+
+### 2. Descriptive Naming
+Use the `should ... when ...` pattern.
+- ✅ `should_calculate_discount_when_user_is_premium`
+- ❌ `test_discount_logic_1`
+
+### 3. Avoid Logic in Tests
+If your test has `if` statements or `for` loops, it's too complex. Tests should be straightforward declarations of expected behavior.
+
+### 4. Zero Watermarks
+Ensure your tests clean up after themselves (e.g., deleting temporary files or resetting mocks) to avoid "leaky state" affecting other tests.
+
+## Running Tests
+Always keep your test runner in "watch mode" during TDD. The feedback loop must be near-instant.