@nano-step/skill-manager 5.6.1 → 5.6.2

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,61 @@
+# 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: CLI
+
+All nano-brain operations use the CLI via Bash tool:
+
+| Need | CLI Command |
+|------|-------------|
+| Hybrid search (best quality) | `npx nano-brain query "search terms"` |
+| Keyword search (function name, error) | `npx nano-brain query "exact term" -c codebase` |
+| Save review findings | `npx nano-brain write "content" --tags=review` |
+
+## Setup
+
+Run `/nano-brain-init` in the workspace, or `npx nano-brain init --root=/path/to/workspace`.
+
+## Phase 1 Memory Queries
+
+For each significantly changed file/module:
+- **Hybrid search**: `npx nano-brain query "<module-name>"` (best quality, combines BM25 + vector + reranking)
+- **Scoped search**: `npx nano-brain query "<function-name>" -c codebase` for code-specific results
+
+Specific queries:
+- Past review findings: `npx nano-brain query "review <module-name>"`
+- Architectural decisions: `npx nano-brain query "<module-name> architecture design decision"`
+- Known issues: `npx nano-brain 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
+npx nano-brain 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
+npx nano-brain write "## Code Review: PR #<number> - <title>
+Date: <date>
+Files: <changed_files>
+
+### Key Findings
+<critical_issues_summary>
+<warnings_summary>
+
+### Decisions
+<architectural_decisions_noted>
+
+### 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);
+}
+```

package/skills/pr-code-reviewer/references/report-template.md

