milens 0.6.3 → 0.6.4

package/.agents/skills/adapters/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: milens-adapters
+description: Code intelligence for the adapters area — symbols, dependencies, and entry points
+---
+
+# Adapters
+
+## Overview
+Contains 30 symbols (27 exported) across 3 files.
+
+## Key Symbols
+- **`Milens — Code Intelligence for Claude Code`** [section] (adapters/claude-code/CLAUDE.md:1) — 0 refs
+- **`Available Tools`** [section] (adapters/claude-code/CLAUDE.md:5) — 0 refs
+- **`Session Workflow`** [section] (adapters/claude-code/CLAUDE.md:25) — 0 refs
+- **`Edit Safety (Mandatory)`** [section] (adapters/claude-code/CLAUDE.md:33) — 0 refs
+- **`Tool Selection`** [section] (adapters/claude-code/CLAUDE.md:49) — 0 refs
+- **`Reference`** [section] (adapters/claude-code/CLAUDE.md:55) — 0 refs
+- **`Milens — Code Intelligence for OpenCode`** [section] (adapters/opencode/AGENTS.md:1) — 0 refs
+- **`Available Tools`** [section] (adapters/opencode/AGENTS.md:5) — 0 refs
+- **`Session Workflow`** [section] (adapters/opencode/AGENTS.md:25) — 0 refs
+- **`Edit Safety (Mandatory)`** [section] (adapters/opencode/AGENTS.md:33) — 0 refs
+- **`Tool Selection`** [section] (adapters/opencode/AGENTS.md:49) — 0 refs
+- **`Reference`** [section] (adapters/opencode/AGENTS.md:55) — 0 refs
+- **`Milens Adapter Packs`** [section] (adapters/README.md:1) — 0 refs
+- **`What is milens?`** [section] (adapters/README.md:5) — 0 refs
+- **`Available Adapters`** [section] (adapters/README.md:9) — 0 refs
+
+## Files
+- adapters/README.md
+- adapters/claude-code/CLAUDE.md
+- adapters/opencode/AGENTS.md

package/.agents/skills/analyzer/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: milens-analyzer
+description: Code intelligence for the analyzer area — symbols, dependencies, and entry points
+---
+
+# Analyzer
+
+## Overview
+Contains 79 symbols (21 exported) across 7 files.
+
+## Key Symbols
+- **`resolveLinksWithStats`** [function] (src/analyzer/resolver.ts:35) — 5 refs
+- **`loadAliases`** [function] (src/analyzer/config.ts:10) — 4 refs
+- **`analyze`** [function] (src/analyzer/engine.ts:106) — 4 refs
+- **`scanFiles`** [function] (src/analyzer/scanner.ts:11) — 4 refs
+- **`resolveLinks`** [function] (src/analyzer/resolver.ts:30) — 3 refs
+- **`reviewPr`** [function] (src/analyzer/review.ts:101) — 3 refs
+- **`enrichMetadata`** [function] (src/analyzer/enrich.ts:21) — 2 refs
+- **`reviewSymbol`** [function] (src/analyzer/review.ts:167) — 2 refs
+- **`generateTestPlan`** [function] (src/analyzer/testplan.ts:104) — 2 refs
+- **`findCoverageGaps`** [function] (src/analyzer/testplan.ts:175) — 2 refs
+- **`ResolutionResult`** [interface] (src/analyzer/resolver.ts:22) — 1 refs
+- **`ReviewResult`** [interface] (src/analyzer/review.ts:17) — 1 refs
+- **`RiskLevel`** [type] (src/analyzer/review.ts:6) — 1 refs
+- **`TestImpactResult`** [interface] (src/analyzer/testplan.ts:35) — 1 refs
+- **`SymbolRisk`** [interface] (src/analyzer/review.ts:8) — 0 refs
+
+## Entry Points
+- **`find`** [function] — 19 incoming references
+- **`resolve`** [method] — 11 incoming references
+- **`resolveLinksWithStats`** [function] — 5 incoming references
+- **`loadAliases`** [function] — 4 incoming references
+- **`analyze`** [function] — 4 incoming references
+
+## Dependencies
+- **parser**: `langForFile`, `getParser`, `loadLanguage`, `extractFromTree`, `clearQueryCache`, `extractVueScript`, `extractVueTemplateRefs`, `extractHtmlScripts` (+6 more)
+- **root**: `isTestFile`, `CodeSymbol`, `ExtractionResult`, `RawImport`, `RawCall`, `RawHeritage`, `RawReExport`, `RawTypeBinding` (+8 more)
+- **store**: `Database`, `TfIdfProvider`, `EmbeddingStore`, `buildEmbeddingText`, `get`, `clear`, `isFileUpToDate`, `upsertFileHash` (+22 more)
+
+## Used By
+- **root**: `loadAliases`, `analyze`, `resolve`, `clear`
+- **server**: `reviewPr`, `resolve`, `find`
+- **test**: `resolveLinks`, `resolveLinksWithStats`, `reviewSymbol`, `scanFiles`, `generateTestPlan`, `findCoverageGaps`, `analyze`, `loadAliases` (+1 more)
+- **scripts**: `resolve`
+- **parser**: `find`, `resolve`
+- **store**: `find`, `resolve`
+
+## Files
+- src/analyzer/config.ts
+- src/analyzer/engine.ts
+- src/analyzer/enrich.ts
+- src/analyzer/resolver.ts
+- src/analyzer/review.ts
+- src/analyzer/scanner.ts
+- src/analyzer/testplan.ts

