@shaykec/bridge 0.4.25 → 0.4.26

package/modules/team-topologies/quick-ref.md

@@ -0,0 +1,61 @@
+# Team Topologies — Quick Reference
+
+## Conway's Law
+
+**Organizations design systems that mirror their communication structure.** Change structure to change architecture.
+
+## Four Team Types
+
+| Type | Purpose |
+|------|---------|
+| **Stream-aligned** | Own full value stream; build, run, evolve. Default. |
+| **Platform** | Provide internal services, APIs, tooling for stream-aligned teams |
+| **Enabling** | Help teams learn; temporary; step back when done |
+| **Complicated-subsystem** | Own specialized domain (ML, crypto, compliance) |
+
+## Three Interaction Modes
+
+| Mode | When | What |
+|------|------|------|
+| **Collaboration** | Discovery, high ambiguity | Side-by-side; shared goals |
+| **X-as-a-Service** | Stable interface (default) | Clear API, SLA; low touch |
+| **Facilitating** | Learning, adoption | Teach; stream-aligned learns; step back |
+
+## Cognitive Load
+
+- **Intrinsic** — domain complexity (unavoidable)
+- **Extraneous** — tooling, process, ambiguity (minimize)
+- **Germane** — productive learning (maximize)
+
+**Design to reduce extraneous load.** Split teams or add platform when load is too high.
+
+## Team Size
+
+- **Two-pizza rule** — 5–9 people
+- **Dunbar** — effective working teams ~7±2
+- **Split when** — cognitive load too high, decision wait times grow, natural sub-domains emerge
+
+## Team API
+
+Platform teams need clear contracts:
+- Documentation (what we offer, how to use)
+- SLA (uptime, latency, support)
+- Versioning (how we evolve)
+- Support path (who to ask, how to escalate)
+
+## Pitfalls
+
+| Avoid | Do Instead |
+|-------|------------|
+| Too much collaboration | Default to X-as-a-Service |
+| Platform does project work | Platform provides capabilities; streams build features |
+| Enabling never steps back | Exit criteria; handoff; step back |
+| Ignoring cognitive load | Split or add platform; simplify |
+| Reorg without behavior change | Change incentives, APIs, communication |
+
+## Evolution
+
+- **Early** — Few streams; maybe one platform person
+- **Growth** — Add platform when streams duplicate work
+- **Scale** — Enabling teams for big transitions
+- **Mature** — Complicated-subsystem when domain needs dedicated expertise

package/modules/team-topologies/quiz.md

