@nano-step/skill-manager 5.6.1 → 5.7.0

package/skills/pr-code-reviewer/references/confidence-scoring.md

@@ -0,0 +1,98 @@
+# Confidence Scoring (Phase 4.6)
+
+Re-review the final findings to score how confident we are in the review's **results** — are the findings correct and complete?
+
+**Always run this phase**, even if no critical/warning findings remain. The confidence score reflects the entire review quality, not just individual findings.
+
+## Per-Finding Confidence
+
+For each surviving finding (post Phase 4.5), assign a confidence level:
+
+| Level | Criteria |
+|-------|----------|
+| 🟢 High | Verified with concrete file:line evidence AND 2+ agents independently flagged it |
+| 🟡 Medium | Verified but single agent, OR 2+ agents agreed but evidence is indirect |
+| 🔴 Low | Unverifiable, pattern-based reasoning, no agent consensus |
+
+## Overall Confidence Score (0–100)
+
+Compute from three measurable rates:
+
+```
+# Inputs (from Phase 4 + 4.5)
+raw_findings        = total findings from all 4 subagents (before dedup)
+false_positives     = findings dropped in Phase 4.5 as verified:false
+verified            = findings confirmed real in Phase 4.5 (verified:true)
+unverifiable        = findings marked unverifiable in Phase 4.5
+final_findings      = all findings in the final report (critical + warning + improvement + suggestion)
+consensus_findings  = final findings that were flagged by 2+ agents independently
+evidence_findings   = final findings that cite concrete file:line proof
+
+# Rates
+accuracy_rate   = verified / max(verified + false_positives, 1)        # How often we're right (0.0–1.0)
+consensus_rate  = consensus_findings / max(final_findings, 1)          # Agreement level (0.0–1.0)
+evidence_rate   = evidence_findings / max(final_findings, 1)           # Proof quality (0.0–1.0)
+
+# Weighted score
+overall = round((accuracy_rate * 40) + (consensus_rate * 30) + (evidence_rate * 30))
+```
+
+## Special Cases
+
+- If Phase 4.5 was skipped (no critical/warning to verify): `accuracy_rate = 1.0` (no false positives possible)
+- If `final_findings == 0` (clean review, no issues found): `overall = 100` (nothing to be wrong about)
+- If all subagents returned empty findings: `overall = 100` with note "No issues found by any agent"
+
+## Confidence Thresholds & Gate Behavior
+
+| Score | Label | Gate Action |
+|-------|-------|-------------|
+| 80–100 | 🟢 High | Proceed normally — findings are reliable |
+| 60–79 | 🟡 Medium | Add ⚠️ in report: "Some findings may be inaccurate — verify manually" |
+| < 60 | 🔴 Low | Add 🔴 in report: "Low confidence review — significant uncertainty in findings. Manual review recommended." |
+
+## Display Format (included in Phase 5 TL;DR)
+
+```
+📊 Result Confidence: 🟢 92/100
+   Accuracy: 85% (3 false positives caught and removed)
+   Consensus: 100% (all findings had 2+ agent agreement)
+   Evidence: 100% (all findings cite file:line proof)
+```
+
+For low confidence:
+```
+📊 Result Confidence: 🔴 45/100
+   Accuracy: 50% (4 of 8 findings were false positives)
+   Consensus: 30% (most findings from single agent only)
+   Evidence: 60% (some findings lack concrete proof)
+   ⚠️ Low confidence — manual review recommended for: [list specific uncertain findings]
+```
+
+## Checkpoint Schema
+
+Save results to `.checkpoints/phase-4.6-confidence.json`:
+
+```json
+{
+  "raw_findings": 16,
+  "false_positives": 3,
+  "verified": 5,
+  "unverifiable": 0,
+  "final_findings": 6,
+  "consensus_findings": 4,
+  "evidence_findings": 6,
+  "accuracy_rate": 0.625,
+  "consensus_rate": 0.667,
+  "evidence_rate": 1.0,
+  "overall_score": 75,
+  "label": "medium",
+  "per_finding_confidence": [
+    { "file": "src/service.js", "line": 42, "severity": "warning", "confidence": "high" },
+    { "file": "src/utils.js", "line": 10, "severity": "improvement", "confidence": "medium" }
+  ],
+  "gate_action": "Add warning to report"
+}
+```
+
+Update `manifest.json` (`completed_phase: 4.6`, `next_phase: 5`).

