mindforge-cc 10.0.2 → 10.7.0

package/.mindforge/skills/technical-leadership/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: technical-leadership
+version: 1.0.0
+min_mindforge_version: 10.3.0
+status: stable
+triggers: technical leadership, engineering management decision, team velocity improvement, technical vision setting, architecture governance, tech lead responsibilities, engineering culture, technical strategy, staff engineer guidance, principal engineer, tech leadership transition, engineering org design
+---
+
+# Technical Leadership
+
+## When this skill activates
+
+This skill activates when making engineering management decisions, setting technical vision for a team or organization, governing architectural standards, improving team velocity, or transitioning into technical leadership roles. It applies to tech leads, staff engineers, principal engineers, and engineering managers responsible for technical direction and team performance.
+
+## Mandatory actions when this skill is active
+
+### Before making any leadership decision
+
+1. **Establish decision context** — Identify stakeholders, time horizon (tactical vs strategic), reversibility (one-way door vs two-way door), and blast radius. High-stakes irreversible decisions require more scrutiny than low-stakes experiments.
+2. **Gather signal, not noise** — Talk to engineers who have touched the code recently, not those with opinions but no context. Review metrics (deploy frequency, MTTR, cycle time) before making velocity assessments.
+3. **Write down your reasoning** — Document the problem, alternatives considered, tradeoffs, and decision rationale. Leadership decisions without artifacts create organizational amnesia.
+4. **Identify your biases** — Are you anchoring on past experience? Optimizing for your personal preferences? Overweighting recency? Name the bias before it distorts the decision.
+
+### During technical leadership activities
+
+#### Vision & Strategy
+
+- **Set technical vision in layers** — Near-term (3-6 months): concrete projects with clear outcomes. Mid-term (6-18 months): architectural bets and platform investments. Long-term (18-36 months): directional hypotheses, not detailed plans.
+- **Make the implicit explicit** — Document coding standards, architecture principles, trade-off frameworks. Teams align on shared mental models, not vague aspirations.
+- **Balance innovation and stability** — 70% of engineering time on core features and maintenance. 20% on incremental improvements and modernization. 10% on exploratory bets. Adjust ratios based on business stage.
+- **Connect technical work to business outcomes** — Engineers need to understand how their work impacts revenue, retention, or cost. Translate technical milestones into user or business value.
+
+#### Architectural Governance
+
+- **Define guardrails, not mandates** — Specify constraints (must use relational DB for transactional data, must have rollback plan for migrations) but let teams choose implementations. Mandates kill autonomy and innovation.
+- **Create Architecture Decision Record (ADR) culture** — Every significant architectural choice gets a lightweight ADR: context, decision, consequences, alternatives rejected. No ADR, no merge.
+- **Run design reviews, not rubber stamps** — Effective design reviews probe assumptions, identify edge cases, and challenge the status quo. Ineffective reviews just approve what's already built.
+- **Enforce technical debt budgets** — Cap tech debt at 20% of sprint capacity. If debt exceeds cap, pause feature work and pay it down. Uncapped debt compounds until the system becomes unmaintainable.
+
+#### Team Velocity
+
+- **Measure flow, not output** — Deploy frequency, lead time for changes, change failure rate, and mean time to restore (DORA metrics) predict team effectiveness better than story points or velocity charts.
+- **Eliminate toil systematically** — Track where engineers spend time. Automate the top 3 toil sources each quarter. Manual deploy scripts, flaky tests, and brittle CI pipelines are velocity killers.
+- **Protect maker time** — Engineers need 4-hour uninterrupted blocks for deep work. Meetings before 10am or after 3pm. No meetings on focus days (e.g., Tuesdays and Thursdays).
+- **Run blame-free incident reviews** — Focus on system improvements, not individual mistakes. If an engineer caused an outage, the real failure is the system that allowed a single mistake to cascade.
+
+#### Engineering Culture
+
+- **Model the behavior you want** — If you want engineers to write tests, write tests yourself. If you want transparency, share your own mistakes publicly. Culture is what leaders do, not what they say.
+- **Give feedback early and often** — Waiting for performance reviews is too late. Real-time feedback after code reviews, design reviews, and incident responses creates faster learning loops.
+- **Celebrate learning, not just shipping** — Recognize engineers who identified a critical edge case, refactored a brittle module, or wrote excellent documentation. Shipping features is necessary but not sufficient.
+- **Defend technical values against business pressure** — When product pushes for shortcuts that compromise quality, your job is to articulate the long-term cost and negotiate scope cuts, not quality cuts.
+
+#### Delegation & Escalation
+
+- **Use the delegation ladder** — Level 1: You decide, inform them. Level 2: You decide after consulting them. Level 3: They decide after consulting you. Level 4: They decide, inform you. Level 5: They decide, no need to inform you. Move up the ladder as trust and competence grow.
+- **Escalate with recommendations, not problems** — When escalating to your manager or execs, always include: problem summary, impact, options with pros/cons, your recommended path, and what you need from them.
+- **Own outcomes, delegate tasks** — You remain accountable for the team's results even when you delegate execution. Check-in without micromanaging.
+
+### After leadership actions
+
+- **Verify alignment** — After setting vision or making decisions, verify that the team understood correctly. Ask engineers to summarize in their own words. Misalignment is the default.
+- **Measure impact** — Leadership actions should move metrics. If velocity decisions don't improve DORA metrics within 1-2 quarters, the intervention failed. Adjust or abandon.
+- **Document decisions publicly** — Share architectural decisions, process changes, and strategic shifts in team channels or wikis. Private decisions create information silos and distrust.
+- **Create feedback loops** — Schedule retrospectives after major milestones. What worked? What didn't? What will we do differently next time? Learning compounds with reflection.
+
+## Self-check before task completion
+
+- [ ] Technical vision is articulated in concrete near-term projects, not vague aspirations
+- [ ] Architectural guardrails are documented with clear rationale and exceptions process
+- [ ] Team velocity is measured with DORA metrics, not story points or velocity charts
+- [ ] Engineering culture values (testing, documentation, code review rigor) are modeled by leadership
+- [ ] Delegation is explicit: who owns what, at what decision level, with what reporting cadence
+- [ ] Decisions are documented with context, alternatives, and tradeoffs
+- [ ] Feedback loops exist to measure impact and adjust course