@@ -0,0 +1,101 @@
+# Team Topologies — Quiz
+
+## Question 1
+
+What does Conway's Law state?
+
+A) Systems should be designed before teams are formed
+B) Organizations design systems that mirror their communication structure
+C) Team size should match system complexity
+D) Platform teams should own all infrastructure
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Conway's Law (1967) observes that organizations design systems that mirror their communication structure. If you have three teams, you get a three-part system. The implication: change team structure to change architecture. -->
+
+## Question 2
+
+Which team type is the default—the one that owns the core value flow?
+
+A) Platform team
+B) Enabling team
+C) Stream-aligned team
+D) Complicated-subsystem team
+
+<!-- ANSWER: C -->
+<!-- EXPLANATION: Stream-aligned teams own a full stream of value (e.g., checkout, search). They build, run, and evolve it. Platform, enabling, and complicated-subsystem teams exist to support stream-aligned teams. -->
+
+## Question 3
+
+When should two teams use the "Collaboration" interaction mode?
+
+A) Always—teams should always collaborate closely
+B) When the interface is stable and well-defined
+C) During discovery, new domains, or high ambiguity
+D) When one team is teaching the other
+
+<!-- ANSWER: C -->
+<!-- EXPLANATION: Collaboration is for discovery, new domains, and high ambiguity—when teams need to work side-by-side with shared goals. For stable interfaces, use X-as-a-Service. For teaching, use Facilitating. Collaboration is expensive; use it sparingly. -->
+
+## Question 4
+
+What is the primary constraint that team topology design should optimize for?
+
+A) Team size
+B) Budget
+C) Cognitive load
+D) Geographic distribution
+
+<!-- ANSWER: C -->
+<!-- EXPLANATION: Cognitive load is the key constraint. Teams can only hold so much in their heads. Design to minimize extraneous load, manage intrinsic load, and maximize germane (productive) learning. Splitting teams or adding platform can reduce load. -->
+
+## Question 5
+
+What is the "Inverse Conway Maneuver" pitfall?
+
+A) Reorganizing teams to match desired architecture without changing communication and incentives
+B) Creating too many stream-aligned teams
+C) Making platform teams too large
+D) Using X-as-a-Service when collaboration is needed
+
+<!-- ANSWER: A -->
+<!-- EXPLANATION: The Inverse Conway Maneuver is the attempt to reorganize teams to "match" a desired architecture. The pitfall: changing the org chart without changing behavior, incentives, and communication. Structure and behavior must align. -->
+
+## Question 6
+
+When should an enabling team step back?
+
+A) Never—enabling teams are permanent
+B) When the stream-aligned team has learned and can self-serve
+C) When the platform team is ready
+D) After one quarter
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Enabling teams are temporary. They help stream-aligned teams learn new skills or adopt new tech. Once the stream-aligned team can self-serve, the enabling team steps back. They have an exit criteria; they don't become permanent. -->
+
+## Question 7
+
+<!-- VISUAL: quiz-matching -->
+
+Match each team type to its description:
+
+A) Stream-aligned → 1) Owns a full value stream; builds, runs, evolves it
+B) Platform → 2) Provides internal services and tools for other teams
+C) Enabling → 3) Helps other teams learn; temporary, has exit criteria
+D) Complicated-subsystem → 4) Owns a complex subsystem requiring specialized skills
+
+<!-- ANSWER: A1,B2,C3,D4 -->
+<!-- EXPLANATION: Stream-aligned owns the value flow. Platform provides shared capabilities. Enabling teaches and steps back. Complicated-subsystem owns specialized domain expertise. -->
+
+## Question 8
+
+<!-- VISUAL: quiz-matching -->
+
+Match each interaction mode to its definition:
+
+A) Collaboration → 1) Teams work side-by-side; shared goals; discovery phase
+B) X-as-a-Service → 2) Consumer uses provider's offerings; well-defined interface
+C) Facilitating → 3) Provider helps consumer achieve outcome; teaching/coaching
+D) Stream-aligned → 4) Not an interaction mode; a team type
+
+<!-- ANSWER: A1,B2,C3,D4 -->
+<!-- EXPLANATION: Collaboration = work together in discovery. X-as-a-Service = consume defined offerings. Facilitating = provider helps consumer learn. Stream-aligned is a team type, not an interaction mode. -->

package/modules/team-topologies/resources.md

