sequant 1.6.0 → 1.7.0

package/dist/src/commands/doctor.js

@@ -19,7 +19,7 @@ export async function doctorCommand() {
                 message: `Outdated: ${versionResult.currentVersion} → ${versionResult.latestVersion} available`,
             });
             // Show remediation steps
-            console.log(chalk.yellow(`  ⚠️  ${getVersionWarning(versionResult.currentVersion, versionResult.latestVersion)}`));
+            console.log(chalk.yellow(`  ⚠️  ${getVersionWarning(versionResult.currentVersion, versionResult.latestVersion, versionResult.isLocalInstall)}`));
             console.log("");
         }
         else {

package/dist/src/commands/run.js

@@ -742,7 +742,7 @@ export async function runCommand(issues, options) {
         try {
             const versionResult = await checkVersionCached();
             if (versionResult.isOutdated && versionResult.latestVersion) {
-                console.log(chalk.yellow(`  ⚠️  ${getVersionWarning(versionResult.currentVersion, versionResult.latestVersion)}`));
+                console.log(chalk.yellow(`  ⚠️  ${getVersionWarning(versionResult.currentVersion, versionResult.latestVersion, versionResult.isLocalInstall)}`));
                 console.log("");
             }
         }

package/dist/src/lib/version-check.d.ts

@@ -12,6 +12,7 @@ export interface VersionCheckResult {
     currentVersion: string;
     latestVersion: string | null;
     isOutdated: boolean;
+    isLocalInstall?: boolean;
     error?: string;
 }
 /**
@@ -26,6 +27,17 @@ export declare function getCachePath(): string;
  * Get the current version from package.json
  */
 export declare function getCurrentVersion(): string;
+/**
+ * Check if running from a local node_modules install (vs npx cache)
+ *
+ * Local installs are in: <project>/node_modules/sequant/
+ * npx installs are in: ~/.npm/_npx/<hash>/node_modules/sequant/
+ *
+ * This matters because:
+ * - Local installs should be updated with: npm update sequant
+ * - npx installs should be updated with: npx sequant@latest
+ */
+export declare function isLocalNodeModulesInstall(): boolean;
 /**
  * Read the version cache
  */
@@ -53,8 +65,11 @@ export declare function compareVersions(a: string, b: string): number;
 export declare function isOutdated(currentVersion: string, latestVersion: string): boolean;
 /**
  * Get the version warning message
+ *
+ * For local node_modules installs, recommends `npm update sequant`
+ * For npx usage, recommends `npx sequant@latest`
  */
-export declare function getVersionWarning(currentVersion: string, latestVersion: string): string;
+export declare function getVersionWarning(currentVersion: string, latestVersion: string, isLocal?: boolean): string;
 /**
  * Check version freshness (thorough - for doctor command)
  * Always fetches from npm registry

package/dist/src/lib/version-check.js

@@ -54,6 +54,25 @@ export function getCurrentVersion() {
         return "0.0.0";
     }
 }
+/**
+ * Check if running from a local node_modules install (vs npx cache)
+ *
+ * Local installs are in: <project>/node_modules/sequant/
+ * npx installs are in: ~/.npm/_npx/<hash>/node_modules/sequant/
+ *
+ * This matters because:
+ * - Local installs should be updated with: npm update sequant
+ * - npx installs should be updated with: npx sequant@latest
+ */
+export function isLocalNodeModulesInstall() {
+    // Check if our path contains node_modules/sequant but NOT in .npm/_npx
+    const normalizedPath = __dirname.replace(/\\/g, "/");
+    // Running from local node_modules (not npx cache)
+    const inNodeModules = normalizedPath.includes("/node_modules/sequant");
+    const inNpxCache = normalizedPath.includes("/.npm/_npx/") ||
+        normalizedPath.includes("\\.npm\\_npx\\");
+    return inNodeModules && !inNpxCache;
+}
 /**
  * Read the version cache
  */
@@ -158,10 +177,19 @@ export function isOutdated(currentVersion, latestVersion) {
 }
 /**
  * Get the version warning message
+ *
+ * For local node_modules installs, recommends `npm update sequant`
+ * For npx usage, recommends `npx sequant@latest`
  */
-export function getVersionWarning(currentVersion, latestVersion) {
+export function getVersionWarning(currentVersion, latestVersion, isLocal) {
+    const isLocalInstall = isLocal ?? isLocalNodeModulesInstall();
+    if (isLocalInstall) {
+        return `sequant ${latestVersion} is available (you have ${currentVersion})
+   Run: npm update sequant
+   Note: You have sequant as a local dependency. npx uses your node_modules version.`;
+    }
     return `sequant ${latestVersion} is available (you have ${currentVersion})
-   Run: npx sequant@latest or npm update sequant`;
+   Run: npx sequant@latest`;
 }
 /**
  * Check version freshness (thorough - for doctor command)
@@ -169,12 +197,14 @@ export function getVersionWarning(currentVersion, latestVersion) {
  */
 export async function checkVersionThorough() {
     const currentVersion = getCurrentVersion();
+    const isLocal = isLocalNodeModulesInstall();
     const latestVersion = await fetchLatestVersion();
     if (!latestVersion) {
         return {
             currentVersion,
             latestVersion: null,
             isOutdated: false,
+            isLocalInstall: isLocal,
             error: "Could not fetch latest version",
         };
     }
@@ -184,6 +214,7 @@ export async function checkVersionThorough() {
         currentVersion,
         latestVersion,
         isOutdated: isOutdated(currentVersion, latestVersion),
+        isLocalInstall: isLocal,
     };
 }
 /**
@@ -192,6 +223,7 @@ export async function checkVersionThorough() {
  */
 export async function checkVersionCached() {
     const currentVersion = getCurrentVersion();
+    const isLocal = isLocalNodeModulesInstall();
     // Check cache first
     const cache = readCache();
     if (cache && isCacheFresh(cache)) {
@@ -199,6 +231,7 @@ export async function checkVersionCached() {
             currentVersion,
             latestVersion: cache.latestVersion,
             isOutdated: isOutdated(currentVersion, cache.latestVersion),
+            isLocalInstall: isLocal,
         };
     }
     // Fetch new version (with timeout)
@@ -210,12 +243,14 @@ export async function checkVersionCached() {
                 currentVersion,
                 latestVersion: cache.latestVersion,
                 isOutdated: isOutdated(currentVersion, cache.latestVersion),
+                isLocalInstall: isLocal,
             };
         }
         return {
             currentVersion,
             latestVersion: null,
             isOutdated: false,
+            isLocalInstall: isLocal,
         };
     }
     // Update cache
@@ -224,5 +259,6 @@ export async function checkVersionCached() {
         currentVersion,
         latestVersion,
         isOutdated: isOutdated(currentVersion, latestVersion),
+        isLocalInstall: isLocal,
     };
 }

package/dist/src/lib/workflow/run-log-schema.js

@@ -15,6 +15,7 @@
  * console.log(log.summary.passed, log.summary.failed);
  * ```
  */
+import { randomUUID } from "node:crypto";
 import { z } from "zod";
 /**
  * Available workflow phases
@@ -159,7 +160,7 @@ export function generateLogFilename(runId, startTime) {
  * @returns Initial RunLog structure
  */
 export function createEmptyRunLog(config) {
-    const runId = crypto.randomUUID();
+    const runId = randomUUID();
     const startTime = new Date().toISOString();
     return {
         version: 1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sequant",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Quantize your development workflow - Sequential AI phases with quality gates",
   "type": "module",
   "bin": {
@@ -54,7 +54,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.1",
+    "@anthropic-ai/claude-agent-sdk": "^0.2.11",
     "chalk": "^5.3.0",
     "commander": "^12.1.0",
     "diff": "^7.0.0",

package/templates/skills/improve/SKILL.md

@@ -0,0 +1,655 @@
+---
+name: improve
+description: "Codebase analysis, improvement discovery, issue creation, and execution pipeline"
+license: MIT
+metadata:
+  author: sequant
+  version: "1.0"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash(gh *)
+  - Bash(git *)
+  - Bash(npm run *)
+  - Bash(npx *)
+  - AskUserQuestion
+---
+
+# Improve Command
+
+You are the "Improvement Agent" for the current repository.
+
+## Purpose
+
+When invoked as `/improve [area]`, your job is to:
+
+1. **Analyze** the codebase (or specified area) for potential improvements
+2. **Present** findings categorized by type and effort level
+3. **Create** GitHub issues for user-selected improvements
+4. **Offer** `sequant run` command for immediate execution
+
+## Invocation
+
+```bash
+/improve                    # Analyze entire codebase
+/improve src/utils          # Focus on specific directory
+/improve src/lib/api.ts     # Focus on specific file
+/improve performance        # Focus on performance improvements
+/improve tests              # Focus on test coverage gaps
+/improve docs               # Focus on documentation gaps
+/improve security           # Focus on security concerns
+```
+
+## Workflow Overview
+
+```
+/improve [area]
+├────────────────────────────────────────────────────────────┤
+│                                                            │
+│  ┌──────────┐                                              │
+│  │ ANALYZE  │ Scan codebase for improvement opportunities  │
+│  └────┬─────┘                                              │
+│       │                                                    │
+│       ▼                                                    │
+│  ┌──────────┐                                              │
+│  │ PRESENT  │ Show findings grouped by type and effort     │
+│  └────┬─────┘                                              │
+│       │                                                    │
+│       ▼                                                    │
+│  ┌──────────┐                                              │
+│  │ SELECT   │ User selects which improvements to pursue    │
+│  └────┬─────┘                                              │
+│       │                                                    │
+│       ▼                                                    │
+│  ┌──────────┐                                              │
+│  │ CREATE   │ Create GitHub issues for selected items      │
+│  └────┬─────┘                                              │
+│       │                                                    │
+│       ▼                                                    │
+│  ┌──────────┐                                              │
+│  │ EXECUTE  │ Offer sequant run command                    │
+│  └──────────┘                                              │
+└────────────────────────────────────────────────────────────┘
+```
+
+## Phase 1: Analysis
+
+### 1.1 Scope Detection
+
+Determine analysis scope based on invocation:
+
+| Invocation | Scope |
+|------------|-------|
+| `/improve` | Entire `src/` directory (or project root) |
+| `/improve src/utils` | Specific directory |
+| `/improve file.ts` | Single file |
+| `/improve performance` | Performance-focused analysis |
+| `/improve tests` | Test coverage analysis |
+| `/improve docs` | Documentation analysis |
+| `/improve security` | Security-focused analysis |
+
+### 1.2 Analysis Categories
+
+Scan for improvements in these categories:
+
+#### Code Quality
+- Inconsistent patterns across similar files
+- Complex functions (high cyclomatic complexity)
+- Code duplication
+- Unused exports or dead code
+- Missing error handling
+- Type safety issues (`any` types, missing types)
+
+**Detection strategies:**
+```bash
+# Find 'any' types
+grep -r ": any" --include="*.ts" --include="*.tsx"
+
+# Find TODO/FIXME comments
+grep -r "TODO\|FIXME" --include="*.ts" --include="*.tsx"
+
+# Find large files (potential split candidates)
+find src -name "*.ts" -exec wc -l {} \; | sort -rn | head -20
+
+# Find duplicate code patterns
+# (Analyze similar function signatures across files)
+```
+
+#### Performance
+- Inefficient loops or operations
+- Missing memoization opportunities
+- Unnecessary re-renders (React)
+- Large bundle imports
+- Missing lazy loading
+
+**Detection strategies:**
+```bash
+# Find large dependencies
+grep -r "from ['\"]" --include="*.ts" | grep -E "lodash|moment|axios" | head -10
+
+# Find potential N+1 patterns
+grep -r "\.map\(.*await" --include="*.ts"
+```
+
+#### Missing Tests
+- Files without corresponding test files
+- Exported functions without test coverage
+- Edge cases not covered
+
+**Detection strategies:**
+```bash
+# Find files without tests
+for f in src/**/*.ts; do
+  test_file="${f%.ts}.test.ts"
+  if [ ! -f "$test_file" ]; then
+    echo "Missing test: $f"
+  fi
+done
+```
+
+#### Documentation Gaps
+- Public APIs without JSDoc
+- Missing README sections
+- Outdated documentation
+- Missing usage examples
+
+**Detection strategies:**
+```bash
+# Find exported functions without JSDoc
+grep -B5 "export function\|export const\|export class" --include="*.ts"
+```
+
+#### Security Concerns
+- Hardcoded secrets or credentials
+- SQL injection risks
+- XSS vulnerabilities
+- Insecure dependencies
+
+**Detection strategies:**
+```bash
+# Find potential secrets
+grep -r "password\|secret\|api_key\|apikey" --include="*.ts" -i
+
+# Check for outdated dependencies
+npm audit --json 2>/dev/null | jq '.vulnerabilities | length'
+```
+
+#### Refactoring Candidates
+- Functions > 50 lines
+- Files > 500 lines
+- Deeply nested code
+- God objects/functions
+
+**Detection strategies:**
+```bash
+# Find long functions
+# (Manual analysis based on function boundaries)
+
+# Find long files
+find src -name "*.ts" -exec wc -l {} \; | awk '$1 > 500'
+```
+
+### 1.3 MCP Enhancement (Optional)
+
+If MCP servers are available, enhance analysis:
+
+**Context7 (if available):**
+- Check for outdated library patterns
+- Suggest modern alternatives
+
+**Sequential Thinking (if available):**
+- Deep analysis of complex refactoring decisions
+
+**Fallback:** All core functionality works with standard tools only.
+
+## Phase 2: Critical Self-Assessment (REQUIRED)
+
+**Before presenting any findings, critically evaluate each one.**
+
+The goal is to filter out busywork and only surface improvements that provide real value. Pattern-matching finds "issues" - honest assessment determines if they matter.
+
+### 2.1 Assessment Questions
+
+For each potential finding, ask:
+
+| Question | If "No" → Filter Out |
+|----------|---------------------|
+| Does this cause real problems today? | Skip theoretical issues |
+| Would fixing this measurably improve the codebase? | Skip cosmetic changes |
+| Is the fix worth the maintenance burden it adds? | Skip if tests/code add more complexity than value |
+| Would a senior engineer care about this? | Skip pedantic findings |
+| Is this the right time to fix this? | Skip if other priorities exist |
+
+### 2.2 Common False Positives to Filter
+
+**Always skip these unless explicitly requested:**
+
+| Pattern Match | Why It's Usually Noise |
+|---------------|----------------------|
+| `any` in test files | Test mocks are hard to type; ESLint disables are fine |
+| `any` with eslint-disable comment | Already acknowledged and accepted |
+| Missing tests for <100 line files | Maintenance burden exceeds value |
+| Missing tests for files tested implicitly | Integration tests often suffice |
+| TODOs that are "nice to have" | If it worked without it for months, it's low priority |
+| Large files that work fine | Size alone isn't a problem if code is cohesive |
+| Low-severity dependency vulns | DoS in dev tools rarely matters |
+| Missing JSDoc on internal functions | Self-documenting code > comment maintenance |
+
+### 2.3 Honest Filtering
+
+After filtering, you should typically have:
+- **0-3 findings** for a well-maintained codebase
+- **5-10 findings** for a codebase with real issues
+- **10+ findings** only for neglected codebases
+
+**If your initial scan found 10+ issues but filtering leaves 0-2, that's correct behavior.** Report honestly:
+
+```markdown
+## Codebase Improvement Analysis
+
+**Scope:** `src/`
+**Initial Scan:** 12 potential issues
+**After Critical Assessment:** 2 worth addressing
+
+The codebase is in good shape. Most findings were false positives:
+- 8 "missing tests" for small files (not worth the maintenance)
+- 1 `any` type in test file (already has eslint-disable)
+- 1 TODO that's a nice-to-have, not a bug
+```
+
+### 2.4 When to Keep Findings
+
+Keep findings that:
+- Cause actual bugs or errors
+- Block future development
+- Create security vulnerabilities (real ones, not theoretical)
+- Make the code significantly harder to understand
+- Were explicitly requested by the user (e.g., `/improve tests`)
+
+## Phase 3: Present Findings
+
+### 3.1 Effort Classification
+
+Categorize each finding by estimated effort:
+
+| Category | Description | Typical Items |
+|----------|-------------|---------------|
+| **Quick Wins** | < 1 hour | Add missing types, fix linting, add JSDoc |
+| **Medium Effort** | 1-4 hours | Add tests, refactor function, improve error handling |
+| **Larger Refactors** | 4+ hours | Split large file, redesign module, add feature |
+
+### 3.2 Output Format
+
+Present findings in a structured, actionable format:
+
+```markdown
+## Codebase Improvement Analysis
+
+**Scope:** `src/` (or specified area)
+**Files Analyzed:** 47
+**Issues Found:** 12
+
+---
+
+### Quick Wins (< 1 hour)
+
+| # | Type | Location | Description |
+|---|------|----------|-------------|
+| 1 | Type Safety | `src/lib/api.ts:45` | Replace `any` with proper type |
+| 2 | Documentation | `src/utils/format.ts` | Add JSDoc to exported functions |
+| 3 | Code Quality | `src/components/Button.tsx` | Remove unused import |
+
+### Medium Effort (1-4 hours)
+
+| # | Type | Location | Description |
+|---|------|----------|-------------|
+| 4 | Tests | `src/lib/validation.ts` | Add unit tests (0% coverage) |
+| 5 | Error Handling | `src/api/client.ts` | Add retry logic for network errors |
+| 6 | Performance | `src/hooks/useData.ts` | Add memoization to prevent re-fetches |
+
+### Larger Refactors (4+ hours)
+
+| # | Type | Location | Description |
+|---|------|----------|-------------|
+| 7 | Architecture | `src/lib/legacy.ts` | Split 800-line file into modules |
+| 8 | Refactor | `src/components/Dashboard/` | Extract shared logic to hooks |
+
+---
+
+**Select improvements to create issues for (enter numbers, e.g., "1,2,4,7"):**
+```
+
+## Phase 4: Selection
+
+### 4.1 User Selection
+
+Use `AskUserQuestion` to let the user select improvements:
+
+```javascript
+AskUserQuestion({
+  questions: [{
+    question: "Which improvements would you like to create issues for?",
+    header: "Select",
+    options: [
+      { label: "All Quick Wins", description: "Create issues for items 1-3" },
+      { label: "All Medium", description: "Create issues for items 4-6" },
+      { label: "Custom Selection", description: "Specify item numbers" }
+    ],
+    multiSelect: false
+  }]
+})
+```
+
+### 4.2 Validation
+
+- Validate selected numbers exist
+- Confirm selections before creating issues
+- Allow adding related items
+
+## Phase 5: Issue Creation
+
+### 5.1 Issue Template
+
+For each selected improvement, create a well-formatted GitHub issue:
+
+```markdown
+## Summary
+
+[Brief description of the improvement]
+
+## Current State
+
+[What currently exists or the problem]
+
+## Proposed Change
+
+[What should be done]
+
+## Acceptance Criteria
+
+- [ ] [Specific, testable criteria]
+- [ ] [Another criterion]
+
+## Context
+
+- **Location:** `[file path]`
+- **Type:** [Code Quality | Performance | Tests | Docs | Security | Refactor]
+- **Effort:** [Quick Win | Medium | Large]
+- **Identified by:** `/improve` analysis
+
+## Related
+
+- Part of improvement batch from `/improve` analysis
+- Related issues: [if any]
+```
+
+### 5.2 Label Mapping
+
+Map improvement types to GitHub labels:
+
+| Type | Labels |
+|------|--------|
+| Code Quality | `enhancement`, `code-quality` |
+| Performance | `enhancement`, `performance` |
+| Missing Tests | `enhancement`, `tests` |
+| Documentation | `docs` |
+| Security | `security`, `priority:high` |
+| Refactoring | `enhancement`, `refactor` |
+
+### 5.3 Issue Creation
+
+```bash
+gh issue create \
+  --title "improve(<scope>): <brief description>" \
+  --body "<issue body>" \
+  --label "<labels>"
+```
+
+### 5.4 Batch Creation
+
+When creating multiple issues:
+1. Create issues sequentially
+2. Collect issue numbers
+3. Link related issues in comments
+4. Output summary
+
+```markdown
+## Issues Created
+
+| # | Issue | Title | Labels |
+|---|-------|-------|--------|
+| 1 | #234 | improve(api): Add proper types to api.ts | enhancement, code-quality |
+| 2 | #235 | improve(validation): Add unit tests | enhancement, tests |
+| 3 | #236 | improve(legacy): Split into modules | enhancement, refactor |
+```
+
+## Phase 6: Execution Offer
+
+### 6.1 Output Command
+
+After creating issues, offer the execution command:
+
+```markdown
+## Ready to Execute
+
+Created issues: #234, #235, #236
+
+**Run these improvements:**
+```bash
+npx sequant run 234 235 236
+```
+
+**Or run individually:**
+```bash
+/fullsolve 234   # Quick win: Add types
+/fullsolve 235   # Medium: Add tests
+/fullsolve 236   # Large: Split legacy file
+```
+
+> **Tip:** Quick wins (#234) are great candidates for batch execution.
+> Larger refactors (#236) may benefit from `/fullsolve` for more thorough handling.
+```
+
+### 6.2 Execution Options
+
+Provide context-aware recommendations:
+
+- **Quick Wins:** Recommend batch execution with `sequant run`
+- **Medium Effort:** Recommend sequential execution
+- **Large Refactors:** Recommend individual `/fullsolve` with quality loop
+
+## Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| MAX_FINDINGS | 20 | Maximum improvements to report |
+| SKIP_NODE_MODULES | true | Ignore node_modules |
+| INCLUDE_PATTERNS | `*.ts,*.tsx,*.js,*.jsx` | Files to analyze |
+| EXCLUDE_PATTERNS | `*.test.*,*.spec.*` | Files to skip |
+
+## Examples
+
+### Example 1: Full Codebase Analysis
+
+```
+User: /improve
+
+Agent: Analyzing codebase for improvement opportunities...
+
+## Codebase Improvement Analysis
+
+**Scope:** `src/`
+**Files Analyzed:** 47
+**Issues Found:** 8
+
+---
+
+### Quick Wins (< 1 hour)
+
+| # | Type | Location | Description |
+|---|------|----------|-------------|
+| 1 | Type Safety | `src/lib/api.ts:45` | Replace `any` with `ApiResponse` type |
+| 2 | Code Quality | `src/utils/index.ts` | Remove unused `formatDate` export |
+
+### Medium Effort (1-4 hours)
+
+| # | Type | Location | Description |
+|---|------|----------|-------------|
+| 3 | Tests | `src/lib/validation.ts` | Add unit tests (currently 0% coverage) |
+| 4 | Documentation | `src/hooks/` | Add JSDoc to custom hooks |
+
+### Larger Refactors (4+ hours)
+
+| # | Type | Location | Description |
+|---|------|----------|-------------|
+| 5 | Architecture | `src/lib/legacy.ts` | Split 800-line file into modules |
+
+---
+
+Which improvements would you like to create issues for?
+
+User: 1, 3, 5
+
+Agent: Creating 3 issues...
+
+## Issues Created
+
+| # | Issue | Title | Labels |
+|---|-------|-------|--------|
+| 1 | #234 | improve(api): Replace any type with ApiResponse | enhancement |
+| 2 | #235 | improve(validation): Add unit tests | enhancement, tests |
+| 3 | #236 | improve(legacy): Split into modules | enhancement, refactor |
+
+## Ready to Execute
+
+**Run these improvements:**
+```bash
+npx sequant run 234 235 236
+```
+
+> **Tip:** Issue #234 is a quick win - great for batch execution.
+> Issue #236 has `refactor` label - quality loop will auto-enable.
+```
+
+### Example 2: Focused Analysis
+
+```
+User: /improve src/lib/api.ts
+
+Agent: Analyzing `src/lib/api.ts` for improvement opportunities...
+
+## File Improvement Analysis
+
+**File:** `src/lib/api.ts`
+**Lines:** 245
+**Issues Found:** 4
+
+---
+
+### Quick Wins
+
+| # | Type | Location | Description |
+|---|------|----------|-------------|
+| 1 | Type Safety | Line 45 | Replace `data: any` with proper type |
+| 2 | Type Safety | Line 78 | Replace `options?: any` with `RequestOptions` |
+
+### Medium Effort
+
+| # | Type | Location | Description |
+|---|------|----------|-------------|
+| 3 | Error Handling | Lines 89-120 | Add retry logic for transient errors |
+| 4 | Tests | - | Add integration tests for API client |
+
+---
+
+Which improvements would you like to create issues for?
+```
+
+### Example 3: Topic-Focused Analysis
+
+```
+User: /improve security
+
+Agent: Running security-focused analysis...
+
+## Security Analysis
+
+**Scope:** Entire codebase
+**Files Analyzed:** 47
+**Security Issues Found:** 3
+
+---
+
+### Findings
+
+| # | Severity | Location | Description |
+|---|----------|----------|-------------|
+| 1 | Medium | `src/config.ts:12` | API key in source (should use env var) |
+| 2 | Low | `package.json` | 2 dependencies with known vulnerabilities |
+| 3 | Info | `src/api/client.ts` | No request timeout configured |
+
+---
+
+Which issues would you like to create?
+```
+
+## Error Handling
+
+### No Improvements Found
+
+If analysis finds no improvements:
+
+```markdown
+## Codebase Improvement Analysis
+
+**Scope:** `src/utils/`
+**Files Analyzed:** 5
+**Issues Found:** 0
+
+No significant improvement opportunities identified in this area.
+
+**Suggestions:**
+- Try analyzing a larger scope: `/improve src/`
+- Focus on a specific category: `/improve tests`
+- The codebase may already be well-maintained
+```
+
+### Invalid Scope
+
+If the specified path doesn't exist:
+
+```markdown
+Error: Path `src/nonexistent/` not found.
+
+**Did you mean:**
+- `src/utils/`
+- `src/lib/`
+
+**Or try:**
+- `/improve` (analyze entire codebase)
+```
+
+## Notes
+
+- This skill is **interactive** - it analyzes, presents, and waits for user selection
+- Issue creation requires user confirmation before proceeding
+- All analysis uses standard tools (Glob, Grep, Read) - no MCP dependency
+- Large codebases may be sampled to keep analysis manageable
+- Focus arguments (`performance`, `tests`, etc.) narrow the analysis scope
+
+---
+
+## Output Verification
+
+**Before responding, verify your output includes ALL of these:**
+
+- [ ] **Analysis Summary** - Scope, files analyzed, issues found
+- [ ] **Categorized Findings** - Quick Wins, Medium Effort, Larger Refactors tables
+- [ ] **Selection Prompt** - Ask user which items to create issues for
+- [ ] **Issues Created** - Table with issue numbers, titles, and labels (after selection)
+- [ ] **Execution Command** - `npx sequant run <issue-numbers>` command
+- [ ] **Recommendations** - Tips for running quick wins vs larger refactors
+
+**DO NOT proceed to issue creation without user selection.**
+**DO NOT respond until all items are verified.**