package/skills/pr-code-reviewer/references/framework-rules/express.md

@@ -0,0 +1,39 @@
+# Express Code Review Rules
+
+## Critical Rules
+- Unhandled async errors in route handlers → use express-async-handler or try-catch
+- SQL injection in raw queries → use parameterized queries
+- Missing authentication middleware on protected routes
+- Exposing sensitive data in error responses
+
+## Warning Rules
+- Missing input validation → use express-validator or joi
+- Exposing stack traces in production → check NODE_ENV
+- Missing rate limiting on public endpoints
+- No request body size limit → use express.json({ limit: '10kb' })
+
+## Suggestions
+- Use helmet for security headers
+- Use compression middleware
+- Centralize error handling middleware
+- Use router.param() for parameter validation
+
+## Detection Patterns
+
+```javascript
+// CRITICAL: Unhandled async
+app.get('/api', async (req, res) => {
+  const data = await fetchData()  // if throws, crashes server
+})
+
+// SECURE: Wrapped async
+app.get('/api', asyncHandler(async (req, res) => {
+  const data = await fetchData()
+}))
+
+// CRITICAL: SQL injection
+db.query(`SELECT * FROM users WHERE id = ${req.params.id}`)
+
+// SECURE: Parameterized
+db.query('SELECT * FROM users WHERE id = ?', [req.params.id])
+```

package/skills/pr-code-reviewer/references/framework-rules/nestjs.md

@@ -0,0 +1,41 @@
+# NestJS Code Review Rules
+
+## Critical Rules
+- Missing `@Injectable()` decorator on service class
+- Circular dependency without `forwardRef()`
+- Missing guards on sensitive endpoints → use `@UseGuards()`
+- Raw SQL without parameterization in repositories
+
+## Warning Rules
+- Missing DTO validation → use `class-validator` decorators
+- Missing `@ApiTags()` / `@ApiOperation()` for Swagger docs
+- Injecting repository directly in controller → use service layer
+- Missing `@Transactional()` on multi-step database operations
+
+## Suggestions
+- Use `ConfigService` instead of `process.env` directly
+- Use custom exceptions extending `HttpException`
+- Use interceptors for response transformation
+- Use pipes for input transformation
+
+## Detection Patterns
+
+```typescript
+// CRITICAL: Missing Injectable
+class UserService {  // should be @Injectable()
+  constructor(private repo: UserRepository) {}
+}
+
+// WARNING: Missing validation
+@Post()
+create(@Body() dto: CreateUserDto) {}  // dto needs class-validator decorators
+
+// CRITICAL: Circular dependency
+@Injectable()
+export class ServiceA {
+  constructor(private serviceB: ServiceB) {}  // if B also injects A
+}
+
+// SECURE: Forward ref
+constructor(@Inject(forwardRef(() => ServiceB)) private serviceB: ServiceB) {}
+```

package/skills/pr-code-reviewer/references/framework-rules/nextjs.md

