| name | octocode-engineer |
| description | System-engineering skill for codebase understanding, bug investigation, refactors, PR safety, architecture review, and RFC validation. Enforces Clean Architecture and Clean Code with AST, LSP, and scanner evidence. Produces a flows / boundaries / architecture-health artifact with file:line citations before recommending action. |
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 index
| Situation | Reference |
|---|
| Tool workflows, research recipes | tool-workflows.md |
| Scanner flags, thresholds, scope syntax, exit codes | cli-reference.md |
| Reading scan artifacts | output-files.md |
| AST presets, pattern syntax, Python kinds | ast-reference.md |
| Confirming / dismissing a finding | validation-playbooks.md |
| Detector catalog, metrics, severities | quality-indicators.md |
| How to present findings | output-format.md |
| eslint, tsc, knip, ruff, mypy | externals.md |
Operating contract (agent view)
Every non-trivial task MUST satisfy this contract:
- Scope — restate the goal and constraints in one line before touching tools.
- Lenses — apply both required lenses defined in §Clean Architecture & Clean Code: the five Clean-Architecture principles and the six analytic dimensions.
- 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.
- Artifact — produce the understanding artifact (§Required output) before recommending action.
- Gates — stop at every hard gate in §User-Ask Gates.
- 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 formal RFCs with migration strategy, pair with 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
- Dependency rule — source code dependencies point inward. Domain never imports infrastructure/UI; use cases never import frameworks.
- Layer boundaries — entities → use cases → interface adapters → frameworks & drivers. Concerns stay in their layer.
- Stable abstractions — volatile details depend on stable policy, never the reverse.
- Boundary ownership — every cross-boundary call goes through an explicit port (interface/DTO). Implementation types do not leak.
- 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 | localSearchCode(entry,lineHint) → lspCallHierarchy incoming/outgoing → scripts/run.js flow/graph on hot paths | hidden event jumps; unenumerable middleware chains; untested error branches |
| 2 | Duplication — same logic in two places drifts | scanner (duplicate-function-body, duplicate-flow-structure, similar-function-body) → scripts/ast/search.js --pattern → lspFindReferences on canonical version | two sources of truth; drifting copies; per-caller reinvention |
| 3 | Types — in-process contracts | lspGotoDefinition on boundary params → lspFindReferences on type → scripts/ast/search.js presets (any-type, type-assertion, non-null-assertion) → scanner (unsafe-any, type-assertion-escape, narrowable-type) | any/unknown at public boundary; casts silencing compiler; always-populated "optional" fields |
| 4 | Protocols & schemas — wire contracts (HTTP/gRPC/GraphQL/SQL/events/config) | localFindFiles on *.proto, *.graphql, *.sql, openapi*, schema*, migrations/* → localGetFileContent → lspFindReferences on generated types → githubSearchPullRequests for external changes | schema drift; implicit required fields; defaults in code not schema; version bumps without compat windows; null/missing/empty ambiguity |
| 5 | Data flows — state, ownership, mutation | schema + repository/DAO → lspFindReferences on write fns (save, update, insert, publish) → scripts/run.js graph/flow on write paths → scripts/ast/search.js --kind on mutations | multi-writers on one field; read-your-writes across async; cache/write races; write paths bypassing validator; projections without consistency guarantees |
| 6 | Execution — runtime (sync/async, I/O, retries, timeouts, startup/shutdown, lifecycles) | scripts/ast/search.js presets (async-function, await-in-loop, sync-io, promise-all) → scanner (await-in-loop, sync-io, uncleared-timer, unbounded-collection, startup-risk-hub, listener-leak-risk) → lspCallHierarchy on hot path → tests/benchmarks | await in tight loops; sync I/O on request path; timers/listeners without lifecycle; startup assuming init order; retries without backoff/idempotency |
Clean Code — what to enforce, how to verify
- Names reveal intent — symbols describe what, not how.
- Small, single-purpose functions — one level of abstraction; short; ≤ ~3 params.
- No dead or duplicated logic — every branch reachable; each pattern lives in one place.
- Fail loudly, never silently — no empty catches, no swallowed errors, no bare
except.
- Types are precise at boundaries — no
any / no bare except / no unchecked casts at contracts.
- Comments explain why, not what — if the comment restates the code, delete one.
| Rule | Tool | Preset / signal |
|---|
| Small functions | scripts/run.js | god-function, cognitive-complexity, halstead-effort, excessive-parameters |
| Duplication | scripts/run.js | duplicate-function-body, duplicate-flow-structure, similar-function-body |
| Silent failures | scripts/ast/search.js | --preset empty-catch, --preset py-bare-except, --preset py-pass-except, --preset catch-rethrow |
| Loose types | scripts/ast/search.js | --preset any-type, --preset type-assertion, --preset non-null-assertion |
| Intent-revealing names | code read + lspFindReferences | widely-used cryptic symbols, abbreviations that spread |
| Dead / unreachable | scanner + knip | dead-export, dead-file, unused-import, unused-npm-dependency |
For the full detector catalog, metric definitions, and severity rubric, see quality-indicators.md.
Required output: understanding artifact
Produce before recommending action. required sections always appear (use N/A + reason if not applicable); applicable sections appear only when the task touches that surface. Keep each section ≤ 2 min read.
| # | Section | When | Source dimensions |
|---|
| 1 | System summary — what it does, who consumes it, invariants | required | — |
| 2 | Control flows — numbered call paths, each step cited file:line | required | Flows |
| 3 | Data flows — writers, readers, transaction boundaries, caches per entity | applicable (stateful tasks) | Data flows |
| 4 | Types & protocols — boundary DTOs/schemas/wire contracts, compatibility posture | applicable (contract tasks) | Types, Protocols & schemas |
| 5 | Boundaries & ownership — module ownership, ports, contract tests | required | — |
| 6 | Duplication inventory — top near-clones and the missing abstraction | applicable (refactor / quality) | Duplication |
| 7 | Execution profile — hot paths, async/sync posture, retry/timeout/lifecycle, runtime risks | applicable (perf / reliability) | Execution |
| 8 | Architecture health — one line per principle and per dimension, with `confirmed | likely | uncertain` + source |
| 9 | Clean-code hotspots — top AST/scanner findings worth fixing, cited file:line | applicable (quality work) | — |
| 10 | Next step — one sentence | required | — |
Trivial tasks: section 10 + verification only (see §Trivial vs. non-trivial). Section ordering, phrasing, examples: output-format.md.
If the task involves a change, also include:
- Change flow — the specific call path the change traverses. (required for any change)
- Data-flow impact — entities read/written and how transaction/cache semantics are preserved. (required if section 3 applied)
- Contract impact — types/schemas/protocols touched and compatibility posture (backwards-compatible / breaking-with-migration / additive-only). (required if section 4 applied)
- Blast radius — callers and consumers touched, from
lspFindReferences, labeled by layer. (required for any change with consumers)
- Risk vector — which clean-architecture principles and which analytic dimensions the change stresses, and how each is preserved. (required for any change)
Artifact self-check — before closing
A good artifact answers all of: ownership/boundary; blast radius (consumers, layers); contract safety (types/schemas/protocols); local vs structural vs architectural; build/config involvement; reliability under failure/retry/concurrency; observability sufficiency; rollout/migration reversibility; folder bloat and file/folder naming fitness; modularity trajectory; documented assumptions; safest next move. If the answer only explains one file, it is usually incomplete.
Tool Families And Their Jobs
1. Local Octocode tools
First tools for workspace mapping — not a fallback.
| Tool | Use it for |
|---|
localViewStructure | Package/module layout, folder depth, source spread |
localFindFiles | Large files, recent churn, suspicious filenames, likely hotspots |
localSearchCode | Fast discovery, symbol search, text patterns, and lineHint for LSP |
localGetFileContent | Final code reading after you know what you are looking at |
Rules:
- Do not start with a full-file read when discovery tools can narrow the target first.
- When
localSearchCode returns zero matches: (1) widen the pattern (drop regex meta-chars, try a substring), (2) fall back to localFindFiles on likely filename patterns, (3) retry with the literal symbol name. Only after that may you broaden to localViewStructure for layout reconnaissance.
2. LSP tools
Use LSP tools to understand real semantic relationships. lineHint rule stated in §Quick decision cheatsheet — applies to every entry below.
| Tool | Use it for |
|---|
lspGotoDefinition | What symbol is this really? |
lspFindReferences | Blast radius, all usages, dead-code checks (types, vars, anything) |
lspCallHierarchy | Function call flow only: incoming callers and outgoing callees |
3. AST tools — structural proof
Authoritative proof for code-shape, redundancy, and smell claims; use when text search is too weak.
| Script | Role | Example invocation |
|---|
scripts/ast/search.js | Live ast-grep search on current source — authoritative | node scripts/ast/search.js --preset empty-catch --root ./src |
scripts/ast/search.js | Project-specific structural claim | node scripts/ast/search.js --pattern 'if ($C) { return $V }' --json |
scripts/ast/tree-search.js | Fast triage over cached AST trees from a prior scan | node scripts/ast/tree-search.js -i .octocode/scan -k function_declaration --limit 25 |
Rules:
- Presets cover the common clean-code rules; list them with
node scripts/ast/search.js --list-presets.
- Python presets are prefixed
py- (e.g. py-bare-except, py-mutable-default).
- Use
tree-search.js first to narrow, then search.js to confirm on live code.
- If a structural claim matters to a decision, confirm it with AST before presenting it as fact.
- Pair every match with its
file:line in the summary.
- For preset catalog, pattern syntax, and Python node kinds, see ast-reference.md.
4. Scanner — architecture and flow
Use scripts/run.js when the question is bigger than one symbol or one file. It surfaces dependency cycles, chokepoints, coupling pressure, layer violations, dead-code clusters, security sinks, test gaps, and hot paths — the issues local reading misses.
| Script | Role | Example invocation |
|---|
scripts/run.js | Default scoped scan | node scripts/run.js --scope=packages/my-pkg |
scripts/run.js --graph | Architecture graph (cycles, SDP, coupling) | node scripts/run.js --graph --out .octocode/scan/scan.json |
scripts/run.js --json | Machine-readable findings | node scripts/run.js --json --out .octocode/scan/scan.json |
Use scanner output to reason about: where change risk concentrates, whether a module is structurally unhealthy, whether a local fix ignores a broader architectural problem, which area to refactor first. Flags, thresholds, scope syntax, and exit codes: cli-reference.md. Reading the scan artifacts: output-files.md.
First-run install. Scripts auto-install native deps (tree-search.js needs none) using the detected package manager (pnpm-lock.yaml → pnpm, yarn.lock → yarn, else npm); on failure they exit non-zero with the manual command. Opt out with OCTOCODE_NO_AUTO_INSTALL=1.
Invoking the scripts. Skill is private: true with no bin — npx octocode-engineer-* is invalid. npx applies only to externals in externals.md. Forms:
| Form | Example | When |
|---|
| Absolute path | node <SKILL_DIR>/scripts/run.js --scope=packages/my-pkg | From any cwd (default) |
yarn alias | cd <SKILL_DIR> && yarn analyze|analyze:full|analyze:graph|analyze:json | Idiomatic in-skill shortcut |
yarn alias (AST) | cd <SKILL_DIR> && yarn search|search:json|search:presets|search:trees|search:trees:json | AST scripts |
| Raw node (cwd-local) | cd <SKILL_DIR> && node scripts/run.js [flags] | When you need flags not covered by an alias |
Full flag catalog + exit codes: cli-reference.md.
Cost. Prefer --scope=<path> over full-repo; reuse existing artifacts when they answer the question; on staleness re-run only the minimal scope.
5. Cross-cutting quality checks
The Clean-Architecture principles and the six analytic dimensions already cover naming, cohesion, duplication, layering, contracts, types, data flow, and execution. Use this section only for concerns not directly named there:
| Check | Focus |
|---|
| Reliability & resilience | retry policy, timeout handling, failure isolation, idempotency, fallback behavior |
| Observability & operability | logging quality, metric/tracing coverage, diagnosability, alert/runbook readiness |
| Rollout & migration | feature flags, backward-compatibility windows, rollback path, migration sequencing |
| Build & config | ESM/CJS mismatch, module resolution, script wiring, runtime assumptions |
| Structure health | leaf-folder bloat, vague shared/helper buckets, depth balance, source spread, file and folder naming consistency for the project |
| Docs | whether critical assumptions, contracts, flows, setup, migrations, and risks are documented |
| CSS hygiene | selector scope, token reuse, naming clarity, dead styles (when frontend styling is touched) |
knip | unused exports, files, dependencies, dead integration edges (run on refactors) |
Skip items that do not apply. For concrete npx commands for eslint, tsc, knip, stylelint, type-coverage, dep-cruiser, ruff, mypy, and related externals, see externals.md — ask before running.
6. Execution discipline
- Per-step: declare the next tool and why it is the cheapest proof; separate facts from inference; carry forward concrete identifiers (
lineHint, paths, symbols); verify explicitly after edits.
- Status updates: say what was checked and what remains — no vague progress, no "looks fine" without evidence, no switching to edits without a short flow summary.
- Depth control: mark
N/A on irrelevant checks; go deeper only where risk/uncertainty is meaningful; pick the lightest evidence path.
- Token efficiency: one investigation thread at a time; reference prior checkpoints instead of restating evidence; stop research when confidence is sufficient; summarize findings as issue → evidence → impact → action.
- Task tracking: use todos when the work spans research → plan → implement → verify → docs. Track investigation, decision, implementation, verification, docs follow-up.
Default Working Order
Non-trivial tasks follow this arc (recommended, not mandatory): clarify the question → create todos if multi-step → map layout with local tools → trace symbols with LSP → identify critical and failure paths → validate structure with AST → check architecture/contracts/reliability/build/docs with the scanner → read the code in context → validate design docs or RFCs against current flows and contracts → apply both lenses (confirmed|likely|uncertain with evidence) → produce the artifact → pause at any hard gate → decide to explain, plan, or edit.
Task shapes
Same working order; emphasis differs:
| Task | Weight on | Notes |
|---|
| Code understanding | steps 3–8 (layout → LSP → AST → scoped scanner → read) | Deliverable is the artifact. |
| Bug fixing | Flows + Execution from failing behavior to entry point; adjacent error/retry/contract risk | Fix the smallest layer that solves the root cause; escalate via Smallest-fix vs. safest-fix gate when systemic. |
| Refactor | blast radius (lspFindReferences), scoped scan, duplication inventory, then plan | Prefer extracting modules, clarifying contracts, simplifying flows over cosmetic reshuffling. Verify per batch. |
| Architecture review | scanner --graph first, then LSP on candidate modules, then read representatives | Report both local and system-level causes. |
| RFC / design validation | map each claim to code ownership; verify flow, contract, and architecture alignment | Mark claims `confirmed |
Before / During / After A Change
Operational actions per phase (investigation substance = lenses + artifact):
Before
- Produce the understanding artifact.
- Map design-doc / RFC claims to concrete code ownership when one exists.
- Look for an existing local pattern before inventing a new one.
During
- Keep edits in the smallest responsible layer; preserve boundaries unless the plan intentionally changes them.
- Maintain contract/protocol compatibility unless an explicit migration is in scope.
- If root cause turns out structural mid-task, stop and hit the Smallest-fix vs. safest-fix gate instead of continuing with a cosmetic patch.
After
- Run tests, lint, and build/type-check.
- Re-check changed symbols with LSP after renames/moves; run a scoped scanner pass for non-trivial changes.
- Run
knip when the refactor may leave dead artifacts; CSS checks when styles changed.
- Re-validate the artifact's dimensions against the final implementation; note any remaining architectural risk even if the code now works.
- Sync docs / RFC sections touched by the change.
Confidence Rules
| Level | Meaning | Example |
|---|
confirmed | ≥2 approaches agree, or one authoritative source | AST proves empty catch + LSP shows function widely used |
likely | good evidence, one angle still missing | scanner hotspot agrees with code shape, blast radius unverified |
uncertain | conflicting / incomplete / single weak source | text search suggests dead code, LSP unavailable |
Evidence conflict resolution
When sources disagree on a claim that affects a decision, prefer the source whose domain it is, then re-verify the weaker source:
| Claim type | Authoritative source | Corroborator |
|---|
| Symbol identity, references, callers/callees | LSP (lspGotoDefinition, lspFindReferences, lspCallHierarchy) | AST + code read |
Structural shape (empty catch, any usage, nested ternary, preset match) | AST (scripts/ast/search.js) | scanner + code read |
| Runtime behavior and side effects | targeted code read + tests | AST + scanner |
| Architecture pressure (coupling, cycles, SDP, hot paths) | scanner (scripts/run.js) | LSP references + code read |
| Contract/schema shape at a boundary | the schema/IDL file itself + lspGotoDefinition | references to generated types |
If the authoritative source contradicts a weaker one, mark the weaker one as "re-verify" in the artifact and note the resolution. Never present conflicting evidence as resolved without a recorded tiebreak.
For step-by-step playbooks that confirm or dismiss a finding (dead code, duplicate, unsafe any, layer violation, cycle, etc.), see validation-playbooks.md.
User-Ask Gates
A gate is a hard stop — do not proceed without the user's explicit decision.
Hard gates (always stop and ask)
State situation in ≤3 lines, list options, name tradeoff, recommend one.
- Ambiguous scope — the task has more than one reasonable interpretation and the right one changes the plan.
Ambiguous: "fix the login bug". Unambiguous: "fix 500 on /api/login when password field is empty".
- Public contract change — a public API, exported symbol, event schema, DB schema, CLI flag, or wire protocol would change.
Fires: renaming an exported function with external consumers. Does not fire: renaming a private helper with no references.
- Cross-layer/cross-package change — the fix requires editing more than one layer or crosses a workspace boundary.
Fires: bug fix needs changes in
packages/domain AND packages/http-adapter. Does not fire: edit contained in one package.
- Dependency-rule violation required — the cleanest fix would break the dependency rule, break a boundary, or introduce a new cycle.
Fires: domain module would need to import the HTTP adapter. Does not fire: adapter importing domain (correct direction).
- Destructive or irreversible action — delete/rename shared files, drop tables, reset branches, force-push, publish packages, send messages/PRs on the user's behalf.
Fires:
git reset --hard, rm -rf, publishing an npm version. Does not fire: local file edits on a feature branch.
- Blast radius > ~5 consumers —
lspFindReferences returns many callers and the change alters their behavior.
Fires: changing a utility called by 20 files. Does not fire: changing a helper with 2 callers, both of which are co-edited.
- Two refinement attempts failed — same approach tried twice and the evidence still doesn't line up.
Fires: two different search patterns both return empty for a symbol you expected. Does not fire: one failed attempt with a clear next angle.
- Missing gate prerequisite — no tests exist for the area, no owner documented, no schema available, and the change needs one.
Fires: user asks for a refactor of untested legacy code. Does not fire: tests exist and cover the change surface.
- Conflicting evidence — authoritative and corroborating sources (see §Evidence conflict resolution) disagree on a claim that matters to the decision.
Fires: LSP says 0 references, AST shows an import of the symbol. Does not fire: scanner is noisy but LSP is clear.
- Smallest-fix vs. safest-fix conflict — a narrow patch would work but the root cause is structural.
Fires: bug can be fixed by adding a null check but the real cause is a missing contract between two layers. Does not fire: the narrow patch IS the right layer.
Soft gates (ask if material)
Ask when the decision materially changes the outcome; otherwise proceed and note the assumption.
- Multiple reasonable architectures exist for a greenfield area.
- Framework / library choice where the project has no established pattern.
- Rollout strategy (feature flag vs direct deploy) for a behavior change.
- Migration sequencing when old and new consumers coexist.
- Whether to fix adjacent smells discovered mid-task or log them as follow-ups.
Ask template
Gate: <what triggered it, 1 line>
Options:
-
— tradeoff
-
— tradeoff
Recommendation: <A or B, 1 line why>
Blocking:
Keep it short. The user should be able to respond in one sentence. If the user picks an option you did not recommend, record the decision and the stated reason in the Architecture health / Risk vector sections and proceed without re-asking. Do not argue against a decided option — raise residual risks once, then execute.
Gate discipline
- Do not ask when the answer is obvious from the code, CLAUDE.md, or prior context.
- Do not silently continue past a hard gate because "it seemed fine" — that is the failure gates prevent.
- If a gate fires mid-implementation, stop at a clean checkpoint (commit if appropriate, revert if not) and ask.
- After a decision, record it in the artifact so future steps carry it forward.
- Gates bind regardless of fallback state. If an Octocode tool is unavailable and you are in §Fallback Mode, gates still fire on the same conditions; lower confidence does not weaken the rule.
Hard Rules (recap)
Non-negotiable guardrails beyond the §Operating contract (which already binds gates and tool universe):
- Do not present raw detector output as unquestioned fact.
- Do not use
lspCallHierarchy on non-function symbols — use lspFindReferences instead.
- Do not judge shared modules from one file read alone.
- Do not claim design/RFC compliance without claim-by-claim evidence.
- Do not ignore build/config evidence when runtime behavior may depend on it.
- Do not apply a quick patch when the real issue is contracts, boundaries, duplication, or architecture — hit the Smallest-fix vs. safest-fix gate.
- Check blast radius before changing shared symbols.
- Re-sync docs/RFCs when implementation changes architecture, contracts, rollout assumptions, or constraints.
Fallback Mode
Fallback applies only when an Octocode tool is truly unavailable — not registered, unreachable, or returning hard errors. A warning inside a successful response is not a failure.
If unavailable: continue with AST tools and the scanner; rely more on local search and direct code reading within this skill's tool universe; reduce confidence on semantic claims; label proven vs. inferred.
If degraded but completed: treat the response as valid; on empty/wrong results, retry with a simpler input (drop regex meta-characters, switch to literal search, narrow the path). Do not switch to native Claude Code tools — that leaves the skill's evidence model.
Companion Skill
Pair with the RFC skill when architecture options, trade-offs, or migration strategy need a formal proposal before coding:
