@nano-step/skill-manager 5.6.1 → 5.6.2

package/skills/feature-analysis/SKILL.md

@@ -0,0 +1,290 @@
+---
+name: feature-analysis
+description: "Deep code analysis of any feature or service before writing docs, diagrams, or making changes. Enforces read-everything-first discipline. Traces exact execution paths, data transformations, guard clauses, bugs, and gaps between existing docs and actual code. Produces a validated Mermaid diagram and structured analysis output. Language and framework agnostic."
+compatibility: "OpenCode"
+metadata:
+  version: "2.0.0"
+tools:
+  required:
+    - Read (every file in the feature)
+    - Bash (find all files, run mermaid validator)
+  uses:
+    - mermaid-validator skill (validate any diagram produced)
+triggers:
+  - "analyze [feature]"
+  - "how does X work"
+  - "trace the flow of"
+  - "understand X"
+  - "what does X do"
+  - "deep dive into"
+  - "working on X - understand it first"
+  - "update docs/brain for"
+---
+
+# Feature Analysis Skill
+
+A disciplined protocol for deeply analyzing any feature in any codebase before producing docs, diagrams, or making changes. Framework-agnostic. Language-agnostic.
+
+---
+
+## The Core Rule
+
+**READ EVERYTHING. PRODUCE NOTHING. THEN SYNTHESIZE.**
+
+Do not write a single diagram node, doc line, or description until every file in the feature has been read. Every time you produce output before reading all files, you will miss something.
+
+---
+
+## Phase 1: Discovery — Find Every File
+
+Before reading anything, map the full file set.
+
+```bash
+# Find all source files for the feature
+find <feature-dir> -type f | sort
+
+# Check imports to catch shared utilities, decorators, helpers
+grep -r "import\|require" <feature-dir> | grep -v node_modules | sort -u
+```
+
+**Read in dependency order (bottom-up — foundations first):**
+
+1. **Entry point / bootstrap** — port, env vars, startup config
+2. **Schema / model files** — DB schema, columns, nullable, indexes, types
+3. **Utility / helper files** — every function, every transformation, every constant
+4. **Decorator / middleware files** — wrapping logic, side effects, return value handling
+5. **Infrastructure services** — cache, lock, queue, external connections
+6. **Core business logic** — the main service/handler files
+7. **External / fetch services** — HTTP calls, filters applied, error handling
+8. **Entry controllers / routers / handlers** — HTTP method, route, params, return
+9. **Wiring files** — module/DI config, middleware registration
+
+**Do not skip any file. Do not skim.**
+
+---
+
+## Phase 2: Per-File Checklist
+
+For each file, answer these questions before moving to the next.
+
+### Entry point / bootstrap
+- [ ] What port or address? (default? env override?)
+- [ ] Any global middleware, pipes, interceptors, or lifecycle hooks?
+
+### Schema / model files
+- [ ] Table/collection name
+- [ ] Every field: type, nullable, default, constraints, indexes
+- [ ] Relations / references to other entities
+
+### Utility / helper files
+- [ ] Every exported function — what does it do, step by step?
+- [ ] For transformations: what inputs? what outputs? what edge cases handled?
+- [ ] Where is this function called? (grep for usages)
+- [ ] How many times is it called within a single method? (once per batch? once per item?)
+
+### Decorator / middleware files
+- [ ] What does it wrap?
+- [ ] What side effects before / after the original method?
+- [ ] **Does it `return` the result of the original method?** (missing `return` = silent discard bug)
+- [ ] Does it use try/finally? What runs in finally?
+- [ ] What happens on the early-exit path?
+
+### Core business logic files
+- [ ] Every method: signature, return type
+- [ ] For each method: trace every line — no summarizing
+- [ ] Accumulator variables — where initialized, where incremented, where returned
+- [ ] Loop structure: sequential or parallel?
+- [ ] Every external call: what service/module, what args, what returned
+- [ ] Guard clauses: every early return / continue / throw
+- [ ] Every branch in conditionals
+
+### External / fetch service files
+- [ ] Exact URLs or endpoints (hardcoded or env?)
+- [ ] Filters applied to response data (which calls filter, which don't?)
+- [ ] Error handling on external calls
+
+### Entry controllers / routers / handlers
+- [ ] HTTP method (GET vs POST — don't assume)
+- [ ] Route path
+- [ ] What core method is called?
+- [ ] What is returned?
+
+### Wiring / module files
+- [ ] What is imported / registered?
+- [ ] What is exported / exposed?
+
+---
+
+## Phase 3: Execution Trace
+
+After reading all files, produce a numbered step-by-step trace of the full execution path. This is not prose — it is a precise trace.
+
+**Format:**
+```
+1. [HTTP METHOD] /route → HandlerName.methodName()
+2. HandlerName.methodName() → ServiceName.methodName()
+3. @DecoratorName: step A (e.g. acquire lock, check cache)
+4.   → if condition X: early return [what is returned / not returned]
+5. ServiceName.methodName():
+6.   step 1: call externalService.fetchAll() → parallel([fetchA(), fetchB()])
+7.     fetchA(): GET https://... → returns all items (no filter)
+8.     fetchB(): GET https://... → filter(x => x.field !== null) → returns filtered
+9.   step 2: parallel([processItems(a, 'typeA'), processItems(b, 'typeB')])
+10. processItems(items, type):
+11.   init: totalUpdated = 0, totalInserted = 0
+12.   for loop (sequential): i = 0 to items.length, step batchSize
+13.     batch = items.slice(i, i + batchSize)
+14.     { updated, inserted } = await processBatch(batch)
+15.     totalUpdated += updated; totalInserted += inserted
+16.   return { total: items.length, updated: totalUpdated, inserted: totalInserted }
+17. processBatch(batch):
+18.   guard: if batch.length === 0 → return { updated: 0, inserted: 0 }
+19.   step 1: names = batch.map(item => transform(item.field))   ← called ONCE per batch
+20.   step 2: existing = repo.find(WHERE field IN names)
+21.   step 3: map = existing.reduce(...)
+22.   step 4: for each item in batch:
+23.     value = transform(item.field)   ← called AGAIN per item
+24.     ...decision tree...
+25.   repo.save(itemsToSave)
+26.   return { updated, inserted }
+27. @DecoratorName finally: releaseLock()
+28. BUG: decorator does not return result → caller receives undefined
+```
+
+**Key things to call out in the trace:**
+- When a utility function is called more than once (note the count and context)
+- Every accumulator variable (where init, where increment, where return)
+- Every guard clause / early exit
+- Sequential vs parallel (for loop vs Promise.all / asyncio.gather / goroutines)
+- Any discarded return values
+
+---
+
+## Phase 4: Data Transformations Audit
+
+For every utility/transformation function used:
+
+| Function | What it does (step by step) | Called where | Called how many times |
+|----------|----------------------------|--------------|----------------------|
+| `transformFn(x)` | 1. step A 2. step B 3. step C | methodName | TWICE: once in step N (batch), once per item in loop |
+
+---
+
+## Phase 5: Gap Analysis — Docs vs Code
+
+Compare existing docs/brain files against what the code actually does:
+
+| Claim in docs | What code actually does | Verdict |
+|---------------|------------------------|---------|
+| "POST /endpoint" | `@Get()` in controller | ❌ Wrong |
+| "Port 3000" | `process.env.PORT \|\| 4001` in entrypoint | ❌ Wrong |
+| "function converts X" | Also does Y (undocumented) | ⚠️ Incomplete |
+| "returns JSON result" | Decorator discards return value | ❌ Bug |
+
+---
+
+## Phase 6: Produce Outputs
+
+Only now, after phases 1–5 are complete, produce:
+
+### 6a. Structured Analysis Document
+
+```markdown
+## Feature Analysis: [Feature Name]
+Repo: [repo] | Date: [date]
+
+### Files Read
+- `path/to/controller.ts` — entry point, GET /endpoint, calls ServiceA.run()
+- `path/to/service.ts` — core logic, orchestrates fetch + batch loop
+- [... every file ...]
+
+### Execution Trace
+[numbered trace from Phase 3]
+
+### Data Transformations
+[table from Phase 4]
+
+### Guard Clauses & Edge Cases
+- processBatch: empty batch guard → returns {0,0} immediately
+- fetchItems: filters items where field === null
+- LockManager: if lock not acquired → returns void immediately (no error thrown)
+
+### Bugs / Issues Found
+- path/to/decorator.ts line N: `await originalMethod.apply(this, args)` missing `return`
+  → result is discarded, caller always receives undefined
+- [any others]
+
+### Gaps: Docs vs Code
+[table from Phase 5]
+
+### Files to Update
+- [ ] `.agents/_repos/[repo].md` — update port, endpoint method, transformation description
+- [ ] `.agents/_domains/[domain].md` — if architecture changed
+```
+
+### 6b. Mermaid Diagram
+
+Write the diagram. Then **immediately run the validator before doing anything else.**
+
+If you have the mermaid-validator skill:
+```bash
+node /path/to/project/scripts/validate-mermaid.mjs [file.md]
+```
+
+Otherwise validate manually — common syntax errors:
+- Labels with `()` must be wrapped in `"double quotes"`: `A["method()"]`
+- No `\n` in node labels — use `<br/>` or shorten
+- No HTML entities (`&amp;`, `&gt;`) in labels — use literal characters
+- `end` is a reserved word in Mermaid — use `END` or `done` as node IDs
+
+If errors → fix → re-run. Do not proceed until clean.
+
+**Diagram must include:**
+- Every step from the execution trace
+- Data transformation nodes (show what the function does, not just its name)
+- Guard clauses as decision nodes
+- Parallel vs sequential clearly distinguished
+- Bugs annotated inline (e.g. "BUG: result discarded")
+
+### 6c. Doc / Brain File Updates
+
+Update relevant docs with:
+- Corrected facts (port, endpoint method, etc.)
+- The validated Mermaid diagram
+- Data transformation table
+- Known bugs section
+
+---
+
+## Anti-Patterns (What This Skill Prevents)
+
+| Anti-pattern | What gets missed | Rule violated |
+|---|---|---|
+| Drew diagram before reading utility files | Transformation called twice — not shown | READ EVERYTHING FIRST |
+| Trusted existing docs for endpoint method | GET vs POST wrong in docs | GAP ANALYSIS required |
+| Summarized service method instead of tracing | Guard clause (empty batch) missed | TRACE NOT SUMMARIZE |
+| Trusted existing docs for port/config | Wrong values | Verify entry point |
+| Read decorator without checking return | Silent result discard bug | RETURN VALUE AUDIT |
+| Merged H1/H2 paths into shared loop node | Sequential vs parallel distinction lost | TRACE LOOP STRUCTURE |
+| Assumed filter applies to all fetches | One fetch had no filter — skipped items | READ EVERY FETCH FILE |
+
+---
+
+## Quick Reference Checklist
+
+Before producing any output, verify:
+
+- [ ] Entry point read — port/address confirmed
+- [ ] All schema/model files read — every field noted
+- [ ] All utility files read — every transformation step documented
+- [ ] All decorator/middleware files read — return value audited
+- [ ] All core service files read — every method traced line by line
+- [ ] All fetch/external services read — filters noted (which have filters, which don't)
+- [ ] All controller/router/handler files read — HTTP method confirmed (not assumed)
+- [ ] All wiring/module files read — dependency graph understood
+- [ ] Utility functions: call count per method noted
+- [ ] All guard clauses documented
+- [ ] Accumulator variables traced (init → increment → return)
+- [ ] Loop structure confirmed (sequential vs parallel)
+- [ ] Existing docs compared against code (gap analysis done)
+- [ ] Mermaid diagram validated before saving

package/skills/feature-analysis/skill.json

@@ -0,0 +1,15 @@
+{
+    "name": "feature-analysis",
+    "version": "2.0.0",
+    "description": "Deep code analysis of any feature or service before writing docs, diagrams, or making changes. Enforces read-everything-first discipline with execution tracing, data transformation audits, and gap analysis.",
+    "compatibility": "OpenCode",
+    "agent": null,
+    "commands": [],
+    "tags": [
+        "analysis",
+        "code-review",
+        "documentation",
+        "mermaid",
+        "tracing"
+    ]
+}

package/skills/nano-brain/skill.json

@@ -5,6 +5,13 @@
     "compatibility": "OpenCode",
     "agent": null,
     "commands": [],
+    "mcp": {
+        "nano-brain": {
+            "type": "remote",
+            "url": "http://host.docker.internal:3100/mcp",
+            "enabled": true
+        }
+    },
     "tags": [
         "memory",
         "persistence",

package/skills/pr-code-reviewer/CHANGELOG.md

@@ -0,0 +1,287 @@
+# PR Code Reviewer Changelog
+
+## v3.1.0 (2026-03-16) - Verification Pipeline (False Positive Reduction)
+
+**FIX**: ~50% of critical/warning findings were false positives because subagents inspected code locally without verifying the full execution context. This release adds a 3-layer verification pipeline that reduces false positives to ~10%.
+
+### Added
+- **VERIFICATION PROTOCOL** in all 4 subagent prompts — mandatory 4-step process (IDENTIFY → TRACE → VERIFY → DECIDE) before reporting any critical/warning finding
+- **Evidence field** (`evidence`, `confidence`, `trace_path`) in finding schema — subagents must cite concrete file:line proof for critical/warning findings
+- **Evidence examples** (good vs bad) in filtering rules — teaches subagents what constitutes valid evidence
+- **Consensus scoring** in Phase 4 — tracks how many subagents independently flagged the same issue; single-agent findings without evidence are auto-downgraded
+- **Phase 4.5: Orchestrator Verification Spot-Check** — orchestrator reads actual code at cited evidence locations to verify critical/warning findings (30s timeout per finding)
+- **`phase-4.5-verification.json` checkpoint** — tracks verification results for resumability
+- **Verification metadata in report TL;DR** — shows how many findings were dropped as false positives
+
+### Changed
+- Phase 4 now includes consensus scoring step after deduplication
+- Phase 4 checkpoint `next_phase` updated from `5` to `4.5`
+- Manifest schema includes Phase 4.5 in `phase_status`
+- Finding schema in SKILL.md Phase 3 updated to include new fields
+- All 4 subagent return format sections updated with `evidence`, `confidence`, `trace_path`
+
+### How It Works
+1. **Layer 1 (Subagent self-verification)**: Subagents trace error handling to HTTP boundary, null safety to data source, framework patterns to usage context — before reporting
+2. **Layer 2 (Orchestrator spot-check)**: Orchestrator reads cited files and verifies evidence claims for critical/warning findings
+3. **Layer 3 (Consensus scoring)**: Multi-agent agreement boosts confidence; single-agent findings without evidence are downgraded
+
+## v2.7.0 (2026-03-09) - Clone to Temp Folder
+
+**FIX**: Reviews now clone the PR branch into a unique temp folder instead of checking out locally. Prevents branch conflicts and enables simultaneous multi-PR reviews.
+
+### Added
+- **Phase 0: Repository Preparation (Clone to Temp)** — MANDATORY pre-review step
+  - Creates unique temp dir: `/tmp/pr-review-{repo}-{pr}-{unix_timestamp}`
+  - Shallow clones repo with `--depth=50 --branch={head_branch}`
+  - Falls back to `gh pr checkout` if branch not found on remote
+  - Verifies clone succeeded before proceeding
+  - Records `$REVIEW_DIR` path for all subsequent phases
+- **Phase 6: Cleanup** — asks user before removing temp folder (NEVER auto-deletes)
+  - Shows folder path and size
+  - Requires explicit user confirmation to delete
+  - Handles multiple PR temp folders individually
+- **Review Checklist** (`checklists/review-checklist.md`) — step-by-step checklist covering all phases
+- All 4 subagent prompts now include `## REVIEW DIRECTORY` section pointing to temp clone
+
+### Why (replaces v7.1.0 checkout approach)
+- `gh pr checkout` on the local repo **disturbs your working directory** — uncommitted changes, stashes, branch switches
+- Cloning to `/tmp` means your workspace is **never touched**
+- Unique timestamp in folder name enables **parallel reviews** of multiple PRs
+- User controls cleanup — temp folder persists until explicitly removed
+
+### Changed
+- Phase 1 now reads full file context from `$REVIEW_DIR` instead of GitHub API
+- Subagent prompts explicitly instruct agents to read from `$REVIEW_DIR`, not workspace repo
+- User notification now includes temp folder path and cleanup prompt
+
+---
+
+## v7.1.0 (2026-03-05) - Branch Alignment Before Review (SUPERSEDED by v2.7.0)
+
+**FIX**: Reviews now always run against the correct PR branch, not whatever branch happens to be checked out locally.
+
+### Added
+- **Phase 0: Repository Preparation (Branch Alignment)** — MANDATORY pre-review step
+  - Extracts repo info from PR URL / `github_get_pull_request`
+  - Clones repo if not present locally
+  - Saves current branch and stashes uncommitted changes
+  - Checks out the PR's head branch via `gh pr checkout`
+  - Verifies checkout succeeded before proceeding
+  - Optionally updates consumer repos to their default branch for cross-repo search
+- **Phase 6: Repository Cleanup** — restores original branch and unstashes changes after review
+- **🚫 Read-Only Rule** — explicit absolute prohibition on any GitHub write actions (push, comment, merge, review, etc.)
+- Subagent prompts now explicitly note that all file reads happen against the checked-out PR branch
+
+### Why
+Local repos may be on any branch (feature branch, old release, etc.). Previous versions read files from whatever was checked out, which could produce:
+- False positives (flagging code that doesn't exist in the PR)
+- Missed bugs (not seeing code that IS in the PR)
+- Wrong context for cross-repo consumer search
+
+This version ensures the reviewer always sees the actual PR code.
+
+---
+
+## v7.0.0 (2026-02-24) - Unified Architecture
+
+MAJOR: Merged project-level v6.1 (cross-repo consumer search, better-context structural analysis) with global v2.6 (4 parallel subagents, nano-brain memory, iterative refinement) into a single unified skill.
+
+### Added
+- 5 parallel subagents (was inline review in v6.1, was 4 subagents in v2.6)
+  - Code Quality (explore)
+  - Security and Logic (oracle)
+  - Docs and Best Practices (librarian)
+  - Tests and Integration (quick)
+  - Cross-Repo Consumer Search (explore, conditional)
+- nano-brain integration for persistent memory across review sessions
+- PR Summary generation (GitHub Copilot-style)
+- Iterative refinement with dedup, severity filtering, and gap analysis
+- Configuration file support (.opencode/code-reviewer.json)
+- Smart tracing by change type (LOGIC/STYLE/REFACTOR/NEW)
+
+### Enhanced
+- Subagent prompts now include better-context structural data (centrality, dependents)
+- Subagent prompts now include breaking change signals from Phase 2
+- Report template includes both Structural Analysis and Cross-Repo Consumer Search sections
+- Framework checklists and rules passed to relevant subagents
+
+### Preserved from v6.1
+- better-context structural analysis (Phase 1.5)
+- MANDATORY cross-repo consumer search (now as 5th subagent)
+- Breaking change signal detection (Phase 2)
+- All checklists: consumer-search-matrix, backend-express, frontend-vue-nuxt, database, ci-cd
+- All framework rules: express, nestjs, typeorm, typescript, vue-nuxt
+- Severity reference with cross-repo icon
+
+### Preserved from v2.6
+- Parallel subagent architecture
+- nano-brain integration (query + save)
+- Compact report philosophy
+- Iterative refinement and filtering
+- Config file support
+
+### Architecture
+- Project-level skill (takes priority over global)
+- SKILL.md is concise, references external files for details
+- 13 reference/checklist files for domain-specific knowledge
+
+---
+
+## v6.1.1 (2026-02-12) - Centralized Manifests
+
+**FIX**: Moved better-context manifests to centralized location to avoid polluting individual repos.
+
+### Changed
+- Manifests now stored at `.better-context/{repo}.json` at workspace root
+- No `.better-context/` folders in individual repos
+- No gitignore changes needed in repos
+- Updated scan command to use `--out` for centralized output
+
+---
+
+## v6.1.0 (2026-02-12) - better-context Integration
+
+**ENHANCEMENT**: Integrated better-context for structural analysis using PageRank centrality and dependency graphs.
+
+### Added
+- **better-context Integration** (Phase 1.5)
+  - `uvx better-context scan` - Index codebase and detect cycles
+  - `uvx better-context stats` - PageRank centrality ranking
+  - `uvx better-context focus <file>` - Ego-centric context for changed files
+  - `uvx better-context deps <file>` - Dependencies and dependents
+
+- **Structural Analysis Output**
+  - Changed files impact table with centrality scores
+  - High-centrality file flags (> 0.05 = critical)
+  - Dependency cycle warnings
+  - Suggested reading order for understanding changes
+
+- **Centrality-Based Review Priority**
+  - Files with centrality > 0.08 → CRITICAL (core infrastructure)
+  - Files with centrality 0.05-0.08 → HIGH (shared utilities)
+  - Files with > 10 dependents → WIDE IMPACT flag
+
+- **Configuration Files**
+  - `.ctx.json` - better-context configuration
+  - `.ctxignore` - Patterns to exclude from analysis
+
+### Enhanced
+- Report template now includes Structural Analysis section
+- High-impact files flagged based on PageRank score
+- Dependency cycle detection integrated into review workflow
+
+### Why better-context?
+- **PageRank Centrality**: Mathematically identifies critical files (not guesswork)
+- **Focus Mode**: Shows exactly what depends on a changed file
+- **Cycle Detection**: Found 2 circular dependency cycles in tradeit-backend
+- **Token Optimization**: Efficient context selection for AI review
+
+### Complementary to Our AGENTS.md
+- better-context provides **structural intelligence** (what depends on what)
+- Our AGENTS.md provides **domain intelligence** (business logic, cross-repo relationships)
+- Together: Complete picture for thorough PR reviews
+
+---
+
+## v6.0.0 (2026-02-11) - Cross-Repo Consumer Search
+
+**MAJOR**: Mandatory cross-repo consumer search for ALL breaking changes
+
+### Added
+- **Consumer Search Matrix** (`checklists/consumer-search-matrix.md`)
+  - Comprehensive matrix of what changes require cross-repo search
+  - Search patterns for each change type (API fields, Redis keys, DB columns, etc.)
+  - Critical fields list that should never be removed without migration
+  
+- **Domain-Specific Checklists**
+  - `checklists/backend-express.md` - Express/Node patterns, error handling, timeouts
+  - `checklists/frontend-vue-nuxt.md` - Vue 3/Nuxt 3 patterns, reactivity, state management
+  - `checklists/database.md` - MySQL/Redis patterns, transactions, migrations
+  - `checklists/ci-cd.md` - Docker, CircleCI, deployment safety
+
+- **Breaking Change Signal Detection**
+  - Conditional/ternary removed → CRITICAL (PR #1101 imgURL issue)
+  - Default case logic changed → WARNING (PR #1101 insightService issue)
+  - Middleware removed → Search httpContext consumers
+  - External URL pattern changed → Search all frontend consumers
+
+- **Timeout/Hang Detection**
+  - AI/LLM calls without timeout → CRITICAL
+  - External HTTP calls without timeout → CRITICAL
+  - Database queries in loops without limit → WARNING
+
+### Enhanced
+- SKILL.md now requires Consumer Search Output section in all reviews
+- Backend signal detection includes service logic changes
+- Cross-repo search scope expanded to tradeit, tradeit-admin, tradeit-extension
+
+### Post-mortem
+PR #1101 review revealed two critical issues that would have been caught with proper consumer search:
+1. `imgURL` conditional removed in inventoryService.js → 30+ frontend components affected
+2. `insightService.js` default case changed → AI content generation broken for category slugs
+
+Both issues were NOT in the PR diff but affected by the changes. This version makes cross-repo consumer search MANDATORY.
+
+---
+
+## v5.1.0 (2026-02-11) - CRITICAL FIX
+
+**CRITICAL FIX**: Mandatory consumer search for Pinia store migrations
+
+### Added
+- Phase 1.5 - Breaking Change Signal Detection
+- Automatic detection of Pinia stores from file paths
+- MANDATORY consumer search with exact grep commands
+- Required output format for consumer search results
+- Orchestrator verification that consumer search was performed
+- Re-run mechanism for incomplete reviews
+
+### Enhanced
+- state-mgmt subagent prompt with step-by-step consumer search
+
+### Fixed
+- Subagents now search ENTIRE codebase, not just PR files
+
+### Post-mortem
+PR #3088 review missed `rootState.currency` bug in `store/inventory.js` because:
+1. The file was NOT in the PR (not assigned to subagent)
+2. Consumer search instructions were advisory, not mandatory
+3. No verification that search was actually performed
+
+---
+
+## v5.0.0 (2026-02-11)
+
+### Added
+- Vuex/Pinia migration checklist (from PR #3108 analysis)
+- Cross-repo impact analysis with database ownership check
+- Devil's Advocate verification protocol
+- OWASP 2025-aligned security checklist
+- Historical context check before flagging issues
+- Research synthesis documentation
+
+### Enhanced
+- state-mgmt category with migration patterns
+- security category with OWASP Top 10 (2025)
+- cross-repo category with consumer search patterns
+
+---
+
+## v4.0.0 (2026-02-10)
+
+### Redesigned
+- Token-efficient orchestrator (< 3000 tokens)
+
+### Added
+- Path-based file categorization
+- Subagent file-based output
+- Checklist tracking
+
+### Removed
+- Django, Next.js, React framework rules
+
+---
+
+## v3.0.0
+
+- Initial parallel subagent architecture

package/skills/pr-code-reviewer/RESEARCH.md

@@ -0,0 +1,60 @@
+# PR Code Reviewer - Research & Design Decisions
+
+## Why This Architecture?
+
+| Decision | Research Source | Rationale |
+|----------|-----------------|-----------|
+| Orchestrator < 3000 tokens | AI tool comparison | Most tools bloat context with full file reads |
+| Path-based categorization | Google CODEOWNERS | Proven at scale, no code parsing needed |
+| Parallel subagents | Meta's review speed research | P75 review time correlates with satisfaction |
+| Devil's Advocate verification | Senior reviewer practices | Reduces false positives significantly |
+| Cross-repo awareness | Microservices research | Breaking changes are #1 cause of outages |
+| Historical context check | Google Critique | "Why was this written?" prevents bad flags |
+
+## What We Learned from PR #3108 and PR #3088
+
+The `rootState.currency` bug taught us:
+
+1. **State migrations are invisible**: Pinia stores don't appear in Vuex's rootState
+2. **Reverts compound problems**: Double-revert brought back broken state
+3. **AI misses cross-store dependencies**: Need explicit migration checklist
+4. **Pattern matching isn't enough**: Must trace actual execution paths
+
+### PR #3088 Post-Mortem (v5.1 trigger)
+
+The v5.0 skill had the RIGHT instructions but WRONG enforcement:
+- Instructions said "search for rootState.{storeName}" 
+- But subagent only reviewed PR files, not entire codebase
+- `store/inventory.js` (NOT in PR) still used `rootState.currency`
+- Bug was missed because consumer search was ADVISORY, not MANDATORY
+
+**Root Cause**: Subagents only read assigned files. Consumer search requires searching ENTIRE codebase.
+
+**Fix (v5.1)**: 
+- Phase 1.5: Detect breaking change signals from file paths
+- Mandatory consumer search with EXACT grep commands
+- Required output format for verification
+- Orchestrator verification that search was performed
+
+## Comparison: Our Approach vs Industry
+
+| Aspect | Google | Meta | AI Tools | Our v5.1 |
+|--------|--------|------|----------|----------|
+| Token efficiency | N/A | N/A | Poor | ✅ Excellent |
+| Cross-repo | Glean indexing | Monorepo | Limited | ✅ Manual check |
+| Speed | Hours | Minutes | Seconds | Minutes |
+| False positives | Low | Low | High | Medium (Devil's Advocate) |
+| Context awareness | Deep | Deep | Shallow | Medium (repo rules) |
+| Breaking changes | Manual | Automated | Limited | ✅ Mandatory search |
+
+## Future Enhancements (v6.0 Candidates)
+
+1. **Automated contract testing**: Integrate Pact-style consumer checks
+2. **Review metrics**: Track time-to-review, false positive rate
+3. **Stacked diff support**: Review incremental changes like Meta
+4. **Git blame integration**: Automatic historical context lookup
+5. **Cross-repo dependency graph**: Visualize service dependencies
+
+## Full Research
+
+See `.opencode/research/code-review-research-synthesis.md` for complete analysis.