core-coding

name	core-coding
description	Activate when the turn's deliverable is source, test, code analysis, or config files — editing or creating code. Provides the Research → Strategy → Execution workflow, the complexity budget, and specialised deep-dive companions (testing, debug, refactor, review).
user-invocable	false

Skill: core-coding

Follow Research → Strategy → Execution for every coding task.

Deep-Dive Companions

When the current step matches a trigger below, Read the named companion from this skill's directory (the activation header lists the directory path and all companion paths). Companions are not pre-loaded — pull them on demand.

Trigger	Companion
About to write, modify, or audit a test	workflows/testing.md
Something is broken locally (build error, failing test, wrong output) and root cause is unclear	workflows/debug.md
A running or deployed system is failing and you can't reproduce it locally — crash/core dump, memory/heap dump, OOM, or diagnosis via kubectl / Grafana / Prometheus / Elasticsearch	workflows/observability.md (helper scripts in tools/)
Code structure needs improvement (complexity, duplication)	workflows/refactor.md
Reviewing changes for correctness, security, or quality	workflows/review.md
Code touches user input, auth, file I/O, or sensitive data	workflows/review.md (security audit checklist)
First substantial edit in a project — identify the language from the manifest	languages/<lang>.md (one of python, typescript, go, rust, java, ruby, php)

Everything in this skill and its companions is a default: explicit user instructions and project guidelines (CLAUDE.md, AGENTS.md, custom skills, project files) override it wherever they conflict. Core guidance fills in the gaps.

PHASE 1: RESEARCH & DISCOVERY

Follow the Scientific Method: form a hypothesis → test it → analyze results. Avoid random changes.

a. High-Level Reconnaissance:

• Use LS with limited depth for initial structure mapping.
• Identify: source directories, test directories, config files, entry points, and utility modules.
• Skip if you already know specific file paths — use targeted Glob instead.

b. Targeted Architecture Discovery:

• Use Glob and Grep in parallel to map file structures, existing patterns, and utility functions.
• Use Grep with specific regex and file_pattern to minimize noise.
• Issue several Read calls in parallel when gathering context from related files.
• Before modifying any existing function, method, or class signature: use LspFindReferences if LSP is available, otherwise Grep. Find all call sites and include updating them in your plan.
• Before moving or removing any file or directory: use Grep to find all imports and path references first.

PHASE 2: STRATEGY

c. Formulate a Grounded Plan:

• Language & Framework Idioms: identify the language, framework, and version from dependency files and existing code. Apply idiomatic conventions — a pattern correct in one language may be an anti-pattern in another. Never add attributes or behavior to objects owned by a library; wrap them in a type you own.
• Pattern Matching: strategy MUST match existing project guidelines and patterns exactly. New code should look as though written by the original author.
• Reuse existing helpers before creating new ones.
• Apply SOLID and DRY. One reason to change per function and class.
• No magic numbers, strings, or unexplained constants. Name every value that carries meaning.

d. Complexity Budget (default hard limits):

Exceeding a limit is a design defect — restructure before continuing. Project guidelines may set different limits; they win.

Metric	Limit	Remedy when exceeded
Cyclomatic complexity	≤ 10 per function	Extract sub-functions
Cognitive complexity	≤ 15 per function	Flatten nesting, add guard clauses
Nesting depth	≤ 2 levels	Invert conditionals; use early returns
Function length	≤ 30 lines	Extract cohesive blocks into named helpers
Parameters per function	≤ 4	Group related params into a data object

Guard clause mandate: invert conditions to exit early; the happy path must never be the deepest else.

Boolean parameter prohibition: a boolean parameter = two functions. Split them.

God Class/Function prohibition: one reason to change per class/function. If you can't name the extracted piece, it's not a coherent abstraction.

e. Testing Strategy: define verification before writing code. For test-first methodology, Read workflows/testing.md.

• New behavior: identify the failing test (RED) first.
• Bug fix: identify the minimal reproduction test first.
• Refactoring: confirm existing tests pass as baseline before touching anything.

PHASE 3: EXECUTION (Plan → Act → Validate)

f. Act (Surgical Implementation):

• Minimal, precise edits only. One logical change per task (atomic). Use existing libraries and patterns.
• Keep functions within the Complexity Budget. Place helpers below callers.
• Strangler Pattern: when replacing a component, keep codebase runnable at every step: new alongside old → update references → remove old.
• Out-of-scope structural problems: report them. If they block this task, Read workflows/refactor.md and address atomically.
• Code Smell Reporting: report poorly structured code you encounter — don't silently fix it.
• Docs: keep documentation in sync; remove deprecated references.

g. Validate (Zero-Regression):

• Validation is the only path to finality.
• Bug fixes: reproduce before fixing. If root cause is unclear, Read workflows/debug.md.
• After any change: run tests, linters, and type-checkers.
• If validation fails, diagnose before retrying.

h. Synthesis:

For user-facing output (docs, error messages, commit messages), apply writing quality standards from core-writing.