package/.mindforge/skills/technical-writing/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: technical-writing
+version: 1.0.0
+min_mindforge_version: 0.1.0
+status: stable
+triggers: technical writing methodology, ADR authoring guide, RFC structure template, design document framework, runbook authoring standard, api documentation methodology, technical document structure, documentation methodology, document template design, tech spec writing guide, architecture document format, writing quality framework
+---
+
+# Skill — Technical Writing
+
+## When this skill activates
+Any task involving authoring ADRs, RFCs, design documents, runbooks, API documentation,
+or establishing documentation standards and templates.
+
+## Mandatory actions when this skill is active
+
+### Before writing
+1. Identify the document type (ADR, RFC, design doc, runbook, API doc).
+2. Identify the audience (developers, ops, product, executives).
+3. Determine what decision or action the reader needs to take after reading.
+
+### During writing
+- Front-load the conclusion (busy readers skim — give them the answer first).
+- One idea per section, one point per paragraph.
+- Use examples — never say "consider using X" without showing the code/config.
+- Write for the reader who has zero context about this system.
+- Use active voice and concrete nouns.
+
+### After writing
+- Read the document as if you have never seen this codebase.
+- Verify every claim is backed by a code reference or data point.
+- Check that a reader can take action based solely on this document.
+
+## Document types and templates
+
+### ADR (Architecture Decision Record)
+```markdown
+# ADR-NNN: [Short Descriptive Title]
+
+- **Status**: Proposed | Accepted | Deprecated | Superseded by ADR-XXX
+- **Date**: YYYY-MM-DD
+- **Deciders**: [Names]
+
+## Context
+[What forces are at play? What problem triggered this decision?]
+
+## Decision
+[What did we decide? State it clearly in one sentence, then elaborate.]
+
+## Options Considered
+### Option A: [Name]
+- Pros: ...
+- Cons: ...
+
+### Option B: [Name]
+- Pros: ...
+- Cons: ...
+
+## Consequences
+- [What becomes easier?]
+- [What becomes harder?]
+- [What new risks are introduced?]
+```
+Rules: One page max. Immutable once accepted (create new ADR to supersede). Record the "why" so future engineers don't revert to failed paths.
+
+### RFC (Request for Comments)
+```markdown
+# RFC: [Title]
+
+- **Author**: [Name]
+- **Status**: Draft | Under Review | Accepted | Rejected
+- **Date**: YYYY-MM-DD
+- **Reviewers**: [Names]
+
+## Summary
+[2-3 sentences: what is this and why does it matter?]
+
+## Motivation
+[Why are we doing this? What problem does it solve? Include data if possible.]
+
+## Detailed Design
+[The meat — how does it work? Include diagrams, code samples, data models.]
+
+## Drawbacks
+[Why might we NOT do this? Be honest.]
+
+## Alternatives Considered
+[What else did we evaluate? Why were they rejected?]
+
+## Open Questions
+[What don't we know yet? What needs more investigation?]
+
+## Rollout Plan
+[How do we ship this incrementally? What's the rollback strategy?]
+```
+Rules: Seek feedback before implementation. Time-box review (1-2 weeks). Address all open questions before accepting.
+
+### Design Document
+```markdown
+# Design: [Feature/System Name]
+
+- **Author**: [Name]
+- **Date**: YYYY-MM-DD
+- **Status**: Draft | Approved | Implemented
+
+## Problem Statement
+[What problem are we solving? For whom? What's the impact of not solving it?]
+
+## Background
+[What context does the reader need? Prior art, related systems, constraints.]
+
+## Goals and Non-Goals
+### Goals
+- [Measurable outcome 1]
+- [Measurable outcome 2]
+
+### Non-Goals
+- [Explicitly out of scope item 1]
+
+## Design
+[Architecture, data model, API contracts, sequence diagrams]
+
+## Alternatives Considered
+[What else was evaluated? Why was it rejected?]
+
+## Security / Privacy Considerations
+[Data handling, auth, PII, encryption]
+
+## Timeline
+[Milestones with dates]
+```
+
+### Runbook
+```markdown
+# Runbook: [Incident/Procedure Name]
+
+- **Last Updated**: YYYY-MM-DD
+- **Owner**: [Team/Person]
+- **Severity**: P1 | P2 | P3
+
+## Trigger
+[When should someone use this runbook? What alert fires?]
+
+## Diagnosis
+1. [Step 1 — check this metric/log]
+2. [Step 2 — verify this service status]
+3. [Step 3 — confirm scope of impact]
+
+## Mitigation
+1. [Step 1 — immediate action to stop bleeding]
+2. [Step 2 — apply fix]
+3. [Step 3 — verify fix applied]
+
+## Escalation
+- If Step 2 fails: page [Team/Person]
+- If impact > [threshold]: declare incident via [process]
+
+## Verification
+- [ ] [How to confirm the issue is resolved]
+- [ ] [Metric returns to baseline]
+
+## Post-Incident
+- [ ] Update this runbook if steps were wrong
+- [ ] File ticket for permanent fix
+```
+
+### API Documentation
+```markdown
+## POST /api/v1/todos
+
+Create a new todo item.
+
+### Request
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| title | string | yes | Todo title (1-200 chars) |
+| priority | enum | no | low, medium, high (default: medium) |
+
+### Response (201 Created)
+```json
+{
+  "id": "abc123",
+  "title": "Buy groceries",
+  "priority": "medium",
+  "created_at": "2025-01-15T10:30:00Z"
+}
+```
+
+### Errors
+| Status | Code | Description |
+|--------|------|-------------|
+| 400 | VALIDATION_ERROR | Title is required or exceeds 200 chars |
+| 401 | UNAUTHORIZED | Missing or invalid auth token |
+| 429 | RATE_LIMITED | Exceeded 100 requests/minute |
+```
+
+## Writing principles
+
+### Front-Load the Important Bits
+- Lead with the conclusion/recommendation, then explain.
+- The first sentence of every section should tell the reader whether to keep reading.
+- If someone reads only the headings, they should get 80% of the message.
+
+### Write for Zero Context
+- Define acronyms on first use.
+- Link to related documents rather than assuming knowledge.
+- Include "Background" sections for non-obvious domain knowledge.
+
+### Examples Over Abstractions
+- Bad: "Use parameterized queries to prevent injection."
+- Good: "Use parameterized queries: `db.query('SELECT * FROM users WHERE id = $1', [userId])`"
+
+### Active Voice
+- Bad: "The configuration file should be updated."
+- Good: "Update the configuration file."
+
+### Concrete Nouns
+- Bad: "The system processes the data appropriately."
+- Good: "The ingestion service validates JSON payloads against the schema."
+
+## Anti-patterns to avoid
+- Writing documentation after the fact (write during implementation).
+- Documents with no audience or action defined.
+- "See code for details" (the reader came to the doc to NOT read all the code).
+- Undated documents with no owner (will rot immediately).
+- ADRs that only list the chosen option (record alternatives and their trade-offs).
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Document type correctly identified and template applied?
+- [ ] Audience defined — who reads this and what action do they take?
+- [ ] Conclusion/recommendation front-loaded?
+- [ ] Every claim backed by example, code reference, or data?
+- [ ] A reader with zero context can understand and act on this?
+- [ ] Document has owner and date?