package/.agents/skills/apps/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: milens-apps
+description: Code intelligence for the apps area — symbols, dependencies, and entry points
+---
+
+# Apps
+
+## Overview
+Contains 34 symbols (12 exported) across 10 files.
+
+## Key Symbols
+- **`Milens Desktop Dashboard`** [section] (apps/dashboard/README.md:1) — 0 refs
+- **`Features`** [section] (apps/dashboard/README.md:5) — 0 refs
+- **`Development`** [section] (apps/dashboard/README.md:13) — 0 refs
+- **`Build`** [section] (apps/dashboard/README.md:19) — 0 refs
+- **`Milens GitHub App`** [section] (apps/github/README.md:1) — 0 refs
+- **`Features`** [section] (apps/github/README.md:5) — 0 refs
+- **`Deployment`** [section] (apps/github/README.md:10) — 0 refs
+- **`Local Development`** [section] (apps/github/README.md:15) — 0 refs
+- **`AgentsMdGenerator`** [class] (apps/github/generators/agents-md.js:1) — 0 refs
+- **`SecurityGenerator`** [class] (apps/github/generators/security.js:1) — 0 refs
+- **`SkillsGenerator`** [class] (apps/github/generators/skills.js:1) — 0 refs
+- **`MilensRunner`** [class] (apps/github/handlers/milens-runner.js:6) — 0 refs
+
+## Entry Points
+- **`createWindow`** [function] — 1 incoming references
+- **`__dirname`** [variable] — 1 incoming references
+
+## Dependencies
+- **store**: `remove`, `Database`, `getCodebaseSummary`, `close`
+
+## Files
+- apps/dashboard/README.md
+- apps/dashboard/index.html
+- apps/dashboard/main.js
+- apps/dashboard/preload.js
+- apps/github/README.md
+- apps/github/app.js
+- apps/github/generators/agents-md.js
+- apps/github/generators/security.js
+- apps/github/generators/skills.js
+- apps/github/handlers/milens-runner.js

