purecontext-mcp 1.1.7 → 1.2.0

package/CODE-INTELLIGENCE.md

@@ -0,0 +1,369 @@
+# Code Intelligence
+
+Some questions about a codebase can't be answered by searching for a specific name or looking at a single file. They require the server to reason about the whole codebase at once: *where does this application start?*, *what does this library expose?*, *which functions have no tests?*, *where are all the outstanding TODO items?*
+
+PureContext's code intelligence tools answer these whole-codebase questions without requiring you to read through files manually.
+
+---
+
+## Finding entry points
+
+Every application has a starting point — and often more than one. A Node.js service has a `bootstrap()` call. A CLI tool has argument parsing. A serverless function has Lambda handlers. A test suite has test runner entry points.
+
+**Scenario:** You've just been handed a codebase you've never seen before. Your first question: how does this thing actually start?
+
+> "Where does this application start? Show me all the entry points."
+
+```
+get_entry_points(repoId) →
+
+  Entry Points (8 found):
+
+  HIGH CONFIDENCE:
+    main()               src/index.ts           main_function
+      reason: "function named main at module root"
+
+    bootstrap()          src/server.ts          server_startup
+      reason: "calls app.listen(), server startup pattern"
+
+    handler()            src/lambda/api.ts       lambda_handler
+      reason: "exported 'handler' in file matching /lambda/"
+
+    handler()            src/lambda/events.ts    lambda_handler
+      reason: "exported 'handler' in file matching /lambda/"
+
+  MEDIUM CONFIDENCE:
+    run()                src/cli/index.ts        cli_handler
+      reason: "calls process.argv, process.exit — CLI pattern"
+
+    workerMain()         src/workers/index.ts    server_startup
+      reason: "calls queue.process() — worker startup pattern"
+
+  LOW CONFIDENCE:
+    setup()              test/setup.ts           test_suite
+      reason: "matched test file pattern, exports setup function"
+
+    seed()               scripts/seed.ts         script
+      reason: "script file with no importers"
+```
+
+Eight entry points: two Lambda handlers, a main server, a CLI, a worker, and a seeding script. In 30 seconds you understand the full deployment surface of the application.
+
+**Filtering by type:**
+
+> "Show me only the Lambda handlers."
+
+```
+get_entry_points(repoId, kind: "lambda_handler", minConfidence: "high") →
+  [only the two confirmed Lambda handlers]
+```
+
+**Use with `get_call_hierarchy`** to trace the full execution path from an entry point:
+
+```
+get_entry_points(repoId, kind: "server_startup") → bootstrap()
+get_call_hierarchy(symbolId: "bootstrap-id", direction: "callees", maxDepth: 3)
+  → full initialization sequence
+```
+
+---
+
+## Auditing the public API surface
+
+Libraries, shared packages, and microservice clients expose a public API. Over time, that API grows — and often includes symbols that were never meant to be public.
+
+**Scenario:** You're preparing a major version release. You want to document the public API and identify exports that aren't actually used by any consumer.
+
+> "What does this package export? Show me the full public API surface."
+
+```
+get_public_api(repoId) →
+
+  Public API Surface — 3 files, 47 exports
+
+  src/index.ts (31 exports):
+    createClient()        function   default export  "Create a new PureContext client"
+    IndexManager          class                      "Manages index lifecycle"
+    SearchEngine          class                      "Symbol and semantic search"
+    SymbolRecord          type                       "Core symbol type"
+    SymbolKind            type                       "Union of all symbol kinds"
+    ImportRecord          type                       "Import edge type"
+    ...
+
+  src/config.ts (9 exports):
+    loadConfig()          function                   "Load and validate config.json"
+    ConfigSchema          type                       "JSON Schema for config"
+    DEFAULT_CONFIG        const                      "Default configuration values"
+    ...
+
+  src/errors.ts (7 exports):
+    PureContextError      class                      "Base error class"
+    IndexNotFoundError    class                      "Repo not indexed"
+    ...
+
+  Total: 47 exported symbols
+```
+
+**Finding dead exports — things you export but nobody uses:**
+
+```
+get_public_api(repoId) → 47 exports
+find_dead_code(repoId)  → 12 exports have no importers
+
+  These 12 are exported but never imported:
+    LegacyParser         src/index.ts   (deprecated)
+    debugMode            src/config.ts  (internal flag leaked into public API)
+    InternalQueue        src/index.ts   (should have been private)
+    ...
+```
+
+Twelve symbols that are publicly exported but consumed by nobody — prime candidates for removal before the major release.
+
+**Filtering the API by kind or file:**
+
+```
+get_public_api(repoId, kind: "function") → only exported functions
+get_public_api(repoId, filePath: "src/auth/") → exports from auth module only
+get_public_api(repoId, includeMembers: true) → includes public methods of exported classes
+```
+
+---
+
+## Tracking TODOs and technical debt comments
+
+Every codebase has outstanding work buried in comments. `get_todos` surfaces all of it in one place.
+
+**Scenario:** Before a release, you want a complete list of every `FIXME` and `TODO` in the codebase.
+
+> "Show me all FIXMEs and TODOs in the codebase, grouped by file."
+
+```
+get_todos(repoId, tags: ["FIXME", "TODO"], groupByFile: true) →
+
+  30 items found across 18 files
+
+  src/auth/oauth2.ts (3):
+    TODO:42   Replace JWT_SECRET with dedicated OAUTH_STATE_SECRET before merge
+    FIXME:67  Race condition: concurrent refreshes can invalidate each other's tokens
+    TODO:89   Add retry logic for failed OAuth state validation
+
+  src/billing/processor.ts (4):
+    FIXME:23  chargePayment doesn't handle partial auth — card could be charged twice
+    TODO:45   Add idempotency key support
+    TODO:67   Move tax calculation to a separate service
+    TODO:134  Handle PaymentIntent.cancelled status
+
+  src/core/database.ts (2):
+    FIXME:45  Connection pool exhaustion under load — needs backpressure
+    TODO:78   Add query timeout configuration
+
+  ... (15 more files)
+
+  Summary by tag:
+    TODO:  24 items
+    FIXME:  6 items
+```
+
+Two of those FIXMEs describe potential bugs — a race condition in OAuth token refresh and a double-charge risk in billing. Those belong on the release blocker list.
+
+**Filtering by tag:**
+
+```
+get_todos(repoId, tags: ["FIXME", "BUG"])
+  → only bugs and fixes — use before a release
+
+get_todos(repoId, tags: ["HACK"])
+  → all acknowledged hacks — useful for tech debt planning
+
+get_todos(repoId, tags: ["TODO", "OPTIMIZE"])
+  → performance improvement backlog
+```
+
+**Filtering by assignee:**
+
+```
+get_todos(repoId, assignee: "alice")
+  → only items assigned to alice: TODO(alice): ...
+
+get_todos(repoId, filePath: "src/auth/", tags: ["FIXME"])
+  → all FIXMEs in the auth module
+```
+
+---
+
+## Finding complexity hotspots
+
+When you have limited refactoring time, you want to focus on the files that will give you the most improvement per hour. `get_complexity_hotspots` ranks files by their complexity concentration — not just the worst individual function, but files with many complex symbols clustered together.
+
+**Scenario:** You're allocating sprint capacity to reduce complexity. Which files should you tackle first?
+
+> "Which files in src/ have the highest complexity concentration? I want to prioritize my refactoring backlog."
+
+```
+get_complexity_hotspots(repoId, scope: "src/", topN: 8) →
+
+  Complexity Hotspots:
+
+  1. src/legacy/UserManager.ts          hotspot: 94/100
+     avg complexity: 11.4    max: 23    symbols: 34
+     Top offenders:
+       processAuthRequest()   complexity: 23   120 lines
+       handlePermissions()    complexity: 19    98 lines
+       validateUserData()     complexity: 14    67 lines
+
+  2. src/billing/processor.ts           hotspot: 78/100
+     avg complexity: 8.7     max: 18    symbols: 14
+     Top offenders:
+       chargePayment()        complexity: 18    89 lines
+       applyDiscounts()       complexity: 12    54 lines
+
+  3. src/api/routes/legacy.ts           hotspot: 67/100
+     avg complexity: 7.1     max: 15    symbols: 21
+     Top offenders:
+       handleLegacyRequest()  complexity: 15    78 lines
+
+  4. src/core/parser.ts                 hotspot: 61/100
+     avg complexity: 6.8     max: 12    symbols: 9
+     ...
+```
+
+`UserManager.ts` has the worst hotspot score — nearly every function in it is complex. `billing/processor.ts` is second, with two high-complexity functions in a smaller file. These two files are your sprint targets.
+
+**Scoping to a directory and filtering out simple functions:**
+
+```
+get_complexity_hotspots(repoId, scope: "src/api/", topN: 5, minComplexity: 5)
+  → hotspots in the API directory, only counting functions with complexity ≥ 5
+```
+
+---
+
+## Visualizing the type hierarchy
+
+For TypeScript codebases with significant type hierarchies — domain models, plugin interfaces, ORM entities — `get_type_graph` shows how all the types relate to each other.
+
+**Scenario:** You're onboarding a new developer to work on the domain model. You want to give them a visual overview of the type relationships before they start.
+
+> "Show me a Mermaid diagram of the type hierarchy in src/domain/."
+
+```
+get_type_graph(repoId, scope: "src/domain/", format: "mermaid") →
+
+  ```mermaid
+  classDiagram
+    Entity <|-- UserEntity
+    Entity <|-- OrderEntity
+    Entity <|-- ProductEntity
+    UserEntity --> Address : uses
+    UserEntity --> UserRole : uses
+    OrderEntity --> OrderItem : uses
+    OrderEntity --> PaymentStatus : uses
+    Repository~T~ <|.. UserRepository
+    Repository~T~ <|.. OrderRepository
+    Repository~T~ <|.. ProductRepository
+  ```
+```
+
+Paste into any Mermaid renderer and the team can see the full domain model at a glance. Generated from live code — never stale.
+
+**Focusing on one type's connected types:**
+
+```
+get_type_graph(repoId, rootSymbol: "UserEntity", maxDepth: 2) →
+  [UserEntity and everything it directly relates to, up to 2 hops]
+```
+
+**JSON output for programmatic use:**
+
+```
+get_type_graph(repoId, scope: "src/domain/", format: "json") →
+  {
+    "nodes": [
+      { "id": "...", "name": "UserEntity", "kind": "class", "filePath": "..." },
+      { "id": "...", "name": "Repository", "kind": "interface", "filePath": "..." },
+      ...
+    ],
+    "edges": [
+      { "source": "UserEntity-id", "target": "Entity-id", "relationship": "extends" },
+      { "source": "UserRepository-id", "target": "Repository-id", "relationship": "implements" },
+      ...
+    ]
+  }
+```
+
+Use this to feed into custom diagram tools, documentation generators, or architecture review scripts.
+
+---
+
+## Finding untested symbols
+
+`find_untested_symbols` identifies functions, methods, and classes whose names don't appear in any test file — a heuristic for missing test coverage without needing a coverage report.
+
+**Scenario:** Before a release, you want to know which business-critical functions have no tests at all.
+
+> "Which functions in src/billing/ have no test coverage?"
+
+```
+find_untested_symbols(repoId, scope: "src/billing/", kinds: ["function", "method"]) →
+
+  Untested Symbols — 12 found (sorted by priority):
+
+  HIGH PRIORITY (complex and untested):
+    chargePayment()       src/billing/processor.ts    complexity: 18   lines: 89
+    applyRefund()         src/billing/refunds.ts      complexity: 12   lines: 67
+    calculateProration()  src/billing/proration.ts    complexity: 9    lines: 45
+
+  MEDIUM PRIORITY:
+    formatInvoiceLine()   src/billing/invoice.ts      complexity: 4    lines: 23
+    getNextBillingDate()  src/billing/schedule.ts     complexity: 3    lines: 18
+    ... (5 more)
+
+  LOW PRIORITY:
+    formatCurrency()      src/billing/format.ts       complexity: 1    lines: 4
+    ... (4 more)
+```
+
+The three high-priority items — `chargePayment`, `applyRefund`, `calculateProration` — are complex, untested, and handle money. These are your release blockers.
+
+**Getting exact coverage with a coverage report:**
+
+For more precision, use `get_test_coverage_map` instead:
+
+> "Parse our vitest coverage report and show me which billing functions are uncovered."
+
+```
+get_test_coverage_map(repoId,
+  coveragePath: "/project/coverage/coverage-final.json",
+  scope: "src/billing/",
+  includeUncoveredOnly: true) →
+
+  Coverage Summary: 67% (41 of 61 symbols covered)
+
+  Uncovered Symbols:
+    chargePayment()       src/billing/processor.ts    0 calls   0% statements
+    applyRefund()         src/billing/refunds.ts      0 calls   0% statements
+    handlePartialAuth()   src/billing/processor.ts    0 calls   0% statements
+    ...
+
+  File Coverage:
+    src/billing/processor.ts    statements: 45%   functions: 33%   branches: 38%
+    src/billing/refunds.ts      statements: 52%   functions: 50%   branches: 44%
+    src/billing/invoice.ts      statements: 91%   functions: 88%   branches: 84%
+```
+
+Line-accurate coverage linked to indexed symbols. Supports Istanbul/NYC (`coverage-final.json`) and V8/c8 formats.
+
+---
+
+## Choosing between coverage tools
+
+| Situation | Use |
+|-----------|-----|
+| No coverage file available — quick estimate | `find_untested_symbols` |
+| You have a coverage report — need line accuracy | `get_test_coverage_map` |
+| Find the most complex untested functions | `find_untested_symbols` (sorted by complexity) |
+| See statement/branch/function % per file | `get_test_coverage_map` |
+
+---
+
+→ Reference: [MCP Tools Reference](docs/06-tools-reference.md) — `get_entry_points`, `get_public_api`, `get_todos`, `get_complexity_hotspots`, `get_type_graph`, `find_untested_symbols`, `get_test_coverage_map`

