octocode-cli 1.2.8 → 1.2.9

package/skills/octocode-engineer/references/quality-indicators.md

@@ -0,0 +1,202 @@
+# Quality Indicators Reference
+
+> Complete catalog of code quality signals detected by the octocode-engineer scanner.
+
+## Overview
+
+The scanner detects quality indicators across 5 pillars: **Architecture**, **Code Quality**, **Dead Code**, **Security**, and **Test Quality**. Each indicator produces a finding with severity (critical/high/medium/low/info), actionable fix guidance, and LSP validation hints.
+
+---
+
+## Metrics Engine
+
+### Cyclomatic Complexity
+- **What**: Number of independent paths through a function's source code.
+- **How**: Increments for `if`, `while`, `for`, `switch/case`, `catch`, `||`, `&&`, `??`, ternary.
+- **Threshold**: `criticalComplexityThreshold` (default: 30).
+- **Engines**: TypeScript Compiler, Tree-sitter.
+
+### Cognitive Complexity
+- **What**: Mental load to understand a function — penalizes nesting more than branching.
+- **How**: Increments for control-flow keywords; adds nesting depth bonus for each level.
+- **Threshold**: `cognitiveComplexityThreshold` (default: 15).
+- **Engines**: TypeScript Compiler, Tree-sitter (now at parity).
+
+### Halstead Metrics
+- **What**: Software science metrics based on operator/operand vocabulary.
+- **Computed**: volume, difficulty, effort, time, estimated bugs.
+- **Threshold**: `halsteadEffortThreshold` (default: 500,000).
+- **Engine**: TypeScript Compiler only.
+
+### Maintainability Index (MI)
+- **What**: Composite score (0–171) indicating ease of maintenance.
+- **Formula**: `171 - 5.2·ln(V) - 0.23·CC - 16.2·ln(LOC)` (clamped to [0, 100]).
+- **Threshold**: `maintainabilityIndexThreshold` (default: 20).
+- **Engine**: TypeScript Compiler only.
+
+---
+
+## Code Quality Detectors (34 total)
+
+### Existing Detectors
+
+| # | Category | Severity | Description |
+|---|----------|----------|-------------|
+| 1 | `duplicate-function-body` | low–high | Identical function body hash across locations |
+| 2 | `duplicate-flow-structure` | low–medium | Repeated control-flow structure shapes |
+| 3 | `function-optimization` | medium–high | High cyclomatic complexity or deep nesting |
+| 4 | `cognitive-complexity` | medium–high | High cognitive complexity per function |
+| 5 | `god-function` | high | Oversized functions by statement count + low MI |
+| 6 | `excessive-parameters` | medium | Functions with too many parameters |
+| 7 | `empty-catch` | medium | Empty catch blocks silently swallowing errors |
+| 8 | `switch-no-default` | low | Switch statements without default case |
+| 9 | `unsafe-any` | medium | Files with excessive `any` type usage |
+| 10 | `halstead-effort` | medium–high | Functions with extreme Halstead effort |
+| 11 | `low-maintainability` | medium–high | Functions below MI threshold |
+| 12 | `type-assertion-escape` | medium | `as any`, double assertions, non-null assertions |
+| 13 | `missing-error-boundary` | medium | Async functions with awaits but no try-catch |
+| 14 | `promise-misuse` | low | Async functions without any await |
+| 15 | `await-in-loop` | medium | Await calls inside loops (sequential where parallel possible) |
+| 16 | `sync-io` | medium | Synchronous I/O calls (readFileSync, etc.) |
+| 17 | `uncleared-timer` | medium | setInterval without corresponding clearInterval |
+| 18 | `listener-leak-risk` | medium | Event listeners added without removal |
+| 19 | `unbounded-collection` | medium | Potential unbounded collection growth |
+| 20 | `similar-function-body` | low–medium | Near-duplicate functions by metric similarity |
+| 21 | `message-chain` | medium–high | Deep property chains violating Law of Demeter |
+
+### Semantic-Gated Detectors (require `--semantic`)
+
+| # | Category | Severity | Description |
+|---|----------|----------|-------------|
+| 22 | `god-module` | medium–high | Oversized modules by statement count + export count |
+| 23 | `unused-parameter` | low | Function parameters never referenced in body |
+| 24 | `deep-override-chain` | medium | Method override chains exceeding depth threshold |
+| 25 | `interface-compliance` | medium | Types claiming to implement an interface but missing members |
+| 26 | `narrowable-type` | low | Union types that could be narrowed for better type safety |
+
+### New Detectors (v2)
+
+| # | Category | Severity | Description |
+|---|----------|----------|-------------|
+| 27 | `deep-nesting` | low–high | Functions with branch/loop nesting exceeding threshold |
+| 28 | `multiple-return-paths` | low–high | Functions with too many return/throw exit points |
+| 29 | `catch-rethrow` | low | Catch blocks containing a throw statement (simplification candidates) |
+| 30 | `magic-string` | low–high | String literals repeated in comparisons across files |
+| 31 | `boolean-parameter-cluster` | medium | Functions with 3+ boolean parameters |
+| 32 | `promise-all-unhandled` | medium | Promise.all/race/any without error handling |
+| 33 | `export-surface-density` | low–high | Modules where >50% of statements are exported |
+| 34 | `change-risk` | medium–critical | Composite risk score from overlapping quality signals |
+
+---
+
+## New Detector Details
+
+### deep-nesting
+- **Threshold**: `deepNestingThreshold` (default: 5)
+- **Signal**: `max(maxBranchDepth, maxLoopDepth)` per function
+- **Severity mapping**: `≥ threshold+3` → high, `≥ threshold+1` → medium, else → low
+- **Fix strategy**: Guard clauses, early returns, extract to named helpers
+
+### multiple-return-paths
+- **Threshold**: `multipleReturnThreshold` (default: 6)
+- **Signal**: `returns` count per function (includes throw statements)
+- **Severity mapping**: `≥ threshold+4` → high, `≥ threshold+2` → medium, else → low
+- **Fix strategy**: Single result variable, guard clauses for error paths only
+
+### catch-rethrow
+- **Signal**: Catch blocks containing a throw statement — candidates for simplification (may include other statements alongside the rethrow)
+- **Severity**: Always low (noise reduction)
+- **Fix strategy**: Remove the try-catch if only rethrowing, or add logging/wrapping before re-throw
+
+### magic-string
+- **Threshold**: `magicStringMinOccurrences` (default: 3)
+- **Signal**: String literals used in `===`, `!==`, `==`, `!=` comparisons or `case` clauses, appearing ≥ threshold times
+- **Severity mapping**: `≥ 8` → high, `≥ 5` → medium, else → low
+- **Fix strategy**: Extract to named constant or enum
+
+### boolean-parameter-cluster
+- **Threshold**: `booleanParamThreshold` (default: 3)
+- **Signal**: Functions with ≥ threshold parameters typed as `boolean`
+- **Severity**: Always medium
+- **Fix strategy**: Replace with options object or split into separate functions
+
+### promise-all-unhandled
+- **Signal**: `Promise.all/allSettled/race/any` calls without surrounding try-catch or `.catch()` chain
+- **Severity**: Always medium
+- **Fix strategy**: Wrap in try-catch or chain `.catch()`
+
+### export-surface-density
+- **Signal**: `exportCount / totalStatements` ratio ≥ 0.5 (modules with ≥ 20 statements)
+- **Severity mapping**: `≥ 80%` → high, `≥ 60%` → medium, else → low
+- **Fix strategy**: Make non-essential symbols private, split into facade + implementation
+
+### change-risk (composite)
+- **Signal**: Weighted sum of overlapping quality problems in a single file
+- **Components scored**:
+  - High average complexity → +2
+  - High cognitive complexity → +2
+  - Low maintainability functions → +count
+  - Empty catches → +1
+  - Unhandled promise combinators → +1
+  - Excessive exports (>15) → +1
+- **Threshold**: Score ≥ 4 triggers finding
+- **Severity mapping**: `≥ 8` → critical, `≥ 6` → high, else → medium
+
+---
+
+## AST Search Presets (22 total)
+
+### Existing Presets
+`empty-catch`, `console-log`, `console-any`, `debugger`, `todo-fixme`, `any-type`, `type-assertion`, `non-null-assertion`, `fat-arrow-body`, `nested-ternary`, `throw-string`, `switch-no-default`, `class-declaration`, `async-function`, `export-default`, `import-star`
+
+### New Presets (v2)
+| Preset | Description |
+|--------|-------------|
+| `catch-rethrow` | Catch blocks that only re-throw the caught error |
+| `promise-all` | Promise.all calls — check for missing error handling |
+| `boolean-param` | Function parameters typed as boolean |
+| `magic-number` | Numeric literals (excluding 0 and 1) |
+| `deep-callback` | 3+ levels of nested arrow function callbacks |
+| `unused-var` | Variable declarations without call expressions |
+
+---
+
+## Thresholds Reference
+
+All thresholds are configurable via CLI flags (e.g. `--critical-complexity-threshold 30`, `--deep-nesting-threshold 5`) or config file. See [CLI reference](./cli-reference.md) for exact flag names.
+
+| Threshold | Default | Used By |
+|-----------|---------|---------|
+| `criticalComplexityThreshold` | 30 | function-optimization |
+| `cognitiveComplexityThreshold` | 15 | cognitive-complexity |
+| `halsteadEffortThreshold` | 500,000 | halstead-effort |
+| `maintainabilityIndexThreshold` | 20 | low-maintainability |
+| `parameterThreshold` | 5 | excessive-parameters |
+| `anyThreshold` | 5 | unsafe-any |
+| `flowDupThreshold` | 3 | duplicate-flow-structure |
+| `similarityThreshold` | 0.85 | similar-function-body |
+| `godFunctionStatements` | 100 | god-function |
+| `godFunctionMiThreshold` | 10 | god-function |
+| `deepNestingThreshold` | 5 | deep-nesting |
+| `multipleReturnThreshold` | 6 | multiple-return-paths |
+| `magicStringMinOccurrences` | 3 | magic-string |
+| `booleanParamThreshold` | 3 | boolean-parameter-cluster |
+
+---
+
+## Algorithms
+
+### Tarjan's SCC (Strongly Connected Components)
+Used to detect dependency cycle clusters. O(V+E) complexity. Identifies groups of modules that form circular dependencies.
+
+### Articulation Points & Bridge Edges
+Graph theory algorithms to find critical nodes (removing one disconnects the graph) and critical edges. Identifies architectural chokepoints.
+
+### Structural Hashing
+Functions are hashed by their AST structure (ignoring identifiers/literals) to detect true duplicates vs. near-duplicates.
+
+### Metric Similarity
+Near-duplicate detection uses feature-vector similarity: `1 - |a-b|/max(a,b)` across 8 metrics (complexity, depth, returns, awaits, calls, loops, statements).
+
+### Composite Risk Scoring
+The `change-risk` detector aggregates multiple quality signals into a single score per file, identifying files most likely to cause regressions.