package/.agents/skills/docs/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: milens-docs
+description: Code intelligence for the docs area — symbols, dependencies, and entry points
+---
+
+# Docs
+
+## Overview
+Contains 266 symbols (253 exported) across 12 files.
+
+## Key Symbols
+- **`Adapter Packs`** [section] (docs/adapters.md:1) — 0 refs
+- **`Available Adapters`** [section] (docs/adapters.md:5) — 0 refs
+- **`Quick Install`** [section] (docs/adapters.md:17) — 0 refs
+- **`Claude Code`** [section] (docs/adapters.md:21) — 0 refs
+- **`OpenCode`** [section] (docs/adapters.md:29) — 0 refs
+- **`Cursor`** [section] (docs/adapters.md:36) — 0 refs
+- **`GitHub Copilot`** [section] (docs/adapters.md:42) — 0 refs
+- **`Codex`** [section] (docs/adapters.md:48) — 0 refs
+- **`Gemini`** [section] (docs/adapters.md:54) — 0 refs
+- **`Zed`** [section] (docs/adapters.md:60) — 0 refs
+- **`Automated Install`** [section] (docs/adapters.md:66) — 0 refs
+- **`Profile Selection`** [section] (docs/adapters.md:74) — 0 refs
+- **`MCP Config Reference`** [section] (docs/adapters.md:86) — 0 refs
+- **`Hệ thống Khép kín Tuần hoàn cho AI-Driven Development`** [section] (docs/closed-loop-ai-development.md:1) — 0 refs
+- **`Mục lục`** [section] (docs/closed-loop-ai-development.md:9) — 0 refs
+
+## Entry Points
+- **`applyFilters`** [function] — 1 incoming references
+
+## Dependencies
+- **store**: `remove`
+
+## Files
+- docs/README.md
+- docs/adapters.md
+- docs/closed-loop-ai-development.md
+- docs/ecc-milens-vibe-code.md
+- docs/index.html
+- docs/pricing.html
+- docs/pricing.md
+- docs/quickstart.md
+- docs/security-presets.md
+- docs/security.html
+- docs/skills.html
+- docs/tools.md