package/HEALTH-DASHBOARDS.md

@@ -0,0 +1,241 @@
+# Health Dashboards & Debt Reporting
+
+Technical debt accumulates the same way in every codebase: gradually, then suddenly. Individual decisions that seemed reasonable at the time compound into a system that's expensive to change and risky to touch. By the time it's a crisis, you're already deep in it.
+
+PureContext gives you three complementary tools for measuring, tracking, and acting on code health over time.
+
+---
+
+## Health radar: five-axis scoring at a glance
+
+`health_radar` scores your codebase on five dimensions, each 0–100 where 100 is perfectly healthy. It's designed for a quick read — dashboard views, CI gates, and pre-meeting overviews.
+
+**Scenario:** Before a quarterly architecture review, you want a snapshot of where the codebase stands.
+
+> "Give me a health overview of the entire codebase before we start our planning session."
+
+```
+health_radar(repoId) →
+
+  Health Radar — purecontext-mcp
+
+  complexity       72   ██████████████░░░░░░  Good
+                        avg. cyclomatic: 3.4  peak: 18 (src/legacy/UserManager.ts)
+
+  coupling         51   ██████████░░░░░░░░░░  Warning
+                        23 files with fan-out > 10  (threshold: < 10)
+
+  maintainability  78   ███████████████░░░░░  Good
+                        3 god classes found  11 dead exports
+
+  documentation    34   ██████░░░░░░░░░░░░░░  Poor
+                        34% of exported symbols have meaningful summaries
+
+  stability        63   ████████████░░░░░░░░  Fair
+                        (churn data available — 8 high-churn files flagged)
+
+  Overall Health:  60   Grade: C
+
+  Summary: 312 files, 4,218 symbols, 7 high-risk files
+```
+
+Five numbers give you the complete picture in under 30 seconds. Complexity and maintainability are green. Coupling is borderline. Documentation is a problem. Stability is fair but has hot spots.
+
+**Scoping to a subsystem:**
+
+> "How healthy is just the authentication module?"
+
+```
+health_radar(repoId, scope: "src/auth/") →
+  [same five axes, computed only for files under src/auth/]
+```
+
+Use this to compare health across services, or to track the health of a specific domain area you're actively working on.
+
+**Excluding git data:**
+
+```
+health_radar(repoId, includeStability: false)
+```
+
+The stability axis requires git history. If git metadata isn't available (e.g., a freshly cloned repo without full history), set `includeStability: false` to score only the four static axes.
+
+---
+
+## Comparing health between two versions
+
+`diff_health_radar` runs health radar on two repos and computes the delta. The most common use is before/after comparison, but it works for any two indexed repos.
+
+**Scenario 1: Validating a refactoring sprint.**
+
+Your team spent two weeks addressing coupling and documentation issues. You want proof that it worked.
+
+> "Compare the health of the codebase now vs. the snapshot we indexed before the sprint."
+
+```
+diff_health_radar(baseRepoId: "pre-sprint-id", headRepoId: "post-sprint-id") →
+
+  Comparison: pre-sprint → post-sprint
+
+  complexity      72 → 74   Δ +2   stable
+  coupling        51 → 67   Δ +16  ▲ improved
+  maintainability 78 → 82   Δ +4   stable
+  documentation   34 → 61   Δ +27  ▲ improved significantly
+  stability       63 → 65   Δ +2   stable
+
+  Overall:  60 → 70   Δ +10   trend: improved
+
+  Improvements: coupling, documentation
+  Regressions:  none
+```
+
+Coupling improved from 51 to 67 — a meaningful change. Documentation went from 34 to 61 — a dramatic improvement from the doc-writing effort. No regressions. The sprint achieved its goals.
+
+**Scenario 2: PR health review.**
+
+> "Does this PR improve or worsen the codebase health?"
+
+```
+# 1. Index main branch
+index_folder(path: "/projects/app", ...)  → baseRepoId: "main-index"
+
+# 2. Index the feature branch
+index_folder(path: "/projects/app-pr-feature-x", ...) → headRepoId: "pr-index"
+
+# 3. Compare
+diff_health_radar(baseRepoId: "main-index", headRepoId: "pr-index") →
+
+  coupling        65 → 61   Δ -4   ▼ degraded
+  documentation   61 → 58   Δ -3   ▼ degraded slightly
+
+  Regressions: coupling, documentation
+  trend: degraded
+```
+
+The PR adds coupling and removes documentation coverage. Flag it in the review — the delta is small but the direction is wrong.
+
+---
+
+## Debt reports: from score to action
+
+Health radar gives you scores. `get_debt_report` gives you the full breakdown with ranked files and prioritized action items.
+
+**Scenario:** You have a C-grade codebase and limited sprint capacity. You want to know exactly where to invest to get the most improvement per hour of work.
+
+> "Generate a technical debt report for the whole codebase. I want to know where to focus first."
+
+```
+get_debt_report(repoId, topN: 5) →
+
+  Technical Debt Report
+
+  Overall Debt Score: 43/100   Grade: C
+
+  ┌─────────────────────┬────────┬──────────────────────────────────────────┐
+  │ Category            │ Score  │ Top Issues                               │
+  ├─────────────────────┼────────┼──────────────────────────────────────────┤
+  │ Complexity          │   38   │ 12 functions with cyclomatic > 10        │
+  │ Structural          │   61   │ 3 circular deps, 8 high-coupling files   │
+  │ Maintainability     │   29   │ 2 god classes, 41 dead exports           │
+  │ Volatility          │   44   │ 5 high-churn files with complexity > 8   │
+  └─────────────────────┴────────┴──────────────────────────────────────────┘
+
+  Top Debt Files:
+
+  1. src/legacy/UserManager.ts          score: 87
+     - cyclomatic complexity avg: 11.4 (34 methods, 4 > 20 complexity)
+     - fan-out: 28 (imports 28 different files)
+     - 0 exports have documentation
+     - modified 47× in the last 6 months (highest churn)
+
+  2. src/utils/helpers.ts               score: 74
+     - 45 symbols across 8 unrelated domains (low cohesion)
+     - fan-in: 41 files depend on it (high blast radius)
+     - 12 dead exports
+
+  3. src/core/billing.ts                score: 68
+     - circular dependency with src/utils/currency.ts
+     - 3 functions with complexity > 12
+     - high churn: modified 31× in 6 months
+
+  4. src/api/routes/legacy.ts           score: 62
+     - 7 functions with complexity > 8
+     - no test references found for 4 exported functions
+
+  5. src/models/user.ts                 score: 58
+     - imported by 34 files (stable hub — risky to change)
+     - 6 dead exports (possibly orphaned during a migration)
+
+  Prioritized Action Items:
+
+  HIGH ROI:
+  • Extract UserManager.ts into focused service classes
+    Reason: highest debt score + highest churn = highest risk
+    Estimated impact: −15 pts on complexity, −8 pts on structural debt
+
+  • Split helpers.ts by domain into 8 focused utility modules
+    Reason: eliminates 41-file blast radius + removes dead code
+    Estimated impact: −12 pts on structural, −5 pts on maintainability
+
+  • Break billing.ts ↔ currency.ts circular dependency
+    Reason: blocking independent testing of both modules
+    Estimated impact: −8 pts on structural debt
+
+  MEDIUM ROI:
+  • Add documentation to top 20 exported symbols in core/
+    Reason: documentation score is pulling down the overall grade
+    Estimated impact: +10 pts on documentation axis in health_radar
+
+  • Delete 41 dead exports (run find_dead_code for the full list)
+    Reason: reduces cognitive load + clarifies the public API surface
+```
+
+The report tells you exactly what to work on: `UserManager.ts` is the highest-priority target (highest debt, highest churn — the most dangerous file in the codebase). `helpers.ts` second. The circular dependency third.
+
+**Narrowing to a subsystem:**
+
+```
+get_debt_report(repoId, scope: "src/core/", topN: 10)
+  → debt analysis restricted to files under src/core/
+```
+
+**For CI integration:**
+
+Run `get_debt_report` in CI and fail the pipeline if the overall debt score exceeds a threshold. Pair it with `diff_health_radar` to catch individual PRs that increase debt.
+
+---
+
+## Using the three tools together
+
+The three tools answer different questions and work best together:
+
+| Tool | When to use | Output |
+|------|------------|--------|
+| `health_radar` | Quick status check: "where are we?" | 5 scores + grade |
+| `diff_health_radar` | Before/after comparison: "did we improve?" | Per-axis deltas |
+| `get_debt_report` | Action planning: "what do we do first?" | Ranked files + action items |
+
+**A monthly rhythm that works:**
+
+```
+1st of the month:
+  health_radar(repoId)
+  → log the scores to track the trend over time
+
+Start of sprint:
+  get_debt_report(repoId, topN: 10)
+  → pick the highest-ROI items for this sprint
+
+End of sprint:
+  diff_health_radar(baseRepoId: "month-start", headRepoId: "current")
+  → measure the sprint's impact on each axis
+
+PR merges:
+  diff_health_radar(baseRepoId: "main", headRepoId: "feature")
+  → catch regressions at the PR level, not the monthly level
+```
+
+---
+
+→ Reference: [MCP Tools Reference](docs/06-tools-reference.md) — `health_radar`, `diff_health_radar`, `get_debt_report`  
+→ See also: [Code Health & Architecture Analysis](CODE-HEALTH.md) — quality metrics, anti-pattern detection