package/.mindforge/skills/technology-radar/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: technology-radar
+version: 1.0.0
+min_mindforge_version: 10.1.0
+status: stable
+triggers: technology radar, tech adoption, trial technology, hold technology, retire technology, tech evaluation, ecosystem maturity, technology lifecycle, adopt or retire, tech assessment, emerging technology, technology governance
+---
+
+# Technology Radar
+
+## When this skill activates
+
+This skill activates when the team needs to evaluate, adopt, trial, or retire a
+technology. It provides a structured governance framework for technology decisions
+using the four-ring radar model, ensuring technologies are assessed objectively
+and lifecycle-managed with clear migration paths.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. **Identify the technology under evaluation** — Name, category (language, framework,
+   tool, platform, technique), and the problem it claims to solve.
+2. **Determine current ring placement** — Where does this technology sit today in the
+   organization's radar? (Adopt / Trial / Assess / Hold / Not yet tracked)
+3. **Gather context** — Who is requesting the evaluation? What project would use it?
+   What does it replace or complement?
+
+### During
+
+4. **Apply the Four Rings model:**
+   - **Adopt** — Proven in production, recommended as default choice. Teams should use
+     this unless there is a compelling reason not to.
+   - **Trial** — Worth pursuing on a specific project with clear boundaries. Team has
+     committed to evaluate with production-quality implementation.
+   - **Assess** — Worth exploring to understand potential. Research spikes, prototypes,
+     and conference talks. No production use yet.
+   - **Hold** — Proceed with caution. Do not start new projects with this technology.
+     Existing usage should plan migration path.
+
+5. **Evaluate against criteria:**
+   - **Community size** — Contributors, GitHub stars trend, Stack Overflow activity,
+     corporate backing stability.
+   - **Maintenance activity** — Release frequency, issue response time, bus factor of
+     maintainers, funding model sustainability.
+   - **Breaking change frequency** — Semver discipline, migration tooling quality,
+     deprecation communication practices.
+   - **Performance benchmarks** — Relevant benchmarks compared to current stack and
+     alternatives. Avoid synthetic-only benchmarks.
+   - **Hiring pool** — Can you hire people who know this? Is the talent market growing
+     or shrinking? Training cost for existing team.
+   - **Ecosystem maturity** — Library availability, tooling quality, IDE support,
+     documentation completeness, testing story.
+
+6. **Governance rules:**
+   - Quarterly radar review — Reassess all Trial and Assess items every quarter.
+   - Trial time-box — Maximum 3 months. At end: promote to Adopt, extend with
+     justification, or move to Hold.
+   - Clear migration paths — Every Hold decision must include a recommended alternative
+     and migration timeline estimate.
+   - Retire explicitly — Technologies leaving Adopt must have deprecation plan with
+     timeline and responsible team.
+
+7. **Risk assessment:**
+   - What happens if this technology is abandoned by maintainers?
+   - What is the switching cost if we adopt and later need to leave?
+   - Does this create a single-vendor dependency?
+   - Are there regulatory/compliance implications?
+
+### After
+
+8. **Update the radar** — Record the ring placement decision with date, rationale, and
+   evaluation evidence.
+9. **Communicate the decision** — Share with engineering org via radar changelog.
+   Include: what changed, why, and what teams should do differently.
+10. **Set review date** — Schedule next evaluation based on ring (Adopt: annually,
+    Trial: 3 months, Assess: 6 months, Hold: review migration progress quarterly).
+
+## Self-check before task completion
+
+- [ ] Technology placed in exactly one ring with clear justification
+- [ ] All six evaluation criteria scored or explicitly marked not-applicable
+- [ ] Risk assessment completed including abandonment and switching cost
+- [ ] Migration path defined if placing in Hold ring
+- [ ] Time-box set if placing in Trial ring
+- [ ] Radar changelog entry written
+- [ ] Next review date scheduled
+- [ ] Decision communicated to affected teams