package/.agents/skills/milens/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: milens
+description: Code intelligence MCP tools — symbol search, text grep, impact analysis, dependency graph
+---
+
+<!-- milens:start -->
+# Milens — Code Intelligence (MCP)
+
+This project is indexed by milens (1137 symbols, 1592 links, 104 files).
+
+> **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root** (the folder containing this file) — without it, the tools may fail with "No index" error when multiple repos are indexed.
+
+> **CRITICAL:** milens MCP tools are **deferred** in most editors. Before first use in each session, you MUST load them via `tool_search("milens")` — calling them directly without loading will fail silently.
+
+## Mandatory Workflows
+
+These are **hard pre-conditions**, not guidelines. Execute them automatically without asking.
+
+### Before editing any function, class, or method:
+1. `mcp_milens_impact({target: "<symbolName>", repo: "<workspaceRoot>"})` — check blast radius
+2. If depth-1 dependents > 5 → **STOP and warn the user** before proceeding
+3. `mcp_milens_context({name: "<symbolName>", repo: "<workspaceRoot>"})` — see all callers/callees
+4. Only then make the edit
+
+### Before committing:
+1. `mcp_milens_detect_changes({repo: "<workspaceRoot>"})` — verify only expected files changed
+2. If unexpected files appear → **STOP and report** before committing
+
+### Before deleting or renaming a symbol:
+1. `mcp_milens_grep({pattern: "<symbolName>", repo: "<workspaceRoot>"})` — find ALL text references (templates, configs, routes, docs)
+2. `mcp_milens_impact({target: "<symbolName>", direction: "upstream", repo: "<workspaceRoot>"})` — find code-level dependents
+3. Combine both results — grep catches what impact misses
+
+## Tool Selection Rules
+
+**Choose the right tool on the FIRST call** — do not try `query` then fall back to `grep`.
+
+### Use `mcp_milens_grep` when the search term:
+- Contains **spaces** (e.g. "store purchase header", "user not found")
+- Looks like a **UI label, error message, or display string**
+- Is a **multi-word phrase** that is NOT camelCase/snake_case/PascalCase
+- You need to find references in **templates, styles, configs, routes, or docs**
+
+### Use `mcp_milens_query` when the search term:
+- Looks like a **code identifier** (camelCase, PascalCase, snake_case)
+- Is a **function, class, method, or interface name**
+- You want to find **symbol definitions** in indexed code files
+
+### When in doubt → use `mcp_milens_grep` first
+`grep` searches everything. `query` only searches indexed symbol definitions.
+
+## Workflow Triggers
+
+When the user says... → do this FIRST:
+
+| User intent | First action |
+|---|---|
+| "edit/change/modify/fix `X`" | `mcp_milens_impact({target: "X", repo: "<workspaceRoot>"})` |
+| "delete/remove `X`" | `mcp_milens_grep({pattern: "X", repo: "<workspaceRoot>"})` then `mcp_milens_impact` |
+| "rename `X`" | `mcp_milens_grep({pattern: "X", repo: "<workspaceRoot>"})` then `mcp_milens_impact` |
+| "find/search for `X`" | Choose `query` or `grep` per rules above |
+| "commit" / "push" | `mcp_milens_detect_changes({repo: "<workspaceRoot>"})` |
+| "what calls/uses `X`" | `mcp_milens_context({name: "X", repo: "<workspaceRoot>"})` |
+| "what happens if I change `X`" | `mcp_milens_impact({target: "X", repo: "<workspaceRoot>"})` |
+| "how are `A` and `B` connected" | `mcp_milens_explain_relationship({from: "A", to: "B", repo: "<workspaceRoot>"})` |
+| "explore/understand `X`" | `mcp_milens_context({name: "X", repo: "<workspaceRoot>"})` |
+| "update/write docs for `X`" | `mcp_milens_grep({pattern: "X", include: "**/*.md"})` — find existing docs mentioning X, then `mcp_milens_context({name: "X"})` for full symbol info |
+| "research/explore docs" | `mcp_milens_get_file_symbols({file: "<doc.md>"})` — see document outline (headings as sections) |
+| "what docs mention `X`" | `mcp_milens_grep({pattern: "X", include: "**/*.md"})` — find all markdown references |
+| "review this PR" | `mcp_milens_review_pr({repo: "<workspaceRoot>"})` — risk assessment for changed files |
+| "is `X` risky to change" | `mcp_milens_review_symbol({name: "X", repo: "<workspaceRoot>"})` |
+| "write tests for `X`" | `mcp_milens_test_plan({name: "X", repo: "<workspaceRoot>"})` — deps, mocks, suggested tests |
+| "what needs tests" | `mcp_milens_test_coverage_gaps({repo: "<workspaceRoot>"})` — untested symbols by risk |
+| "which tests to run" | `mcp_milens_test_impact({repo: "<workspaceRoot>"})` — maps changes → test files |
+| "remember/note that `X`..." | `mcp_milens_annotate({symbol: "X", key: "note", value: "...", repo: "<workspaceRoot>"})` |
+| "what do we know about `X`" | `mcp_milens_recall({symbol: "X", repo: "<workspaceRoot>"})` |
+| "start new session" | `mcp_milens_session_start({agent: "...", repo: "<workspaceRoot>"})` |
+| "find code like `X`" | `mcp_milens_find_similar({name: "X", repo: "<workspaceRoot>"})` |
+| "search for `concept`" | `mcp_milens_semantic_search({query: "concept", repo: "<workspaceRoot>"})` |
+
+## Documentation Workflows
+
+Milens indexes **Markdown files** (.md, .mdx) — headings become `section` symbols with parent-child hierarchy, and local links become cross-file references.
+
+### Researching or exploring documentation:
+1. `mcp_milens_get_file_symbols({file: "README.md", repo: "<workspaceRoot>"})` — see the full heading outline (TOC) of any doc
+2. `mcp_milens_query({query: "<topic>"})` — search section headings across all docs and code
+3. `mcp_milens_grep({pattern: "<keyword>", include: "**/*.md"})` — text search within docs only
+
+### Before updating documentation:
+1. `mcp_milens_get_file_symbols({file: "<doc.md>"})` — understand document structure first
+2. If documenting a code symbol: `mcp_milens_context({name: "<symbolName>"})` — get full symbol info (signature, callers, deps)
+3. `mcp_milens_grep({pattern: "<symbolName>", include: "**/*.md"})` — check if other docs already reference it
+
+### After renaming/deleting a code symbol:
+- `mcp_milens_grep({pattern: "<oldName>", include: "**/*.md"})` — find docs that need updating (milens indexes markdown links as cross-file references)
+
+## Never Do
+
+- NEVER edit a symbol without first running `mcp_milens_impact` on it.
+- NEVER delete or rename without running both `mcp_milens_grep` and `mcp_milens_impact`.
+- NEVER commit without running `mcp_milens_detect_changes()`.
+- NEVER call milens MCP tools without the `repo` parameter.
+- NEVER use `mcp_milens_query` for multi-word display text or UI labels — use `mcp_milens_grep`.
+
+---
+
+## Reference
+
+### Tools
+
+| Tool | Purpose |
+|---|---|
+| `mcp_milens_query` | Find symbol definitions by name (FTS5) |
+| `mcp_milens_grep` | Text search ALL files (templates, styles, configs, docs) |
+| `mcp_milens_context` | 360° view: incoming refs + outgoing deps |
+| `mcp_milens_impact` | Blast radius before editing |
+| `mcp_milens_detect_changes` | Pre-commit scope check |
+| `mcp_milens_explain_relationship` | Shortest path between two symbols |
+| `mcp_milens_get_file_symbols` | All symbols in a file |
+| `mcp_milens_get_type_hierarchy` | Class inheritance tree |
+| `mcp_milens_find_dead_code` | Unused exported symbols |
+| `mcp_milens_status` | Index health check |
+| `mcp_milens_edit_check` | Pre-edit safety: callers + export status + re-export chains + test coverage |
+| `mcp_milens_trace` | Execution flow: call chains from entrypoints to a symbol |
+| `mcp_milens_routes` | Detect framework routes/endpoints (Express, FastAPI, NestJS, etc.) |
+| `mcp_milens_smart_context` | Intent-aware context: understand/edit/debug/test |
+| `mcp_milens_overview` | Combined context + impact + grep in one call |
+| `mcp_milens_domains` | Domain clusters: groups of files forming logical modules |
+| `mcp_milens_repos` | List all indexed repositories with summary stats |
+| `mcp_milens_ast_explore` | Explore raw AST structure of a code file |
+| `mcp_milens_test_query` | Run raw SQL query against the milens index database |
+| `mcp_milens_review_pr` | PR risk assessment: scores changed symbols by blast radius + test coverage |
+| `mcp_milens_review_symbol` | Single symbol risk: role, heat, dependents, test status |
+| `mcp_milens_test_plan` | Dependency-aware test plan: mocks, strategies, suggested tests |
+| `mcp_milens_test_coverage_gaps` | Untested exported symbols sorted by risk |
+| `mcp_milens_test_impact` | Which tests to run for current changes |
+| `mcp_milens_annotate` | Store observation/note about a symbol (persists across sessions) |
+| `mcp_milens_recall` | Retrieve annotations (filter by symbol, key, agent, session) |
+| `mcp_milens_session_start` | Register agent session for multi-agent coordination |
+| `mcp_milens_session_context` | Get session metadata + annotations |
+| `mcp_milens_handoff` | Transfer context between agent sessions |
+| `mcp_milens_codebase_summary` | High-level bootstrapping context: domains, key symbols, coverage |
+| `mcp_milens_semantic_search` | Hybrid FTS5 + vector search (requires --embeddings) |
+| `mcp_milens_find_similar` | Find symbols similar by embedding proximity |
+
+### Keeping the Index Fresh
+
+After significant code changes: `npx milens analyze -p . --force`
+
+### Skills
+
+| Task | Read this skill file |
+|------|---------------------|
+| General milens tools reference | `.agents/skills/milens/SKILL.md` |
+| Work in the Adapters area | `.agents/skills/adapters/SKILL.md` |
+| Work in the Root area | `.agents/skills/root/SKILL.md` |
+| Work in the Apps area | `.agents/skills/apps/SKILL.md` |
+| Work in the Docs area | `.agents/skills/docs/SKILL.md` |
+| Work in the Test area | `.agents/skills/test/SKILL.md` |
+| Work in the Scripts area | `.agents/skills/scripts/SKILL.md` |
+| Work in the Analyzer area | `.agents/skills/analyzer/SKILL.md` |
+| Work in the Parser area | `.agents/skills/parser/SKILL.md` |
+| Work in the Security area | `.agents/skills/security/SKILL.md` |
+| Work in the Server area | `.agents/skills/server/SKILL.md` |
+| Work in the Store area | `.agents/skills/store/SKILL.md` |
+
+<!-- milens:end -->

package/.agents/skills/milens-code-review/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: milens-code-review
+description: Automated Code Review — PR analysis, symbol deep-dive, dead code detection, tech debt grep, and review report
+---
+
+# milens-code-review — Automated Code Review
+
+Analyze a PR or local changes with multi-layered review: risk scoring, symbol deep-dives, dead code audit, tech debt search, and a structured report.
+
+## Tools Required
+
+| Tool | Purpose |
+|---|---|
+| `mcp_milens_review_pr` | List changed files + affected symbols with risk scores |
+| `mcp_milens_review_symbol` | Deep-dive on a single symbol (role, heat, dependents, test status) |
+| `mcp_milens_context` | Incoming references + outgoing dependencies |
+| `mcp_milens_find_dead_code` | Find exported symbols with zero references |
+| `mcp_milens_grep` | Text search for tech debt markers and dangerous patterns |
+
+> **CRITICAL:** All milens MCP tool calls MUST include the `repo` parameter set to the **absolute path of the workspace root**.
+
+## Workflow
+
+### Step 1: PR Overview
+
+Start with the full PR-level assessment.
+
+```
+mcp_milens_review_pr({repo: "<workspaceRoot>"})
+```
+
+Review the output for:
+- **Changed files** — what was touched
+- **Affected symbols** — each with a risk score (CRITICAL, HIGH, MEDIUM, LOW)
+- **Risk summary** — distribution of risk levels across the change
+
+### Step 2: Deep-Dive on High-Risk Symbols
+
+For every symbol rated CRITICAL or HIGH, perform a deep-dive.
+
+```
+mcp_milens_review_symbol({name: "<symbolName>", repo: "<workspaceRoot>"})
+```
+
+What you get:
+- **Role** — what the symbol does in the architecture
+- **Heat** — frequency of changes, complexity, fan-in/fan-out
+- **Dependents count** — how many things break if this is wrong
+- **Test status** — whether it has test coverage
+
+### Step 3: Context for High-Risk Symbols
+
+Still for CRITICAL/HIGH symbols, get 360° context.
+
+```
+mcp_milens_context({name: "<symbolName>", repo: "<workspaceRoot>"})
+```
+
+This reveals:
+- **Incoming references** — who depends on this symbol
+- **Outgoing calls** — what this symbol depends on
+- **Re-export chains** — if the symbol is re-exported through barrel files
+
+### Step 4: Dead Code Audit
+
+Check for exported symbols with zero references (potential dead code).
+
+```
+mcp_milens_find_dead_code({repo: "<workspaceRoot>", limit: 20})
+```
+
+Flag any dead code that is:
+- Newly introduced by this PR
+- In files touched by this PR
+- Adjacent to changed code (same module)
+
+### Step 5: Tech Debt Search
+
+Search for tech debt markers and debugging remnants.
+
+```
+mcp_milens_grep({pattern: "TODO|FIXME|HACK|console\\.(log|debug)", scope: "code", repo: "<workspaceRoot>"})
+```
+
+Also check for:
+- Commented-out code
+- `@ts-ignore` or `@ts-expect-error` (TypeScript)
+- `# noqa` or `# type: ignore` (Python)
+- Empty catch blocks
+
+### Step 6: Produce Review Report
+
+Consolidate findings into a review report with these sections:
+
+1. **Summary** — files changed, risk distribution
+2. **Symbol Deep-Dives** — one entry per CRITICAL/HIGH symbol with findings from Steps 2-3
+3. **Dead Code** — symbols flagged from Step 4, with recommendations
+4. **Tech Debt** — markers found in Step 5, with severity
+5. **Recommendations** — prioritized list of actions (blocking vs. non-blocking)
+6. **Verdict** — APPROVED / NEEDS CHANGES / BLOCKED
+
+## Example Session
+
+### Input
+
+```
+"review the PR for branch feature/auth-refactor"
+```
+
+### Tool Calls
+
+**Step 1 — PR overview:**
+```
+mcp_milens_review_pr({repo: "/home/user/project"})
+```
+
+**Output:**
+```
+Changed files (4):
+  src/auth/login.ts          [modified]
+  src/auth/tokens.ts         [new]
+  src/auth/types.ts          [modified]
+  src/middleware/auth.ts     [modified]
+
+Affected symbols:
+  authenticate    [function]  CRITICAL  — 15 dependents, no tests
+  generateToken   [function]  HIGH      — 8 dependents, 1 test
+  UserSession     [interface] MEDIUM    — 5 dependents
+  validateRole    [function]  LOW       — 2 dependents
+```
+
+**Step 2 — Deep-dive on CRITICAL symbol:**
+```
+mcp_milens_review_symbol({name: "authenticate", repo: "/home/user/project"})
+```
+
+**Output:**
+```
+Symbol: authenticate [function] — CRITICAL
+  Role: core auth entry point, all protected routes depend on it
+  Heat: 23 commits in last 90 days, 87% modification rate
+  Dependents: 15 (12 direct callers + 3 middleware wrappers)
+  Test status: 0 tests, 0% coverage
+  Complexity: high (cyclomatic 14, 5 branching paths)
+```
+
+**Step 3 — Context:**
+```
+mcp_milens_context({name: "authenticate", repo: "/home/user/project"})
+```
+
+**Output:** 15 incoming refs (routes, middleware), 4 outgoing deps (token validation, user lookup, logger, rate limiter)
+
+**Step 4 — Dead code:**
+```
+mcp_milens_find_dead_code({repo: "/home/user/project", limit: 20})
+```
+
+**Output:** `legacyAuthCheck` in the same module has 0 references — candidate for removal.
+
+**Step 5 — Tech debt:**
+```
+mcp_milens_grep({pattern: "TODO|FIXME|HACK|console\\.(log|debug)", scope: "code", repo: "/home/user/project"})
+```
+
+**Output:** 3 matches — 1 `console.log` in tokens.ts, 2 `TODO` comments in login.ts.
+
+**Step 6 — Report produced** (see report format above).
+
+## Best Practices
+
+1. **Don't skip the deep-dive.** CRITICAL symbols demand `review_symbol` + `context` — surface-level review misses cascading failures.
+2. **Dead code in the diff is a red flag.** If a new symbol has zero references, question whether it belongs in this PR.
+3. **Tech debt in new code is a blocker.** `console.log`, `FIXME`, or debug code should not ship. Flag it as blocking.
+4. **Risk score drives review depth.** HIGH/CRITICAL = full deep-dive. MEDIUM = quick context check. LOW = skip unless it's a new file.
+5. **Produce a written report.** Don't just run the tools — consolidate findings into a review document the team can reference.
+
+## Quality Gate
+
+| Criteria | Pass | Fail |
+|---|---|---|
+| PR review tool | Review completes without errors | Tool fails or returns partial data |
+| Risk assessment | All CRITICAL/HIGH symbols deep-dived | Any CRITICAL symbol skipped |
+| Dead code check | No newly introduced dead code | New dead code found in changed files |
+| Tech debt grep | No debug code (`console.log`, etc.) | Debug/leftover code in diff |
+| Report completeness | All 6 report sections filled | Missing sections or incomplete findings |