package/README.md

@@ -44,10 +44,16 @@ The guide explains what PureContext does, why each feature exists, and how to us
 | [Navigating a New Codebase](NAVIGATING-NEW-CODE.md) | Day one on an unfamiliar project |
 | [Finding Code](FINDING-CODE.md) | Three search modes with examples |
 | [Making Changes Safely](SAFE-CHANGES.md) | Blast radius and dependency analysis |
+| [Understanding Code Relationships](UNDERSTANDING-RELATIONSHIPS.md) | Call hierarchies, cycles, coupling, implementations |
+| [Refactoring Safely](REFACTORING-SAFELY.md) | Pre-flight checks before rename, delete, or move |
 | [Understanding Code History](CODE-HISTORY.md) | Symbol-level git history and churn |
 | [The Web UI](WEB-UI.md) | Visual graph, heatmap, symbol timeline |
 | [AI Summaries](AI-SUMMARIES.md) | Better search on undocumented codebases |
 | [Code Health & Architecture Analysis](CODE-HEALTH.md) | Quality metrics, anti-patterns, arch docs |
+| [Health Dashboards & Debt Reporting](HEALTH-DASHBOARDS.md) | Health radar, debt scores, PR health diffs |
+| [Visualizing Code Structure](VISUALIZING-CODE.md) | Mermaid/DOT diagrams, architecture snapshots |
+| [AST-Level Search](AST-SEARCH.md) | Node types, signatures, decorators, complexity |
+| [Code Intelligence](CODE-INTELLIGENCE.md) | Entry points, public API, TODOs, coverage |
 | [Using PureContext with a Team](TEAM-SETUP.md) | Shared server, enterprise setup |
 
 **Real-world workflows:**
@@ -57,6 +63,7 @@ The guide explains what PureContext does, why each feature exists, and how to us
 | [Onboarding to a New Codebase](WORKFLOW-ONBOARDING.md) | First day on a 6,000-file microservices platform |
 | [Refactoring Legacy Code](WORKFLOW-REFACTORING.md) | Replacing auth in a 6-year-old Django monolith |
 | [Reviewing a Pull Request](WORKFLOW-PR-REVIEW.md) | 40-file PR, 45 minutes, two real bugs found |
+| [Running a Tech Debt Sprint](WORKFLOW-TECH-DEBT.md) | Two-week debt reduction: assess, plan, execute, measure |
 
 → [Full guide index](USER-GUIDE.md)