@@ -0,0 +1,58 @@
+# Next.js Code Review Rules
+
+## Critical Rules
+
+### Data Fetching
+- `getServerSideProps` fetching data that doesn't change per-request → use `getStaticProps` + ISR
+- Missing `revalidate` in `getStaticProps` for dynamic content → stale data
+- Calling internal API routes from `getServerSideProps` → call the handler function directly
+- `fetch` in Server Components without `{ cache: 'no-store' }` when fresh data required → unexpected caching
+
+### Routing & Navigation
+- `useRouter().push()` for external URLs → use `window.location.href`
+- Missing `loading.tsx` for slow data fetches → no loading state shown
+- Dynamic route params accessed before null check → crash on direct URL access
+
+### App Router (Next.js 13+)
+- `'use client'` on a component that has no client-side interactivity → unnecessary client bundle
+- `useState` / `useEffect` in Server Component → runtime error
+- Passing non-serializable props from Server → Client component → crash
+
+### Server Actions
+- No input validation in Server Actions → security hole
+- Missing `revalidatePath` / `revalidateTag` after mutations → stale cache
+
+## Warning Rules
+
+### Performance
+- Large `node_modules` imports in `'use client'` components → bundle bloat (use dynamic imports)
+- Missing `next/image` for `<img>` tags → no lazy loading / optimization
+- Missing `next/font` for Google Fonts → layout shift (CLS)
+- `useEffect` for data fetching → waterfall; prefer Server Components
+
+### Auth & Security
+- Middleware not protecting `/api` routes that require auth
+- `cookies()` / `headers()` in cached Server Components → dynamic rendering forced silently
+- Sensitive env vars without `NEXT_PUBLIC_` prefix check — public prefix exposes to client
+
+## Suggestions
+- Use `next/dynamic` for heavy components with `ssr: false` when not needed server-side
+- Use `unstable_cache` for expensive DB queries in Server Components
+- Wrap `<Suspense>` around async Server Components for streaming
+
+## Detection Patterns
+
+```tsx
+// CRITICAL: useState in Server Component
+// app/page.tsx (no 'use client')
+const [count, setCount] = useState(0)  // Error: hooks in Server Component
+
+// CRITICAL: internal API fetch in getServerSideProps
+export async function getServerSideProps() {
+  const res = await fetch('http://localhost:3000/api/data')  // Wrong
+  // Should: import and call the handler directly
+}
+
+// WARNING: img instead of next/image
+<img src={user.avatar} />  // Use <Image> from 'next/image'
+```

package/skills/pr-code-reviewer/references/framework-rules/prisma.md

@@ -0,0 +1,54 @@
+# Prisma Code Review Rules
+
+## Critical Rules
+
+### Data Safety
+- `prisma.user.deleteMany({})` with empty where → deletes all rows
+- Raw queries with string interpolation → SQL injection (`prisma.$queryRaw` must use tagged template literal `Prisma.sql`)
+- Missing `select` / `omit` on queries that return sensitive fields (e.g., `password`, `token`) → data leak
+- `prisma.$transaction` with non-atomic operations that should be atomic → partial write on failure
+
+### Migrations
+- Renaming a column by adding new + deleting old in one migration → data loss if deployed without backfill
+- `@default(now())` added to existing non-nullable column → migration fails on non-empty table
+- Missing `migrate deploy` step noted in release process for schema changes
+
+## Warning Rules
+
+### Performance
+- `findMany` without `take` (limit) → unbounded query, potential OOM
+- N+1: loop calling `findUnique` per item → use `findMany` with `in` filter or `include`
+- Missing `index` on columns used in `where`, `orderBy`, or `join` → full table scan
+- `include` nesting 3+ levels deep → over-fetching
+
+### Patterns
+- Using `upsert` when only create or only update is semantically correct → confusing intent
+- `update` without checking record exists → silent no-op if not found (use `update` which throws, not `upsert`)
+- Accessing `prisma` directly in route handlers → should go through a repository/service layer
+
+## Suggestions
+- Use `select` to fetch only needed columns (reduces payload size)
+- Use `prisma.$transaction([...])` for related writes that must succeed together
+- Add `@@index` directives for common query patterns in schema
+
+## Detection Patterns
+
+```typescript
+// CRITICAL: SQL injection via raw query
+const user = await prisma.$queryRaw(`SELECT * FROM users WHERE id = ${userId}`)
+// SAFE:
+const user = await prisma.$queryRaw(Prisma.sql`SELECT * FROM users WHERE id = ${userId}`)
+
+// CRITICAL: missing field exclusion
+const user = await prisma.user.findUnique({ where: { id } })
+// user.password is returned — should use select or omit
+
+// WARNING: N+1
+for (const order of orders) {
+  const user = await prisma.user.findUnique({ where: { id: order.userId } })
+}
+// FIX: findMany with where: { id: { in: orders.map(o => o.userId) } }
+
+// WARNING: unbounded query
+const all = await prisma.product.findMany()  // missing take:
+```

