octocode-engineer

What this skill does

# Octocode Engineer

Understand, change, and verify a codebase with system awareness. Single-file reading misses root causes — they live in boundaries, flow ownership, contracts, data paths, and runtime assumptions. This skill makes those visible before you act, and keeps them verified after.

## What you get (user view)

A structured **understanding artifact**, grounded in evidence, every claim cited `file:line`:

- **System summary** (what/who/invariants) · **Control flows** (numbered call paths) · **Data flows** (writers/readers/txn/cache per entity) · **Types & protocols** (DTOs, schemas, wire contracts, compat)
- **Boundaries & ownership** (owners, ports, contract tests) · **Structure health** (folder bloat, file/folder naming, project-fit) · **Duplication inventory** (near-clones, missing abstraction) · **Execution profile** (hot paths, async/sync, retries/timeouts/lifecycles)
- **Architecture health** (per-principle + per-dimension, `confirmed|likely|uncertain`) · **Clean-code hotspots** · **Next step** (1 sentence)

For a change: change flow, data-flow impact, contract impact, blast radius, risk vector. **Safety built in** — hard gates stop for your decision before public-contract changes, cross-layer edits, destructive actions, or large blast radius.

## How to invoke (user view)

Ask in natural language. The skill activates on phrases like: *"understand this codebase"*, *"deep-dive this feature"*, *"review the architecture of X"*, *"why is this slow / flaky / coupled?"*, *"is this PR safe?"*, *"what breaks if I change Y?"*, *"prepare to refactor Z"*, *"validate this RFC against the code"*.

## Quick decision cheatsheet (agent view)

Use this first to pick the cheapest proof path. Every LSP call needs a `lineHint` from `localSearchCode` — **never guess**.

| Question | Tool chain |
|---|---|
| Where is X defined? | `localSearchCode(X)` → `lspGotoDefinition(lineHint=N)` |
| Who calls function X? | `localSearchCode(X)` → `lspCallHierarchy(incoming, lineHint=N)` |
| What does X call? | `localSearchCode(X)` → `lspCallHierarchy(outgoing, lineHint=N)` |
| All usages of a type / var / non-function X? | `localSearchCode(X)` → `lspFindReferences(lineHint=N)` |
| Is this pattern duplicated? | `scripts/ast/search.js --pattern` → scanner `duplicate-*` findings |
| Is this shape an antipattern? | `scripts/ast/search.js --preset <name>` (list: `--list-presets`) |
| Is this module structurally unhealthy? | `scripts/run.js --graph --scope=<path>` → read `scan.json` |
| Is the project structure healthy? | `localViewStructure` + `localFindFiles` → `scripts/run.js --scope=<path> --graph` → inspect `qualityRating` folder/naming/consistency signals + `mega-folder` findings |
| Which layer/boundary does this cross? | Scanner layer output + `lspGotoDefinition` across packages |
| What breaks if I change Y? | `lspFindReferences(Y)` → label consumers by layer |
| Find files by name / churn / size | `localFindFiles` |
| Read implementation (last resort) | `localGetFileContent` with `matchString` |

For longer research recipes and end-to-end tool sequences, see [tool-workflows.md](./references/tool-workflows.md).

### References index

| Situation | Reference |
|---|---|
| Tool workflows, research recipes | [tool-workflows.md](./references/tool-workflows.md) |
| Scanner flags, thresholds, scope syntax, exit codes | [cli-reference.md](./references/cli-reference.md) |
| Reading scan artifacts | [output-files.md](./references/output-files.md) |
| AST presets, pattern syntax, Python kinds | [ast-reference.md](./references/ast-reference.md) |
| Confirming / dismissing a finding | [validation-playbooks.md](./references/validation-playbooks.md) |
| Detector catalog, metrics, severities | [quality-indicators.md](./references/quality-indicators.md) |
| How to present findings | [output-format.md](./references/output-format.md) |
| eslint, tsc, knip, ruff, mypy | [externals.md](./references/externals.md) |

## Operating contract (agent view)

Every **non-trivial** task MUST satisfy this contract:

1. **Scope** — restate the goal and constraints in one line before touching tools.
2. **Lenses** — apply both required lenses defined in §Clean Architecture & Clean Code: the five Clean-Architecture principles and the six analytic dimensions.
3. **Evidence** — prove every architectural or code-quality claim with at least one of: Octocode local tools, LSP, AST, scanner. Mark confidence (`confirmed|likely|uncertain`) with source.
4. **Artifact** — produce the understanding artifact (§Required output) before recommending action.
5. **Gates** — stop at every hard gate in §User-Ask Gates.
6. **Tool universe** — never fall back to native Claude Code search tools (`Grep`, `Glob`, `Read`) while Octocode MCP is registered. A warning inside a successful Octocode response is not a failure; see §Fallback Mode for the only legitimate fallback conditions.

## When To Use It

Use when the user asks to **understand** a codebase/feature end-to-end, **change** unclear/shared/cross-file code, **review** quality/architecture/tech-debt/dead-code/security/build issues, or **decide** architecture and validate RFCs against real behavior. Any language; strongest on Node/TypeScript and Python. For architecture options, trade-offs, or migration strategy that need a formal proposal before coding, pair with [octocode-rfc-generator](https://skills.sh/bgauryy/octocode-mcp/octocode-rfc-generator).

## Trivial vs. non-trivial — when the contract binds

The contract, lenses, and artifact apply to **non-trivial** tasks. A task is **trivial** only when ALL hold: single file; no public/exported symbol touched; 0 consumers (per `lspFindReferences`) or behavior-preserving for all; no contract/schema/protocol/config/migration touched; ≤ ~20 lines; no cross-layer/cross-package edit. Otherwise non-trivial (default on doubt). Trivial tasks: deliver the one-line next step + verification only.

## Clean Architecture & Clean Code (Required Lenses)

Non-trivial investigations MUST go through both lenses. Prove every claim with the listed tools — no unevidenced architectural or code-quality facts.

### Clean Architecture — what to enforce, how to verify

1. **Dependency rule** — source code dependencies point inward. Domain never imports infrastructure/UI; use cases never import frameworks.
2. **Layer boundaries** — entities → use cases → interface adapters → frameworks & drivers. Concerns stay in their layer.
3. **Stable abstractions** — volatile details depend on stable policy, never the reverse.
4. **Boundary ownership** — every cross-boundary call goes through an explicit port (interface/DTO). Implementation types do not leak.
5. **Single responsibility per module** — one reason to change; one axis of volatility.

| Principle | Tool | Evidence to collect |
|-----------|------|---------------------|
| Dependency rule | `scripts/run.js --graph` + `lspFindReferences` | layer-violation / SDP findings; inward-pointing edges only |
| Layer boundaries | `localSearchCode` on import lines + scanner layer output | UI→DB, domain→HTTP, adapter→framework leaks |
| Stable abstractions | scanner `distance-from-main-sequence` | concrete high-fan-in modules, unstable abstractions |
| Boundary ownership | `lspGotoDefinition` across package boundaries | types crossing boundaries without a port |
| Single responsibility | scanner + `scripts/ast/search.js` (`--preset class-declaration`, `god-function`) | god modules, multi-purpose classes, wide exports |

### Architect's analytic dimensions

Cover all six on a full review; on a scoped task, cover those the change touches and mark the rest `N/A` with a one-line reason (`N/A` is a claim, not silence). Mapping to artifact sections is encoded in §Required output. On a change, state which dimensions it stresses — that is the risk vector.

| # | Dimension | Verify | Anti-patterns |
|---|-----------|--------|---------------|
| 1 | **Flows** — entry → collaborators → side effects → return/emit | `localS