@@ -0,0 +1,167 @@
+# Report Template
+
+Save to `.opencode/reviews/{type}_{identifier}_{date}.md`.
+Create `.opencode/reviews/` if it does not exist.
+
+## Design Principle
+
+**Short and meaningful.** People don't read long reports. Every section must earn its place.
+
+- Critical + Warning = full detail (file, line, impact, fix)
+- Improvements = one-liner with code suggestion
+- Suggestions = count only (or brief list if < 3)
+- Empty sections = omit entirely
+- TL;DR at the top so the reader can stop after 3 lines if everything is clean
+
+## Template
+
+```markdown
+# Code Review: PR #{number} — {pr_title}
+
+## TL;DR
+
+**{APPROVE | REQUEST CHANGES | COMMENT}** — {one sentence reason}
+
+| Critical | Warnings | Improvements | Suggestions |
+|----------|----------|--------------|-------------|
+| {count}  | {count}  | {count}      | {count}     |
+
+{If Phase 4.5 dropped findings: "🔍 Verification: {N} finding(s) dropped as false positives"}
+{If Phase 4.5 verified all findings: "🔍 All findings verified"}
+{If Phase 4.5 was skipped (no critical/warning): omit this line entirely}
+
+## What This PR Does
+
+{1-3 sentences. Start with action verb. Include business impact if clear.}
+
+**Key Changes:**
+- **{category}**: {brief description}
+- **{category}**: {brief description}
+
+## Ticket Alignment
+
+> Only included when a Linear ticket is linked. Omit entirely if no ticket found.
+
+**Ticket**: [{ticket_id}]({linear_url}) — {ticket_title}
+**Status**: {ticket_status} | **Priority**: {ticket_priority}
+
+### Acceptance Criteria Coverage
+
+| # | Criteria | Status | Notes |
+|---|----------|--------|-------|
+| 1 | {criteria_text} | ✅ Met / ⚠️ Partial / ❌ Missing | {brief note} |
+
+{If all criteria met: "All acceptance criteria addressed."}
+{If gaps found: "**{count} criteria not fully addressed** — see details above."}
+{If criteria are ambiguous: "⚠️ **Ambiguous acceptance criteria** — '{original_text}' can be interpreted as: (a) {interpretation_1}, (b) {interpretation_2}. This PR implements interpretation (a/b). Verify with ticket author."}
+
+## Premise Check (DELETION changes only)
+
+> Only included when the PR deletes existing behavior. Omit for additions/modifications.
+
+| Question | Answer |
+|----------|--------|
+| Why was this code added originally? | {reason} |
+| Is the underlying problem solved? | {yes/no — explanation} |
+| Would fixing the logic be more correct? | {yes/no — explanation} |
+| Cross-repo implications? | {backend config, API contracts, etc.} |
+
+**Verdict**: {REMOVAL CORRECT / SHOULD FIX INSTEAD / NEEDS CLARIFICATION}
+
+## Critical Issues (MUST FIX)
+
+### 1. {Title}
+**`{file}:{line}`** | {Security/Logic/Performance}
+{What's wrong and what could go wrong.}
+**Fix:** {Concrete suggestion or code snippet}
+
+### 2. {Title}
+...
+
+## Warnings (SHOULD FIX)
+
+### 1. {Title}
+**`{file}:{line}`** | {Category}
+{Issue description.}
+**Fix:** {Suggestion}
+
+## Code Improvements
+
+> Opportunities to make the code better — cleaner, faster, more idiomatic.
+
+- **`{file}:{line}`** — {description}. Consider: `{code_suggestion}`
+- **`{file}:{line}`** — {description}
+
+## Suggestions ({count})
+
+{If ≤ 3, list as one-liners. If > 3, just show the count.}
+
+- `{file}:{line}` — {brief}
+
+## Files Changed
+
+| File | Type | Summary |
+|------|------|---------|
+| `{path}` | {LOGIC/DELETION/STYLE/REFACTOR/NEW} | {one-liner} |
+```
+
+**Sections to OMIT unless they contain actionable findings:**
+- Traced Dependencies
+- nano-brain Memory Context
+- Test Coverage Analysis
+- Praise (include only if genuinely noteworthy — one line max)
+- Change Classification table
+
+## PR Summary Generation Guidelines
+
+### What This PR Does (1-3 sentences)
+- Start with action verb: "Adds", "Fixes", "Refactors", "Updates"
+- Mention the feature/bug/improvement
+- Include business impact if clear
+
+### Key Changes categories
+- `Feature`: New functionality
+- `Bugfix`: Fixes broken behavior
+- `Refactor`: Code restructuring without behavior change
+- `Performance`: Speed/memory improvements
+- `Security`: Security fixes or hardening
+- `Docs`: Documentation updates
+- `Tests`: Test additions/modifications
+- `Config`: Configuration changes
+- `Dependencies`: Package updates
+
+### File-by-File Summary
+- **What changed**: Factual description of the code change
+- **Why it matters**: Impact on users, developers, or system
+- **Key modifications**: Specific functions/classes/lines changed
+
+## PR Summary Pseudocode
+
+```javascript
+// Generate PR Summary (GitHub Copilot style)
+const prSummary = `
+## PR Overview
+
+### What This PR Does
+${generateHighLevelSummary(prMetadata, changedFiles)}
+
+### Key Changes
+${categorizeChanges(changedFiles).map(c => `- **${c.category}**: ${c.description}`).join('\n')}
+
+## File-by-File Summary
+
+| File | Change Type | Summary |
+|------|-------------|---------|
+${changedFiles.map(f => `| \`${f.path}\` | ${f.changeType} | ${f.oneLinerSummary} |`).join('\n')}
+
+### Detailed File Changes
+
+${changedFiles.map(f => `
+#### \`${f.path}\` (+${f.additions}/-${f.deletions})
+**What changed**: ${f.whatChanged}
+**Why it matters**: ${f.whyItMatters}
+**Key modifications**:
+${f.keyModifications.map(m => `- ${m}`).join('\n')}
+`).join('\n')}
+`;
+```

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

@@ -0,0 +1,31 @@
+# Security Patterns
+
+## OWASP Top 10 Detection
+
+### 1. Injection
+```javascript
+// CRITICAL: SQL Injection
+const query = `SELECT * FROM users WHERE id = ${userId}`;
+
+// SECURE: Parameterized query
+const query = 'SELECT * FROM users WHERE id = ?';
+await db.query(query, [userId]);
+```
+
+### 2. Broken Authentication
+```javascript
+// CRITICAL: Weak hashing
+crypto.createHash('md5').update(password);
+
+// SECURE: Strong hashing
+bcrypt.hash(password, 12);
+```
+
+### 3. XSS
+```javascript
+// CRITICAL: Direct HTML insertion
+element.innerHTML = userInput;
+
+// SECURE: Text content
+element.textContent = userInput;
+```