package/skills/pr-code-reviewer/references/framework-rules/react.md

@@ -0,0 +1,61 @@
+# React Code Review Rules
+
+## Critical Rules
+
+### Hooks
+- Hooks called conditionally → violates Rules of Hooks, runtime error
+- `useEffect` with missing dependency → stale closure / infinite loop
+- `useEffect` with object/array literal in deps → new reference every render, infinite loop
+- Mutating state directly (`state.items.push(x)`) → no re-render triggered
+
+### State & Props
+- Derived state stored in `useState` when it can be computed inline → sync issues
+- Prop drilling 3+ levels deep without context or state manager → maintenance burden (flag as warning)
+- Reading stale ref value in async callback after unmount → memory leak / crash
+
+### Event Handling
+- Missing cleanup in `useEffect` (subscriptions, timers, event listeners) → memory leak
+- `onClick` on non-interactive element without keyboard equivalent → accessibility gap
+
+## Warning Rules
+
+### Performance
+- Anonymous functions / object literals as props to memoized components → memo is bypassed
+- Missing `useCallback` on functions passed to child components with `React.memo`
+- Large lists rendered without virtualization (`react-window` / `react-virtual`) → slow paint
+- `useContext` on frequently-changing context → unnecessary re-renders
+
+### Patterns
+- `index` as `key` in lists that can reorder/filter → wrong element reconciled
+- Multiple `useState` for related state → use `useReducer`
+- `useEffect` for synchronizing with external system vs for side effects — distinguish them
+
+## Suggestions
+- Use `React.lazy` + `<Suspense>` for code-splitting heavy routes
+- Consider `useMemo` for expensive calculations with stable inputs
+- Use `<ErrorBoundary>` around async components
+
+## Detection Patterns
+
+```tsx
+// CRITICAL: conditional hook
+if (user) {
+  const [name, setName] = useState(user.name)  // Error: conditional hook
+}
+
+// CRITICAL: missing cleanup
+useEffect(() => {
+  const sub = eventBus.subscribe(handler)
+  // Missing: return () => sub.unsubscribe()
+}, [])
+
+// CRITICAL: stale closure
+useEffect(() => {
+  setInterval(() => {
+    console.log(count)  // stale if count not in deps
+  }, 1000)
+}, [])  // Missing: count in deps
+
+// WARNING: object literal breaks memo
+<MyMemo style={{ color: 'red' }} />  // new object every render
+```

package/skills/pr-code-reviewer/references/framework-rules/typeorm.md

@@ -0,0 +1,52 @@
+# TypeORM Code Review Rules
+
+## Critical Rules
+- Raw SQL with string interpolation → SQL injection risk
+- Missing `@Transaction()` on multi-entity operations
+- Forgetting to `await` repository methods → silent failures
+- Using `save()` in loops → N+1 writes, use `save([entities])`
+
+## Warning Rules
+- N+1 query pattern → use `relations` option or `leftJoinAndSelect`
+- Missing indexes on frequently queried columns
+- Using `find()` without `take` limit on large tables
+- Eager loading too many relations → performance hit
+
+## Suggestions
+- Use QueryBuilder for complex queries
+- Use `@Index()` decorator for query optimization
+- Use `createQueryBuilder().insert()` for bulk inserts
+- Consider `@DeleteDateColumn()` for soft deletes
+
+## Detection Patterns
+
+```typescript
+// CRITICAL: SQL injection
+repository.query(`SELECT * FROM users WHERE name = '${name}'`)
+
+// SECURE: Parameterized
+repository.query('SELECT * FROM users WHERE name = ?', [name])
+
+// CRITICAL: N+1 in loop
+for (const user of users) {
+  await userRepo.save(user)  // N writes
+}
+
+// SECURE: Batch save
+await userRepo.save(users)  // 1 write
+
+// WARNING: N+1 query
+const users = await userRepo.find()
+for (const user of users) {
+  const posts = await postRepo.find({ where: { userId: user.id } })
+}
+
+// SECURE: Eager load
+const users = await userRepo.find({ relations: ['posts'] })
+
+// WARNING: Missing limit
+await userRepo.find({ where: { status: 'active' } })  // could return millions
+
+// SECURE: With limit
+await userRepo.find({ where: { status: 'active' }, take: 100 })
+```