package/skills/octocode-engineer/references/tool-workflows.md

@@ -0,0 +1,298 @@
+# Tool Workflows — Research Methodology & Patterns
+
+Step-focused workflows for code analysis. For multi-angle investigation principles and tool descriptions, see [SKILL.md](../SKILL.md#how-to-investigate). For tool params and flags, see [CLI reference](./cli-reference.md).
+
+---
+
+## Quick Decision Table
+
+| Question | Approach |
+|----------|----------|
+| "What does this codebase look like?" | Explore directory structure → find large files → spot hotspots |
+| "Does pattern X exist?" | AST structural search with preset or pattern |
+| "Where is X defined?" | Text search to locate → jump to definition |
+| "Who calls function X?" | Text search for lineHint → call hierarchy (incoming) |
+| "All usages of type/var X?" | Text search for lineHint → find references |
+| "Is export X dead?" | Find references (exclude declaration) → cross-check with AST import search |
+| "What's the AST shape of file X?" | AST tree-search on scan artifact |
+| "Read this function" | Read file content with match targeting |
+| "Trace flow A → B" | Search → definition jump → call hierarchy → chain hops |
+| "Architecture hotspots?" | Scan with graph analysis → validate hotFiles with reference counts |
+| "Structural smells?" | AST preset sweep (batch multiple presets in parallel) |
+| "Did my fix work?" | Re-scan scoped to changed files + AST preset check + project toolchain |
+
+---
+
+## Workflows
+
+### 1 — Full Scan → Triage → Validate
+
+Start here for any new codebase or broad audit.
+
+1. **Run full scan** with graph + flow flags → generates hypotheses
+2. **Read summary.md** → health scores, pillar grades, top recommendations
+3. **Triage top findings** from findings.json → check severity, lspHints, correlated signals
+4. **Quick structural triage** — AST tree-search for function declarations to spot large/complex shapes
+5. **Explore project layout** — directory structure + largest files for hotspot candidates
+6. **Validate top findings** — use lspHints from findings to confirm or dismiss via reference counts and call hierarchy
+
+See [output files](./output-files.md) for scan artifact schemas and read order. See [validation playbooks](./validation-playbooks.md) for per-category validation tactics.
+
+### 2 — Symbol Deep Dive
+
+Trace a function: definition → callers → callees.
+
+1. **Check AST shape** — tree-search for the function to see its span, nesting depth, and structure
+2. **Locate the symbol** — text search to get file + lineHint
+3. **Read the function body** — targeted file content around the function
+4. **Jump to definition** — follow the symbol to its canonical definition
+5. **Find callers** — incoming call hierarchy → who depends on this?
+6. **Find callees** — outgoing call hierarchy → what does this depend on?
+
+### 3 — Impact Analysis (Pre-Refactor)
+
+Assess blast radius before changing a symbol.
+
+1. **Map structural imports** — AST search for import patterns involving the symbol
+2. **Locate the symbol** — text search to get file + lineHint
+3. **Count all consumers** — find references, excluding declaration
+4. **Count test consumers** — find references filtered to test directories only
+5. **Count production consumers** — find references excluding test directories
+6. **Assess safety** — few production refs + high test coverage = safe to change. Many production refs = plan carefully, consider incremental migration.
+
+### 4 — Dead Export Validation
+
+Fastest path from finding to verdict.
+
+1. **Check for consumers** — find references excluding declaration. 0 refs = likely dead, >0 = alive.
+2. **Cross-check structurally** — AST search for import statements of the export name
+3. **Check for dynamic usage** — text search for the export name to catch computed/dynamic references
+4. **Verdict** — 0 consumers across all checks = confirmed dead. Any usage found = dismiss.
+
+### 5 — Code Smell Sweep (AST Presets)
+
+Structural code smell detection — zero false positives.
+
+1. **Run AST presets in parallel** — batch presets: empty-catch, any-type, console-log, switch-no-default, nested-ternary, non-null-assertion
+2. **Add custom pattern checks** if needed (e.g. eval usage, specific anti-patterns)
+3. **Read context** around flagged locations to understand severity
+4. **Assess impact** — check callers of flagged functions to gauge blast radius
+
+See [AST reference](./ast-reference.md) for all presets and pattern syntax.
+
+### 6 — Dependency Cycle Tracing
+
+Validate cycles from `architecture.json`.
+
+1. **Scan for cycles** — run scan with dependency-cycle feature + graph
+2. **Read cycle paths** from architecture.json
+3. **Find back-edge imports** — AST search for import patterns in the cycle directory
+4. **Identify importing files** — text search for imports from the cycle modules
+5. **Read the import blocks** — targeted content reading at import statements
+6. **Trace through the chain** — jump to definitions and follow call hierarchy until the cycle closes
+
+### 7 — Security Sink Validation
+
+Trace data flow from source to sink.
+
+1. **Find sink patterns** — AST search for eval, innerHTML assignment, exec, command injection patterns
+2. **Find secret patterns** — AST rule search for strings matching password/secret/token patterns
+3. **Find guards** — text search for validation, sanitization, or normalization functions
+4. **Read sink context** — targeted content reading around the sink function
+5. **Locate the sink** — jump to definition for cross-file resolution
+6. **Trace data sources** — incoming call hierarchy to trace who feeds data to the sink
+7. **Check all call sites** — find references for the sink function to assess exposure breadth
+
+See [validation playbooks](./validation-playbooks.md) for taint-tracing and false-positive dismissal.
+
+### 8 — Scoped Deep-Dive (File or Function)
+
+Drill into a specific flagged file or function.
+
+1. **Re-scan scoped** — scan with scope narrowed to the target file, with flow + semantic flags
+2. **Function-level scope** — if drilling into a specific function, use `file:symbol` scope syntax
+3. **Check AST shape** — tree-search for the file to see function spans and nesting
+4. **Read public surface** — targeted content at export declarations
+5. **Read imports** — content at the top of the file for dependency context
+6. **Read target section** — content around the specific area of interest
+7. **Count consumers per export** — find references for each exported symbol
+8. **Map function dependencies** — outgoing call hierarchy per function
+
+### 9 — Coupling Hotspot Analysis
+
+Quantify coupling for architecture findings.
+
+1. **Scan for coupling signals** — run scan with coupling + god-module features + advanced graph
+2. **Read top hotFiles** from architecture.json
+3. **Map import density** — AST search for import patterns in the hotspot directory
+4. **Count consumer files** — text search for imports from the hotspot
+5. **Assess module size** — structure view of the hotspot directory + find largest files
+6. **Quantify per-export coupling** — find references for each export, call hierarchy for each function
+
+**Decision**: high fan-in + large files = decomposition candidate. Low fan-in = less urgent.
+
+### 10 — Fix Verification Loop
+
+Confirm fixes reduced finding count. Run after every fix batch.
+
+1. **Re-scan changed files** — scoped scan with relevant feature flags
+2. **AST smell check** — run presets against changed directories to verify smells are gone
+3. **Spot-check fixes** — read fixed code to confirm the change looks right
+4. **Verify references** — find references to confirm moved/renamed symbols still resolve
+5. **Verify callers** — incoming call hierarchy to confirm callers are still connected
+6. **Run project toolchain** — lint (with auto-fix), tests, build → all must pass
+
+---
+
+## Extended Workflows — Architecture, Planning, Exploration
+
+### 11 — Pre-Implementation Check ("Where should new code live?")
+
+Before writing new code, understand the existing landscape to pick the right location.
+
+1. **Explore project layout** — directory structure at depth 2
+2. **Map dependency graph** — scan with graph + advanced flags → identify hotspots
+3. **Avoid hotspots** — read top hotFiles from architecture.json, don't add to them
+4. **Find analogous patterns** — text search for similar features to see how the codebase does it
+5. **Check existing API shape** — AST search for export patterns in candidate directories
+6. **Check candidate module coupling** — find references for candidate module's exports
+7. **Read the public surface** — targeted content at exports of the target module
+
+**Decision**: low fan-in module with related exports = good home. High fan-in hotspot = add to a new module instead.
+
+### 12 — Refactoring Plan (Safe Restructure)
+
+Plan a multi-file refactor with full blast radius awareness.
+
+1. **Map all files containing the symbol** — text search with file-list mode
+2. **Count all consumers** — find references excluding declaration
+3. **Split test vs production consumers** — find references with include/exclude patterns for test dirs
+4. **Map callers and dependencies** — incoming and outgoing call hierarchy
+5. **Check import graph** — AST search for import patterns in the target area
+6. **Check coupling/cycle risk** — scoped scan with architecture + graph features
+7. **Assess test quality around target** — scoped scan with test-quality feature
+
+**Output**: file list + consumer count + test coverage + coupling risk = refactoring confidence level.
+
+### 13 — Codebase Exploration (New Repo Orientation)
+
+Quickly understand an unfamiliar codebase.
+
+1. **Layout** — top-level directory structure → source root shape with file sizes
+2. **Scale and hotspots** — find largest files, recently modified files, barrel/index files
+3. **API surface** — text search for exports (file-list mode), AST search for class declarations and default exports
+4. **Architecture shape** — full scan with graph + flow → read summary.md for health scores
+5. **Conventions** — AST search for import patterns, text search for test patterns, find test file locations
+
+### 14 — Test Strategy Analysis
+
+Map test coverage gaps and test quality issues.
+
+1. **Test landscape** — find all test files, explore test directory structure, count test density
+2. **Coverage gaps** — text search for exported functions, then find references filtered to test dirs. 0 test refs = coverage gap.
+3. **Test quality** — scan with test-quality feature + include-tests. AST search for empty catches, mock density, assertion density in test source
+4. **Critical untested code** — scan for architecture to find critical paths, check test coverage per hotFile
+
+**Output**: untested exports list + test quality findings + critical untested hotspots = test priority plan.
+
+### 15 — Code Review Support (Change Impact Analysis)
+
+Assess the architectural impact of changed files.
+
+1. **Read the changes** — targeted content reading around changed functions
+2. **Blast radius per symbol** — text search for changed symbols → find references → split test vs production → incoming call hierarchy for direct callers
+3. **Architecture effect** — scoped scan of changed files with architecture + graph → AST search for new import patterns
+4. **Quality check** — scoped scan of changed files with code-quality + security features → AST preset sweep on changed dirs for new smells
+5. **Test coverage** — find references for changed symbols filtered to test directories → are all changes tested?
+
+**Output**: consumer impact count + architecture delta + new quality issues + test coverage = review verdict.
+
+### 16 — Code Quality Review (Module or File)
+
+Focused quality review of a specific target.
+
+1. **Scoped scan** — scan target with code-quality + dead-code features, flow + semantic flags → read summary + top findings
+2. **AST smell sweep** — batch presets: empty-catch, any-type, type-assertion, non-null-assertion, console-log, nested-ternary, switch-no-default
+3. **Complexity check** — AST tree-search for function spans + nesting, scoped scan for cognitive-complexity + god-module + god-function
+4. **Dead code check** — find references per export (0 refs = dead), AST cross-check on import patterns
+5. **Maintainability assessment** — read public surface size, map outgoing call hierarchy (dependency count), map incoming call hierarchy (fan-in per export)
+
+**Output**: smell count + complexity scores + dead exports + fan-in/fan-out + maintainability = quality verdict with evidence.
+
+### 17 — Full Architecture Analysis
+
+Complete architecture health assessment.
+
+1. **Full architecture scan** — graph + graph-advanced + flow + architecture features
+2. **Read architecture outputs** — summary.md health score, cycles, hotFiles (ranked), SCC clusters, chokepoints, critical paths, Mermaid graph
+3. **Validate top hotspots** — text search for hotspot files → find references for fan-in, call hierarchy for fan-out and direct callers
+4. **Module boundary analysis** — AST search for cross-module imports, text search for barrel re-exports, scan for boundary/layer violations
+5. **Cycle deep-dive** (per cycle) — AST search for imports in cycle dirs, jump to definitions to hop through, read import blocks to confirm back-edges
+6. **Critical path analysis** — read criticalPaths from architecture.json, check incoming call hierarchy for each hub
+
+**Output**: cycle list + SCC clusters + chokepoints + hotfiles (ranked) + boundary violations + critical paths + fan-in/fan-out = full architecture health report.
+
+### 18 — Smart Coding (Impact-Aware Changes)
+
+Before and after making code changes, check blast radius and verify safety.
+
+**=== BEFORE CODING ===**
+
+1. **Define behavior contract** — current behavior, desired behavior, invariants, non-goals, user-facing contract
+2. **Understand the target area** — explore module layout, read current code, jump to definitions
+3. **Check blast radius** — text search for target symbol → find references (total, production-only, test-only) → incoming call hierarchy for direct callers
+4. **Check architecture safety** — scoped scan with architecture + graph → read cycles to check if the change would create new ones
+5. **Follow existing patterns** — AST search for similar patterns nearby, text search for analogous implementations
+
+**=== MAKE THE CHANGE ===**
+
+6. **Implement** — apply edits
+
+**=== AFTER CODING ===**
+
+7. **Verify behavior** — run project tests
+8. **Verify no new issues** — scoped scan of changed files with code-quality + architecture features, AST preset sweep for any-type + empty-catch
+9. **Verify references intact** — find references for moved/renamed symbols, incoming call hierarchy for callers
+10. **Verify user-facing contracts** — run CLI/API/integration checks when relevant, update docs when behavior changed
+11. **Run project toolchain** — lint (with auto-fix), build
+
+**Decision gates**:
+- Step 3: >20 production consumers = high-risk, consider feature flag or incremental migration
+- Step 4: change touches cycle member or hotfile = extra caution, verify with re-scan after
+- Step 8: new findings = fix before committing
+- Step 10: docs or contract drift = fix before committing
+- Step 11: any failure = investigate before proceeding
+
+### 19 — CLI Change Safety
+
+Use when changing commands, flags, help text, output, or exit behavior.
+
+1. **Find CLI entry points** — text search for CLI frameworks (process.argv, commander, yargs, etc.) + find files named cli/bin/command
+2. **Read commands and options** — targeted content reading around command definitions, options, defaults
+3. **Find affected tests and docs** — text search for flag/command names across tests, scripts, and docs
+4. **Verify behavior** — run entry with --help, happy-path input, bad input; check stdout/stderr/exit codes
+5. **Run CLI and e2e tests** if the project has them
+
+**Checklist**: names, aliases, defaults, positional args, stdout/stderr, exit codes, env/config inputs, machine-readable output, backward compatibility.
+
+### 20 — API Contract Safety
+
+Use when changing handlers, endpoints, schemas, DTOs, or serialized responses.
+
+1. **Find the public surface** — text search for router/handler/endpoint/resolver patterns + schema/contract files
+2. **Read request/response code** — targeted content around route definitions
+3. **Trace affected internals** — text search for response/DTO types → find references for shared types → outgoing call hierarchy for handler→service flow
+4. **Verify the contract** — run integration, contract, and/or project test scripts
+
+**Checklist**: request schema, response shape, status codes, error bodies, auth, pagination, idempotency, versioning, deprecation, migration notes.
+
+### 21 — Docs and Rollout Sync
+
+Use when public behavior changed or a risky change needs an operational plan.
+
+1. **Find docs and examples** — find README, markdown, OpenAPI, env.example files + text search for changed names in docs
+2. **Update completion criteria** — docs/help/examples/migration notes updated; feature flag/rollout/telemetry/rollback decided when needed
+3. **Verify docs tooling** — run docs build/check scripts if the project has them
+
+**Output**: updated docs list + compatibility note + rollout/rollback plan, or explicit statement that no public docs or rollout work was needed.
+

package/skills/octocode-engineer/references/validation-playbooks.md

@@ -0,0 +1,99 @@
+# Validation Playbooks
+
+How to validate findings before presenting them. Every scanner finding is a hypothesis — never present it as fact without validation.
+
+For the validation loop (confirmed/dismissed/uncertain), see [SKILL.md](../SKILL.md#cross-validate-findings). For tool descriptions, see [SKILL.md tools](../SKILL.md#tools). For scanner flags, see [CLI reference](./cli-reference.md).
+
+---
+
+## Category playbooks
+
+| Category type | How to validate | Typical fix |
+|---------------|----------------|-------------|
+| Dead export | Find references excluding declaration → 0 refs = dead | Remove export or wire real usage |
+| Coupling hotspot | Measure fan-in (find references) + fan-out (outgoing call hierarchy) | Split module by responsibility/consumer group |
+| Dependency cycle | Read cycle path from architecture.json → trace imports through the chain | Break edge via shared contract/inversion |
+| Security sink | Trace data sources via incoming call hierarchy → check for guards before the sink | Add/centralize validation/sanitization before sink |
+| God function | Read body + map outgoing calls → count concerns and side effects | Extract focused helpers, keep orchestration thin |
+| Performance (await-in-loop) | Read loop body — is each iteration independent? Check for data dependency between iterations | Collect promises with `Promise.all()`. Keep sequential only when iteration N depends on N-1 |
+| Performance (sync I/O, listener leak) | Read body — sync I/O on hot path? Listeners without matching removal? | Replace sync with async; add cleanup |
+| Test gap | Find references for symbol filtered to test dirs → 0 test refs = gap | Add tests around public contract and edge paths |
+
+Use TDD for behavioral fixes when practical: failing test → fix → pass → full suite.
+
+---
+
+## Architecture interpretation
+
+Use these signals when raw findings are noisy:
+- **SCC cluster**: treat overlapping cycles as one refactor unit
+- **Broker/chokepoint**: high fan-in + high fan-out = dependency pressure node
+- **Bridge module**: articulation-style file connecting subsystems
+- **Package chatter**: excessive cross-package traffic indicates boundary erosion
+
+Prioritize fixes where hotspots and critical paths overlap.
+
+---
+
+## Metrics cheat sheet
+
+| Metric | Meaning | Typical threshold signal |
+|--------|---------|--------------------------|
+| Instability `I = Ce / (Ca + Ce)` | how change-prone vs depended-on a module is | stable module depending on more unstable one |
+| Cognitive complexity | branch/nesting mental load | >15 tends to need decomposition |
+| Maintainability index | overall maintainability score | <20 is high-risk maintainability |
+| Halstead effort | estimated comprehension effort | very high effort suggests split/refactor |
+
+Use thresholds as heuristics, not absolute truth.
+
+---
+
+## Worked examples
+
+Three end-to-end validation flows showing how to arrive at **confirmed**, **dismissed**, and **uncertain**.
+
+### Example 1: Confirmed — dead export
+
+**Finding**: `findings.json` reports `dead-export` for `formatDate` in `src/utils/dates.ts` (line 42).
+
+| Step | What was done | Result | Decision |
+|------|--------------|--------|----------|
+| 1 | Text search for "formatDate" scoped to the file | Match at line 42 — `export function formatDate(...)`. Got lineHint. | — |
+| 2 | Find references for `formatDate` at that lineHint, excluding declaration | **0 references** outside the declaration. | No consumers. |
+| 3 | Broad text search for "formatDate" across all files (file-list mode) | Only `src/utils/dates.ts` appears. No re-exports, no test imports. | No indirect usage. |
+
+**Verdict**: **Confirmed** (high confidence). Zero consumers in production and test code. Safe to remove the export or delete the function entirely.
+
+---
+
+### Example 2: Dismissed — false-positive coupling hotspot
+
+**Finding**: `architecture.json` lists `src/config/env.ts` as a coupling hotspot (fanIn=45, fanOut=2).
+
+| Step | What was done | Result | Decision |
+|------|--------------|--------|----------|
+| 1 | Read the full file (25 lines, small enough for full content) | Exports `const ENV = { ... }` — a read-only config object from `process.env`. No logic. | Pure config. |
+| 2 | Find references for `ENV` at its declaration, excluding declaration | 45 references across 32 files, all `import { ENV }` followed by property reads. No mutations. | All consumers read-only. |
+| 3 | Check churn risk — find files in `src/config` modified within 90 days | Not modified in 90 days. | Stable. |
+
+**Verdict**: **Dismissed**. High fan-in is expected and harmless for a read-only config module. No logic, no mutation, no churn. The scanner flags structural coupling but the semantics show this is a stable leaf — not a refactoring target.
+
+---
+
+### Example 3: Uncertain — god function with partial evidence
+
+**Finding**: `findings.json` reports `god-function` for `processOrder` in `src/orders/handler.ts` (line 88, 120 statements, cognitive complexity 35).
+
+| Step | What was done | Result | Decision |
+|------|--------------|--------|----------|
+| 1 | Read the function body (line 88-210) | Large function with validation, discount calculation, inventory check, payment call, email dispatch. Multiple concerns interleaved. | Confirms size and complexity. |
+| 2 | Incoming call hierarchy for `processOrder` | 3 callers: `POST /orders` route handler, a batch job, and 1 test. | Moderate blast radius. |
+| 3 | Outgoing call hierarchy for `processOrder` | Calls 8 functions across 5 files: validateOrder, calcDiscount, checkInventory, chargePayment, sendConfirmation, logAudit, updateMetrics, notifyWarehouse. | Orchestrates many side effects. |
+| 4 | Find references filtered to test directories | 1 test reference — a single happy-path integration test. No edge-case coverage. | Sparse test coverage. |
+
+**Verdict**: **Uncertain** (medium confidence). The function is objectively large and complex, and orchestrates many side effects — consistent with a god function. However, it may be intentionally serving as a transaction script (single orchestration point for atomicity). Cannot confirm it's harmful without knowing:
+- Whether the callers expect atomic all-or-nothing behavior
+- Whether extracting sub-steps would break transaction boundaries
+- Whether the team considers this an acceptable orchestration pattern
+
+**Recommendation**: flag for team review. If refactoring, extract pure computation helpers (validation, discount) first — those are side-effect-free and safe. Defer side-effect orchestration changes until transaction semantics are clarified.