@@ -0,0 +1,37 @@
+# Team Topologies — Resources
+
+## Books
+
+- **Team Topologies** by Matthew Skelton and Manuel Pais — Primary source; four team types, three interaction modes, cognitive load. [teamtopologies.com](https://teamtopologies.com)
+- **An Elegant Puzzle** by Will Larson — Engineering org design; team sizing, platform teams.
+- **The Manager's Path** by Camille Fournier — Management in tech; org structure implications.
+- **Accelerate** by Forsgren, Humble, Kim — DevOps, team structure, delivery performance.
+
+## Articles
+
+- [Conway's Law — Original Paper (1968)](https://www.melconway.com/Home/Committees_Paper.html) — Melvin Conway's original formulation.
+- [Team Topologies — Official Site](https://teamtopologies.com) — Excerpts, diagrams, resources.
+- [Will Larson — An Elegant Puzzle (excerpts)](https://lethain.com/) — Team design, org evolution.
+- [Martin Fowler — Conway's Law](https://martinfowler.com/bliki/ConwaysLaw.html) — Summary and implications.
+- [Spotify Model (and its evolution)](https://engineering.atspotify.com/) — Squad/tribe structure; lessons learned.
+
+## Videos
+
+- [LeadDev — Team Topologies Talk](https://leaddev.com/) — Matthew Skelton on team design.
+- [InfoQ — Skelton & Pais on Team Topologies](https://www.infoq.com/presentations/team-topologies/) — Conference talk.
+- [QCon — Building Platform Teams](https://qconlondon.com/) — Platform team design.
+- [StaffEng — Organization Design](https://staffeng.com/) — Staff+ perspectives on org structure.
+
+## Podcasts
+
+- [Engineering Culture by InfoQ](https://www.infoq.com/podcasts/engineering-culture/) — Org design, team structure.
+- [LeadDev podcast](https://leaddev.com/podcast) — Leadership, team topologies.
+- [Software Engineering Daily](https://softwareengineeringdaily.com/) — Episodes on Conway's Law, platform teams.
+- [Lenny's Podcast](https://www.lennyspodcast.com/) — Product and eng org design.
+
+## Tools
+
+- [Team Topologies — Mapping Template](https://teamtopologies.com/workbook) — Workbook for mapping teams.
+- [Miro](https://miro.com/) — Diagramming team topologies.
+- [Lucidchart](https://www.lucidchart.com/) — Org and architecture diagrams.
+- [Excalidraw](https://excalidraw.com/) — Hand-drawn style diagrams for team mapping.

package/modules/team-topologies/walkthrough.md

@@ -0,0 +1,76 @@
+# Team Topologies — Walkthrough
+
+## Before We Begin
+
+**Diagnostic:** Conway's Law says organizations design systems that mirror their communication structure. In practice: if you have 3 siloed teams, what kind of architecture do you usually get? Why is that—and what would need to change to get something different?
+
+**Checkpoint:** You can explain the link between org structure and system design, and why "reorg to match architecture" often fails without behavior change.
+
+---
+
+## Step 1: Map Your Org to Team Types
+
+<!-- hint:diagram mermaid-type="classDiagram" topic="Team types: stream-aligned, platform, enabling, complicated-subsystem" -->
+
+**Task:** List the teams in your organization (or a subset). For each, classify: stream-aligned, platform, enabling, or complicated-subsystem. If it doesn't fit, note the gap. Are there teams that *should* exist but don't?
+
+**Question:** Where are the mismatches? What would need to change for the structure to better support flow?
+
+**Checkpoint:** Every current team is classified; at least one gap or mismatch identified.
+
+---
+
+## Step 2: Identify Interaction Modes
+
+<!-- hint:buttons type="single" prompt="When should two teams use X-as-a-Service instead of collaboration?" options="When discovering a new domain,When the consumer needs ongoing support,When the provider has a stable API,When both teams are learning" -->
+
+**Task:** Pick 2–3 pairs of teams that work together. For each pair, identify the current interaction mode (collaboration, X-as-a-Service, facilitating). Is it the *right* mode for the context? If not, what would better support flow?
+
+**Question:** Are you overusing collaboration (everyone needs to talk to everyone)? Or underusing it where discovery is needed?
+
+**Checkpoint:** Interaction modes mapped; at least one recommendation for change.
+
+---
+
+## Step 3: Assess Cognitive Load
+
+**Task:** Pick one stream-aligned team you know well. Estimate their cognitive load across intrinsic (domain complexity), extraneous (tooling, process, ambiguity), and germane (learning) dimensions. What's one change that would reduce extraneous load?
+
+**Question:** What happens when cognitive load is too high? What are the warning signs?
+
+**Checkpoint:** Load assessed; one concrete reduction identified.
+
+---
+
+## Step 4: Define a Team API
+
+<!-- hint:list style="cards" -->
+<!-- hint:card type="concept" title="A team API is what the team provides, how to use it, and what to expect—documented for consumers" -->
+
+**Task:** If you have (or imagine) a platform team, define its "team API": what it provides, how consumers use it, SLA expectations, and support model. Write it as a one-pager a stream-aligned team could read.
+
+**Question:** What makes a team API useful vs. ignored? How do you keep it current?
+
+**Checkpoint:** Team API documented; consumable by a stream-aligned team.
+
+---
+
+## Step 5: Plan an Evolution
+
+**Task:** Your org is growing. Today: 2 stream-aligned teams, no platform. In 6 months you'll have 5 stream-aligned teams. Draft a team topology evolution: when do you add a platform team? When might you need enabling? What triggers the change?
+
+**Question:** What's the cost of adding structure too early? Too late?
+
+**Checkpoint:** Evolution plan with triggers and team additions.
+
+---
+
+## Step 6: Avoid Inverse Conway Pitfalls
+
+<!-- hint:celebrate -->
+
+**Task:** Identify one place where your org (or a past org) reorganized to "match" architecture but didn't change behavior. What stayed the same? What would have been needed (incentives, APIs, culture) to make the reorg stick?
+
+**Question:** Why do we often get the org chart right but the behavior wrong?
+
+**Checkpoint:** One example of reorg-without-behavior-change; lessons for next time.

package/modules/technical-debt/content.md

@@ -0,0 +1,111 @@
+# Technical Debt — Identifying, Measuring, and Paying It Down
+
+<!-- hint:slides topic="Technical debt: Fowler's quadrant, principal vs interest, identification signals, measurement, and paydown strategies" slides="5" -->
+
+## What Technical Debt Is (and Isn't)
+
+**Technical debt** is the implied cost of rework caused by choosing a quicker or easier solution now instead of a better one that would take longer. Like financial debt: you get something now, you pay interest (extra effort) later.
+
+It isn't:
+- **Bugs** — bugs are defects; debt is structural
+- **Missing features** — that's scope, not debt
+- **"Bad code"** without a decision — debt implies a choice (even if unconscious)
+
+## The Debt Metaphor
+
+| Term | Meaning |
+|------|---------|
+| **Principal** | The work to fix the suboptimal design |
+| **Interest** | Extra cost of every change that touches the debt (slower dev, more bugs) |
+
+Low-touch code may have low interest; high-touch code has high interest. Pay down high-interest debt first.
+
+## Fowler's Technical Debt Quadrant
+
+Not all debt is equal. Martin Fowler divides it by **deliberate vs inadvertent** and **prudent vs reckless**:
+
+```mermaid
+flowchart LR
+    subgraph Reckless["Reckless"]
+        A1["Inadvertent: We didn't know better"]
+        A2["Deliberate: We knew but cut corners"]
+    end
+    subgraph Prudent["Prudent"]
+        B1["Inadvertent: We learned; design should change"]
+        B2["Deliberate: Thoughtful tradeoff — plan to pay"]
+    end
+```
+
+| | Reckless | Prudent |
+|--|----------|---------|
+| **Deliberate** | "We know we're cutting corners" — often a mistake; interest compounds | "We ship now, plan to fix" — acceptable if you actually pay it |
+| **Inadvertent** | "We didn't know better" — inexperience, learning | "We learned; design should change" — inevitable, even for good teams |
+
+**Prudent-deliberate** is the only "good" debt: you choose it knowingly and plan paydown. The rest range from unavoidable (prudent-inadvertent) to harmful (reckless-deliberate).
+
+## Identifying Technical Debt
+
+### Code Smells
+- Long methods, deep nesting
+- Duplication (DRY violations)
+- Shotgun surgery (one change touches many files)
+- Feature envy, God classes
+- Comments that explain bad names instead of fixing them
+
+### Velocity Trends
+- Story points per sprint dropping
+- Same-size features taking longer
+- More bugs per release
+
+### Bug Clusters
+- Same module keeps failing — often a sign of structural debt
+
+## Measuring It
+
+| Metric | What It Tells You |
+|--------|-------------------|
+| Cyclomatic complexity | Per-function complexity; high = hard to test |
+| Test coverage | Gaps indicate risky areas |
+| Lead time / cycle time | How long from idea to ship |
+| Bug rate by module | Where debt causes the most pain |
+| Churn (files changed often) | High churn + high complexity = high interest |
+
+## Prioritizing Paydown
+
+1. **Interest rate** — How much does this slow us down? Fix high-touch debt first.
+2. **Principal size** — Can we pay it in one sprint or does it need a plan?
+3. **Risk** — Does it cause outages or security issues?
+4. **Strategic fit** — Are we about to change this area anyway?
+
+## Communicating to Stakeholders
+
+- **Speak in outcomes** — "This slows feature X by 2 days per release" not "our code is messy"
+- **Quantify when possible** — "We spend 20% of sprint on workarounds"
+- **Offer options** — "We can pay 1 sprint now or absorb 3x cost over 6 months"
+- **Tie to business goals** — "Fixing this unblocks the Q3 roadmap"
+
+## Strategies for Paydown
+
+### Boy Scout Rule
+Leave code better than you found it. Small, incremental improvement.
+
+### Dedicated Sprints
+Allocate a portion of capacity (e.g., 20%) to debt paydown. Protects against infinite postponement.
+
+### Strangler Fig
+Replace a legacy system gradually by routing new behavior to new code and migrating callers over time. Avoids big-bang rewrites.
+
+### When to Refactor vs Rewrite
+- **Refactor** when the design is salvageable — extract, rename, split. Cheaper, lower risk.
+- **Rewrite** when the design is fundamentally wrong, or the system is small enough that rewrite is faster than untangling. Rare; usually refactor.
+
+---
+
+## Key Takeaways
+
+1. Debt = principal (fix cost) + interest (ongoing cost)
+2. Quadrant: prudent-deliberate is acceptable; reckless-deliberate is toxic
+3. Identify via smells, velocity, bug clusters
+4. Measure and prioritize by interest and risk
+5. Communicate in business terms; offer clear options
+6. Prefer incremental paydown (boy scout, strangler fig) over rewrites

package/modules/technical-debt/exercises.md

@@ -0,0 +1,92 @@
+# Technical Debt Exercises
+
+## Exercise 1: Principal vs Interest
+
+**Task:** A payment service has 2000 lines in one file. Every bug fix or feature touches it. Fixing it properly would take 2 sprints. Each change currently takes 2x longer due to complexity.
+
+Estimate: (a) Principal (sprint-equivalent), (b) Interest per quarter (assuming 8 changes/quarter), (c) Break-even: after how many quarters does interest exceed principal?
+
+**Validation:**
+- [ ] Principal = 2 sprints
+- [ ] Interest = 8 changes × some multiplier (e.g., 1 extra day each = 8 days)
+- [ ] Break-even calculation is coherent
+
+**Hints:**
+1. Principal = one-time cost to fix
+2. Interest = extra cost per touch × number of touches
+3. When does cumulative interest > principal?
+
+---
+
+## Exercise 2: Quadrant Classification
+
+**Task:** Classify each into Fowler's quadrant (prudent/reckless × deliberate/inadvertent):
+
+1. Team uses `any` everywhere in TypeScript to ship fast; never revisits
+2. Team picks a framework they've never used; architecture turns out wrong
+3. Team defers a DB migration to next quarter with a written ticket
+4. Copy-paste from Stack Overflow without understanding; causes bugs later
+
+**Validation:**
+- [ ] (1) Reckless deliberate
+- [ ] (2) Prudent or reckless inadvertent
+- [ ] (3) Prudent deliberate
+- [ ] (4) Reckless inadvertent (or reckless deliberate if they knew)
+
+**Hints:**
+1. Deliberate = they knew they were taking a shortcut
+2. Prudent = they planned to pay it back
+3. "Never revisits" = reckless
+
+---
+
+## Exercise 3: Identify and Measure
+
+**Task:** Pick a module (real or hypothetical). List 3 code smells, 2 metrics you'd track, and 1 business impact you'd report.
+
+**Validation:**
+- [ ] Smells are specific (e.g., "300-line function", "duplicated validation logic")
+- [ ] Metrics are measurable (complexity, coverage, cycle time)
+- [ ] Business impact is in stakeholder language (time, risk, cost)
+
+**Hints:**
+1. Smells: length, duplication, nesting, naming
+2. Metrics: sonar/ESLint complexity, test coverage, Jira cycle time
+3. Impact: "Feature X takes 2 days longer" or "Bugs in payment flow"
+
+---
+
+## Exercise 4: Pitch to Stakeholders
+
+**Task:** Write a short pitch (5–7 sentences) to get 1 sprint for tech debt paydown. Include: problem, current cost, proposed fix, and what unlocks after.
+
+**Validation:**
+- [ ] States the problem in business terms
+- [ ] Quantifies cost (time, risk, or money)
+- [ ] Describes the fix at a high level
+- [ ] Connects paydown to a positive outcome (faster features, fewer bugs)
+
+**Hints:**
+1. Avoid jargon — "slow to change" not "high cyclomatic complexity"
+2. Use numbers: "20% of sprint on workarounds"
+3. End with: "After this, we can deliver X faster"
+
+---
+
+## Exercise 5: Refactor vs Strangler vs Rewrite
+
+**Task:** For each scenario, choose Refactor, Strangler Fig, or Rewrite. Justify in one sentence.
+
+1. Auth logic is scattered across 10 files; needs centralization
+2. Legacy PHP app; team wants to move to Node
+3. One module has wrong abstractions; rest of system is fine
+
+**Validation:**
+- [ ] (1) Refactor — extract and consolidate
+- [ ] (2) Strangler (or rewrite if very small) — gradually replace
+- [ ] (3) Refactor — fix one module in place
+
+**Hints:**
+1. Refactor = improve in place
+2. Strangler = build new around old, migrate incrementally
+3. Rewrite = replace whole system; rare, high risk

package/modules/technical-debt/module.yaml

@@ -0,0 +1,39 @@
+slug: technical-debt
+title: "Technical Debt — Identifying, Measuring, and Paying It Down"
+version: 1.0.0
+description: "Understand technical debt, measure it, prioritize paydown, and communicate it to stakeholders."
+category: developer-skills
+tags: [technical-debt, refactoring, code-quality, maintenance, architecture]
+difficulty: intermediate
+
+xp:
+  read: 15
+  walkthrough: 40
+  exercise: 25
+  quiz: 20
+  quiz-perfect-bonus: 10
+
+time:
+  quick: 5
+  read: 20
+  guided: 50
+
+prerequisites: [code-review]
+related: [clean-code, solid-principles]
+
+triggers:
+  - "What is technical debt?"
+  - "How do I convince my manager to pay down tech debt?"
+  - "How do I measure technical debt?"
+  - "When should I refactor vs rewrite?"
+
+visuals:
+  diagrams: [diagram-mermaid, diagram-flow]
+  quiz-types: [quiz-matching, quiz-timed-choice]
+  playground: null
+  slides: true
+
+sources:
+  - url: "https://martinfowler.com/bliki/TechnicalDebtQuadrant.html"
+    label: "Martin Fowler's Tech Debt Quadrant"
+    type: docs

package/modules/technical-debt/quick-ref.md

@@ -0,0 +1,60 @@
+# Technical Debt Quick Reference
+
+## Debt Metaphor
+
+| Term | Meaning |
+|------|---------|
+| Principal | One-time cost to fix the design |
+| Interest | Extra cost per change that touches the debt |
+
+## Fowler's Quadrant
+
+| | Reckless | Prudent |
+|--|----------|---------|
+| **Deliberate** | Knew, cut corners, no plan to fix | Knew, planned to pay back |
+| **Inadvertent** | Didn't know, made a mess | Learned; design should change |
+
+Prudent deliberate = acceptable. Reckless deliberate = toxic.
+
+## Identifying Debt
+
+| Signal | What to Look For |
+|--------|------------------|
+| Code smells | Long functions, duplication, deep nesting, God classes |
+| Velocity | Same features taking longer, points per sprint dropping |
+| Bugs | Same module failing repeatedly |
+
+## Metrics
+
+| Metric | Use |
+|--------|-----|
+| Cyclomatic complexity | Per-function complexity |
+| Test coverage | Gaps = risky areas |
+| Lead time / cycle time | Idea → ship |
+| Bug rate by module | Where debt hurts most |
+| Churn | Files changed often = high interest |
+
+## Prioritization
+
+1. **Interest** — High-touch debt first
+2. **Principal** — Can we pay in one sprint?
+3. **Risk** — Security, outages
+4. **Strategy** — Are we changing this area soon?
+
+## Communicating
+
+| Do | Don't |
+|----|-------|
+| Quantify impact (time, bugs, risk) | Use jargon (complexity, smells) |
+| Tie to business goals | Say "code is messy" |
+| Offer options and tradeoffs | Demand without context |
+
+## Strategies
+
+| Strategy | When |
+|----------|------|
+| Boy Scout Rule | Incremental; leave code better |
+| Dedicated sprints | Allocate % capacity |
+| Strangler Fig | Legacy; replace gradually |
+| Refactor | Design salvageable |
+| Rewrite | Design fundamentally wrong; rare |

package/modules/technical-debt/quiz.md

@@ -0,0 +1,73 @@
+# Technical Debt Quiz
+
+## Question 1
+
+What is "interest" in the technical debt metaphor?
+
+A) The time it took to write the original code
+B) The ongoing extra cost of every change that touches the debt
+C) The cost of the initial quick-and-dirty solution
+D) The number of bugs in the code
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Interest is the recurring cost — each time you work in that area, you pay extra (slower changes, more bugs, harder debugging). Principal is the one-time cost to fix it. -->
+
+## Question 2
+
+In Fowler's quadrant, which type of debt is acceptable if you actually pay it?
+
+A) Reckless inadvertent
+B) Reckless deliberate
+C) Prudent inadvertent
+D) Prudent deliberate
+
+<!-- ANSWER: D -->
+<!-- EXPLANATION: Prudent deliberate means you knowingly took a shortcut with a plan to pay it back. The others either lack awareness (inadvertent) or lack intention to fix (reckless). -->
+
+## Question 3
+
+Which is a signal of technical debt rather than debt itself?
+
+A) A decision to ship without tests to meet a deadline
+B) A 300-line function with deep nesting
+C) An intentional tradeoff documented in a ticket
+D) A planned migration to a new framework
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: A long, complex function is a "code smell" — a signal that debt may exist. The actual debt is the decision (or lack of decision) that led to it. A, C, D describe decisions or plans. -->
+
+## Question 4
+
+When pitching tech debt paydown to a manager, what's most persuasive?
+
+A) "Our cyclomatic complexity is high"
+B) "This module causes 40% of our bugs and delays each release by 2 days"
+C) "The code is messy"
+D) "We need to refactor"
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Stakeholders care about outcomes: bugs, time, risk. Quantifying impact (40% of bugs, 2-day delay) makes the case. Technical jargon (cyclomatic complexity, "messy") doesn't translate. -->
+
+## Question 5
+
+When should you prefer refactoring over a full rewrite?
+
+A) Never — rewrites are always better
+B) When the design is salvageable and the system isn't tiny
+C) Only when you have infinite time
+D) Rewrites are always cheaper
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Refactoring (extract, rename, split) is cheaper and lower risk when the design can be improved in place. Rewrites are risky and expensive; use for fundamentally broken or very small systems. -->
+
+## Question 6
+
+What does the "Strangler Fig" strategy mean?
+
+A) Rewrite the entire system at once
+B) Gradually replace a legacy system by routing new behavior to new code and migrating over time
+C) Ignore the debt until it crashes
+D) Add more tests around the bad code
+
+<!-- ANSWER: B -->
+<!-- EXPLANATION: Strangler fig pattern: build new code around the old, route new features to the new system, migrate callers incrementally. Avoids big-bang rewrites and reduces risk. -->