package/.mindforge/skills/testing-anti-patterns/SKILL.md

@@ -0,0 +1,288 @@
+---
+name: testing-anti-patterns
+version: 1.0.0
+min_mindforge_version: 10.0.4
+status: stable
+triggers: testing anti-pattern, mock behavior, test-only method, test smell, over-mocking, incomplete mock, integration afterthought, test fragility, testing iron law, test coupling, bad test practice
+compose:
+  - testing-standards
+---
+
+# Skill — Testing Anti-Patterns (Detection & Remediation)
+
+## When this skill activates
+When writing, reviewing, or debugging tests. This skill acts as a negative-space
+guide — it defines what NOT to do, complementing the testing-standards skill which
+defines what TO do. Activate whenever test suites feel brittle, when mocks dominate
+test code, or when tests pass but production breaks.
+
+## Mandatory actions when this skill is active
+
+### Before writing or reviewing tests
+
+1. **Internalize the Three Iron Laws:**
+   - **Iron Law 1**: Test behavior, not implementation. If you refactor internals and tests break without behavior changing, the tests are wrong.
+   - **Iron Law 2**: Mocks verify contracts, not internals. A mock should assert "I called the dependency with these inputs and expected this shape of output" — never "I called internal method X before internal method Y."
+   - **Iron Law 3**: Integration tests validate the seams. Unit tests prove components work in isolation. Integration tests prove they work together. Both are required — neither substitutes for the other.
+
+2. **Load the Red Flags Checklist** (scan code for these signals):
+   - [ ] Test file is longer than the source file it tests
+   - [ ] More than 5 mocks in a single test setup
+   - [ ] Test names describe implementation steps, not behaviors
+   - [ ] Changing a private method breaks tests
+   - [ ] Tests pass with an obviously wrong implementation (tests test nothing)
+   - [ ] Mock setup is copy-pasted across 10+ tests identically
+   - [ ] No integration tests exist for code with 2+ external dependencies
+   - [ ] Tests assert on internal state rather than observable output
+   - [ ] Test requires `sleep()` or arbitrary timeouts to pass
+   - [ ] Removing a test causes no coverage decrease (dead test)
+
+### During test writing/review
+
+**The Five Named Anti-Patterns:**
+
+---
+
+**Anti-Pattern 1: Mock Behavior Testing**
+
+*What it looks like:*
+```typescript
+// BAD: Testing that the mock returns what you told it to return
+mockDb.query.mockResolvedValue([{ id: 1, name: 'Alice' }]);
+const result = await getUser(1);
+expect(result).toEqual({ id: 1, name: 'Alice' }); // You're testing the mock!
+```
+
+*Detection gate:*
+```
+IF test assertion matches mock return value exactly
+AND no transformation logic exists between mock and assertion
+THEN this is Mock Behavior Testing
+```
+
+*Why it's harmful:* You're verifying your test setup, not your code. The test will pass even if `getUser` is `return mockDb.query()` with zero logic.
+
+*Fix:*
+```typescript
+// GOOD: Test the transformation/logic your code adds
+mockDb.query.mockResolvedValue([{ id: 1, name: 'alice', role_id: 3 }]);
+const result = await getUser(1);
+// Assert on the TRANSFORMATION your code performs
+expect(result.displayName).toBe('Alice'); // capitalization logic
+expect(result.permissions).toContain('read'); // role mapping logic
+```
+
+*Decision tree:*
+1. Does my code transform the mock's return value? → If NO, this test adds zero value
+2. Am I testing the transformation or the passthrough? → Must be transformation
+3. Would this test catch a real bug? → If you can't name the bug, delete the test
+
+---
+
+**Anti-Pattern 2: Test-Only Methods**
+
+*What it looks like:*
+```typescript
+class PaymentService {
+  // This method exists ONLY so tests can inspect internal state
+  _getInternalQueue() { return this.queue; }
+  
+  // This method exists ONLY so tests can bypass validation
+  _processWithoutValidation(payment) { ... }
+}
+```
+
+*Detection gate:*
+```
+IF method is prefixed with _ or marked @visibleForTesting
+AND method is called ONLY in test files (zero production callers)
+AND method exposes internal state or bypasses guards
+THEN this is a Test-Only Method
+```
+
+*Why it's harmful:* It couples tests to internals, creates maintenance burden, and the bypassed logic is now untested in the path that matters.
+
+*Fix:*
+- Test through the public API only
+- If you can't test behavior through the public API, your design needs refactoring (extract a collaborator, use dependency injection)
+- If state inspection is needed: add an observable side-effect (event emitted, log written, metric incremented)
+
+*Decision tree:*
+1. Is this method called anywhere in production code? → If NO, delete it
+2. Can I verify the same behavior through a public method? → If YES, use that instead
+3. Do I need to see internal state? → Refactor: make the state observable through legitimate outputs
+
+---
+
+**Anti-Pattern 3: Mocking Without Understanding**
+
+*What it looks like:*
+```typescript
+// BAD: Blindly mocking everything without understanding contracts
+jest.mock('./emailService');
+jest.mock('./database');
+jest.mock('./cache');
+jest.mock('./logger');
+jest.mock('./metrics');
+// Test only proves: "my code calls things" — not that it calls them CORRECTLY
+```
+
+*Detection gate:*
+```
+IF mock count > 3 in a single test
+AND mock return values are generic/default (undefined, {}, [])
+AND no assertions verify mock call arguments
+THEN this is Mocking Without Understanding
+```
+
+*Why it's harmful:* The mocks don't reflect real behavior. When the real dependency changes its contract, these tests keep passing while production breaks.
+
+*Fix:*
+```typescript
+// GOOD: Mock with contract awareness
+const mockEmail = {
+  send: jest.fn().mockImplementation((to, subject, body) => {
+    // Validate contract: email service requires these fields
+    if (!to.includes('@')) throw new Error('Invalid email');
+    if (!subject) throw new Error('Subject required');
+    return Promise.resolve({ messageId: 'msg-123', status: 'queued' });
+  })
+};
+// Assert on the CONTRACT, not just "was called"
+expect(mockEmail.send).toHaveBeenCalledWith(
+  expect.stringContaining('@'),
+  expect.stringMatching(/Order #\d+/),
+  expect.objectContaining({ html: expect.any(String) })
+);
+```
+
+*Decision tree:*
+1. Do I know what the real dependency's contract is? → If NO, read its docs/types first
+2. Does my mock enforce the same constraints as the real dep? → If NO, fix the mock
+3. Am I asserting on call arguments? → If NO, add contract assertions
+
+---
+
+**Anti-Pattern 4: Incomplete Mocks (Happy Path Only)**
+
+*What it looks like:*
+```typescript
+// BAD: Only mocking the success case
+mockPaymentGateway.charge.mockResolvedValue({ success: true });
+// Never testing: what if it throws? Returns { success: false }? Times out? Returns malformed data?
+```
+
+*Detection gate:*
+```
+IF mock only has .mockResolvedValue / .mockReturnValue (never .mockRejectedValue)
+AND the real dependency can fail (network, validation, timeout)
+AND no test exercises the failure path
+THEN this is Incomplete Mocking
+```
+
+*Why it's harmful:* Production failures in dependency error paths are the #1 source of incidents. If you only test happy path, you're only testing the path that rarely breaks.
+
+*Fix:*
+```typescript
+// GOOD: Test all response categories
+describe('PaymentService.charge', () => {
+  it('should process successful payment', async () => {
+    mockGateway.charge.mockResolvedValue({ success: true, txId: '123' });
+    // ...assert success handling
+  });
+
+  it('should handle declined card gracefully', async () => {
+    mockGateway.charge.mockResolvedValue({ success: false, code: 'DECLINED' });
+    // ...assert decline handling (user message, no retry)
+  });
+
+  it('should retry on transient network error', async () => {
+    mockGateway.charge
+      .mockRejectedValueOnce(new Error('ETIMEDOUT'))
+      .mockResolvedValue({ success: true, txId: '456' });
+    // ...assert retry logic
+  });
+
+  it('should circuit-break after 3 consecutive failures', async () => {
+    mockGateway.charge.mockRejectedValue(new Error('SERVICE_UNAVAILABLE'));
+    // ...assert circuit breaker trips
+  });
+});
+```
+
+*Decision tree:*
+1. Can this dependency fail? → YES (all external deps can fail)
+2. How many failure modes does it have? → List them: timeout, rejection, malformed, partial
+3. Do I have a test for each failure mode? → If NO, add them
+
+---
+
+**Anti-Pattern 5: Integration-as-Afterthought**
+
+*What it looks like:*
+- 200 unit tests, 0 integration tests
+- All dependencies mocked in every test
+- Tests pass, but the system fails when components connect
+- "Works on my machine" because mocks hide contract mismatches
+
+*Detection gate:*
+```
+IF test suite has > 50 unit tests
+AND zero integration tests exist
+AND code has 2+ external dependencies (DB, API, queue, cache)
+THEN this is Integration-as-Afterthought
+```
+
+*Why it's harmful:* Unit tests prove each brick is solid. Integration tests prove the mortar holds. Without integration tests, you have a pile of solid bricks, not a wall.
+
+*Fix:*
+- For every external dependency boundary, write at least one integration test that uses the real (or containerized) dependency
+- Integration tests should cover: connection setup, happy path through the seam, error propagation across the seam
+- Use test containers (Docker) for databases, queues, caches
+- Use contract tests (Pact) for HTTP API dependencies
+- Minimum ratio: 1 integration test per 10 unit tests for code with external deps
+
+*Decision tree:*
+1. Does this module talk to something external? → If YES, integration tests required
+2. Do I have at least one test that uses the real dependency? → If NO, add one
+3. Have I tested error propagation across the boundary? → If NO, add failure path integration tests
+
+---
+
+### After test review
+
+**Gate Function Summary — Run these checks on every test file:**
+
+```
+GATE 1 (Iron Law 1): For each test, ask:
+  "If I refactored internals without changing behavior, would this test break?"
+  → If YES: test is coupled to implementation. Rewrite to test behavior.
+
+GATE 2 (Iron Law 2): For each mock assertion, ask:
+  "Does this verify the CONTRACT with the dependency or INTERNAL sequencing?"
+  → If INTERNAL: rewrite to verify inputs/outputs at the boundary.
+
+GATE 3 (Iron Law 3): For the module as a whole, ask:
+  "If all mocks were replaced with real deps, would the system work?"
+  → If UNSURE: you need integration tests to find out.
+```
+
+**Remediation priority:**
+1. Fix Anti-Pattern 4 first (incomplete mocks) — highest incident correlation
+2. Fix Anti-Pattern 5 next (missing integration tests) — catches contract drift
+3. Fix Anti-Pattern 1 (mock behavior testing) — eliminate false confidence
+4. Fix Anti-Pattern 3 (mocking without understanding) — improve mock fidelity
+5. Fix Anti-Pattern 2 (test-only methods) — clean up API surface
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I verify tests test behavior, not implementation? (Iron Law 1)
+- [ ] Did I check that mock contracts match real dependency contracts? (Iron Law 2)
+- [ ] Did I verify integration test coverage exists for external boundaries? (Iron Law 3)
+- [ ] Did I scan the Red Flags Checklist (10 items)?
+- [ ] Did I run the 3 Gate Functions on modified test files?
+- [ ] For each mock: does it enforce constraints the real dep enforces?
+- [ ] For each mock: are failure paths tested, not just happy paths?
+- [ ] Are there zero test-only methods in production code?