package/skills/pr-code-reviewer/references/framework-rules/typescript.md

@@ -0,0 +1,50 @@
+# TypeScript Code Review Rules
+
+## Critical Rules
+- Using `any` type to bypass type checking
+- Using `@ts-ignore` or `@ts-expect-error` without justification
+- Type assertion (`as Type`) on untrusted external data
+- Missing null checks before accessing optional properties
+
+## Warning Rules
+- Non-null assertion (`!`) without prior validation
+- Using `as unknown as Type` double assertion
+- Implicit `any` from missing return types
+- Using `Object` or `{}` as type → too permissive
+
+## Suggestions
+- Use `unknown` instead of `any` for external data, then narrow
+- Use discriminated unions for state machines
+- Use `satisfies` operator for type checking without widening
+- Use `readonly` for immutable data structures
+
+## Detection Patterns
+
+```typescript
+// CRITICAL: any type
+const data: any = await fetchData()
+data.whatever.you.want  // no type safety
+
+// SECURE: unknown + narrowing
+const data: unknown = await fetchData()
+if (isUserData(data)) {
+  data.name  // type-safe
+}
+
+// CRITICAL: Unsafe assertion
+const user = JSON.parse(input) as User  // input could be anything
+
+// SECURE: Runtime validation
+const user = userSchema.parse(JSON.parse(input))  // zod/yup validation
+
+// WARNING: Non-null assertion without check
+function process(user?: User) {
+  return user!.name  // crashes if undefined
+}
+
+// SECURE: With guard
+function process(user?: User) {
+  if (!user) throw new Error('User required')
+  return user.name
+}
+```

package/skills/pr-code-reviewer/references/framework-rules/vue-nuxt.md

@@ -0,0 +1,53 @@
+# Vue 3 / Nuxt 3 Code Review Rules
+
+## Critical Rules
+
+### State Management (Vuex ↔ Pinia)
+- `rootState.{module}` where module is Pinia store → Vuex cannot access Pinia state
+- `useStore()` in Pinia-only context → wrong store type
+- Store module exists but not registered in `store/index.js`
+- Pinia store file missing `export` or `defineStore`
+
+### Auto-Import Gotchas (Nuxt)
+- Using function from `utils/` without import → only `composables/` auto-imported
+- Using `defineStore` without import when `@pinia/nuxt` not in modules
+
+### Component Issues
+- Mutating props directly
+- `v-if` and `v-for` on same element
+
+## Warning Rules
+
+### State Management
+- Mixed `useStore()` and `use*Store()` in same composable
+- Vuex action accessing Pinia store via workaround
+- `rootState.{x}` or `rootGetters['{x}/...']` → verify module exists
+
+### Reactivity
+- Using `reactive()` for primitives → use `ref()`
+- Destructuring reactive object without `toRefs()` or `storeToRefs()`
+- Missing `.value` on ref in script (not template)
+
+### Composables
+- Composable not returning reactive refs
+- Using `this` in composable (not available in setup)
+
+## Suggestions
+- Use `storeToRefs()` when destructuring Pinia store
+- Use `computed` for derived state
+- Prefer Pinia for new stores (migration in progress)
+- Use `<script setup>` syntax for components
+
+## Detection Patterns
+
+```javascript
+// CRITICAL: Vuex accessing Pinia (will be undefined)
+rootState.currency.selectedRate  // if currency is Pinia store
+
+// WARNING: Check if module exists
+rootState.{moduleName}  // verify in store/index.js modules: { {moduleName} }
+
+// CRITICAL: Missing import in utils (not auto-imported)
+// In component using function from utils/helpers.js without import
+stripImageSizeFromUrl(url)  // will be undefined if not imported
+```