package/modules/technical-debt/resources.md

@@ -0,0 +1,25 @@
+# Technical Debt — Resources
+
+## Videos
+
+- [Technical Debt Explained](https://www.youtube.com/results?search_query=martin+fowler+technical+debt) — Martin Fowler and others. The metaphor, quadrant, and paydown strategies.
+- [Managing Technical Debt](https://www.youtube.com/watch?v=ZAhN_2lcfSI) — GOTO Conferences. Practical approaches to measurement and communication.
+
+## Articles and Readings
+
+- [Technical Debt Quadrant](https://martinfowler.com/bliki/TechnicalDebtQuadrant.html) — Martin Fowler. Prudent/reckless, deliberate/inadvertent. Key framework.
+- [Technical Debt](https://martinfowler.com/bliki/TechnicalDebt.html) — Martin Fowler. Origin of the metaphor.
+- [A Mess Is Not a Technical Debt](https://sites.google.com/site/unclebobconsultingllc/a-mess-is-not-a-technical-debt) — Uncle Bob. Distinguishes debt from mess; complements Fowler's quadrant.
+- [Strangler Fig Application](https://martinfowler.com/bliki/StranglerFigApplication.html) — Martin Fowler. Incremental replacement of legacy systems.
+
+## Books
+
+- **Refactoring** by Martin Fowler — Systematic techniques for paying down debt safely.
+- **Working Effectively with Legacy Code** by Michael Feathers — Strategies for improving code you're afraid to touch.
+- **The Software Craftsman** by Sandro Mancuso — Professional attitude toward quality and debt.
+
+## Tools and Playgrounds
+
+- [SonarQube](https://www.sonarqube.org/) — Code quality and technical debt metrics.
+- [ESLint](https://eslint.org/) — JavaScript/TypeScript linting; catches many smells.
+- [CodeClimate](https://codeclimate.com/) — Maintainability and debt metrics.