package/skills/pr-code-reviewer/references/nano-brain-integration.md

@@ -0,0 +1,46 @@
+# nano-brain Integration
+
+nano-brain provides persistent memory across sessions. The reviewer uses it for historical context about changed files:
+- Past review findings and architectural decisions
+- Known issues and tech debt in affected modules
+- Prior discussions about the same code areas
+
+## Access Method: HTTP API
+
+All nano-brain operations use HTTP API (nano-brain runs as Docker service on port 3100):
+
+| Need | Command |
+|------|---------|
+| Hybrid search (best quality) | `curl -s localhost:3100/api/query -d '{"query":"search terms"}'` |
+| Keyword search (function name, error) | `curl -s localhost:3100/api/search -d '{"query":"exact term"}'` |
+| Save review findings | `curl -s localhost:3100/api/write -d '{"content":"...","tags":"review"}'` |
+
+## Phase 1 Memory Queries
+
+For each significantly changed file/module:
+- **Hybrid search**: `curl -s localhost:3100/api/query -d '{"query":"<module-name>"}'` (best quality, combines BM25 + vector + reranking)
+- **Scoped search**: `curl -s localhost:3100/api/query -d '{"query":"<function-name>","collection":"codebase"}'` for code-specific results
+
+Specific queries:
+- Past review findings: `curl -s localhost:3100/api/query -d '{"query":"review <module-name>"}'`
+- Architectural decisions: `curl -s localhost:3100/api/query -d '{"query":"<module-name> architecture design decision"}'`
+- Known issues: `curl -s localhost:3100/api/query -d '{"query":"<function-name> bug issue regression"}'`
+
+Collect relevant memory hits as `projectMemory` context for subagents.
+
+## Phase 2 Memory Queries (LOGIC changes)
+
+Query nano-brain for known issues:
+```bash
+curl -s localhost:3100/api/query -d '{"query":"<function-name> bug issue edge case regression"}'
+```
+
+## Phase 5.5: Save Review to nano-brain
+
+After generating the report, save key findings for future sessions:
+
+```bash
+curl -s localhost:3100/api/write -d '{"content":"## Code Review: PR #<number> - <title>\nDate: <date>\nFiles: <changed_files>\n\n### Key Findings\n<critical_issues_summary>\n<warnings_summary>\n\n### Decisions\n<architectural_decisions_noted>\n\n### Recommendation: <APPROVE|REQUEST_CHANGES|COMMENT>","tags":"review,pr-<number>"}'
+```
+
+This ensures future reviews can reference past findings on the same codebase areas.

package/skills/pr-code-reviewer/references/performance-patterns.md

@@ -0,0 +1,26 @@
+# Performance Patterns
+
+## N+1 Queries
+```javascript
+// CRITICAL: N+1 pattern
+const users = await db.query('SELECT * FROM users');
+for (const user of users) {
+  const posts = await db.query('SELECT * FROM posts WHERE user_id = ?', [user.id]);
+}
+
+// SECURE: Eager loading
+const users = await db.query(`
+  SELECT u.*, p.* FROM users u
+  LEFT JOIN posts p ON u.id = p.user_id
+`);
+```
+
+## React Re-renders
+```jsx
+// WARNING: Inline function
+<button onClick={() => handleClick(id)}>
+
+// BETTER: useCallback
+const handleClick = useCallback(() => { ... }, [id]);
+<button onClick={handleClick}>
+```

package/skills/pr-code-reviewer/references/quality-patterns.md

@@ -0,0 +1,25 @@
+# Quality Patterns
+
+## Type Safety
+```typescript
+// WARNING: any type
+const data: any = getData();
+
+// BETTER: Proper typing
+interface UserData { id: string; name: string; }
+const data: UserData = getData();
+```
+
+## Error Handling
+```javascript
+// CRITICAL: Silent catch
+try { await doSomething(); } catch (e) { }
+
+// BETTER: Proper handling
+try {
+  await doSomething();
+} catch (error) {
+  logger.error('Operation failed', { error });
+  throw new CustomError('Operation failed', error);
+}
+```