Coding

Coding

Discover before assuming. Verify before shipping.

Every coding failure traces to one of three root causes:

• Acting on assumptions instead of evidence
• Skipping verification before declaring done
• Burning context on noise instead of signal

This skill prevents all three.

Core Loop

Every task follows this sequence. No exceptions.

Discover → Plan → Implement → Verify

• Discover: Read the code. Trace dependencies. Understand what exists.
• Plan: Define success criteria. Scope the change. Identify risks.
• Implement: Write minimal code. Work incrementally. Stay simple.
• Verify: Run tests. Validate behavior. Confirm requirements met.

The loop exists because each step prevents a category of failure. Skipping discovery causes wrong assumptions. Skipping planning causes scope creep. Skipping verification ships broken code.

The threshold: if you can describe the diff in one sentence, skip planning. Otherwise, plan first.

The Assumption Interrupt

This pattern must become automatic in your reasoning:

<cognitive-interrupt> WHENEVER you find yourself:

• Using a method/type/interface without having read its definition
• Using words like "probably", "likely", "should have", "typically"
• Recalling an API from memory instead of reading current source
• Planning changes to code you haven't read in this session
• Assuming a method signature, type structure, or interface shape

STOP. Ask yourself: 1. "Do I have evidence in current context that this exists?" 2. "Have I actually read this code, or am I assuming?" 3. If no evidence exists → VERIFY before proceeding.

Every unverified assumption is a potential compile failure, runtime bug, or behavioral regression. </cognitive-interrupt>

<assumption-markers> These words in your reasoning are RED FLAGS:

• "probably" → You don't know. Read it.
• "likely" → You're guessing. Check it.
• "should have" → Assumption. Verify it.
• "typically" → General knowledge, not this codebase. Read it.
• "I remember" → Memory is unreliable. Read it now.
• "usually" → This codebase may differ. Check it.

</assumption-markers>

Discovery Protocol

Before planning or implementing, map the territory.

<discovery-protocol>

1. Map the Area

• Read files in the target directory
• Understand package/module structure
• Identify related files and established patterns

2. Trace Dependencies

• What does this code import/use?
• What imports/uses this code?
• Search for usages: grep for function/type names

3. Verify Contracts

• Read actual method signatures — don't assume
• Read interface and type definitions
• For third-party code: read vendored source OR fetch docs
• Verify: function exists, signature matches, types correct

4. Assess Impact

• Who calls what you're modifying?
• What tests cover this code?
• What might break?

</discovery-protocol>

Discovery is cheap. Debugging wrong assumptions is expensive.

Planning Discipline

Before writing code, establish:

<planning-checklist>

• Success criteria — What does "done" look like? Define measurable outcomes, not vague goals.

Bad: "improve the API" Good: "add pagination to /api/users, 100 items/page, response under 200ms"

• Scope — What files change? What stays untouched? Explicitly bound the change. Don't

"helpfully improve" adjacent code.

• Risks — What could break? If modifying shared code, trace all callers first.

• Verification strategy — How will you prove it works? Tests > manual check > "it looks

right". Define this BEFORE writing any implementation code.

</planning-checklist>

Implementation Discipline

Work Incrementally

Don't one-shot complex features.

<incremental-rules>

• One logical change at a time
• Verify each change works before moving to the next
• If a change touches 5+ files, break it into smaller steps
• Leave the codebase in a clean, working state at every step
• For multi-step tasks: track completed steps and remaining work

</incremental-rules>

Write Simple Code

Agents overcomplicate by default. Actively resist this.

<simplicity-rules>

• Prefer functions over classes when either works
• Avoid inheritance unless the problem demands it
• Prefer explicit over implicit — no magic
• Keep permission checks and validation visible at the call site, not hidden in middleware the

next reader won't find

• Use descriptive names — longer is better than ambiguous
• Do the simplest thing that works, then optimize if measured performance requires it

</simplicity-rules>

Follow Existing Patterns

Before inventing a new pattern, search the codebase for existing ones. Consistency beats novelty.

<pattern-rules>

• Search for similar features/components as reference
• Match the existing error handling strategy
• Use the same testing patterns found in adjacent tests
• Follow the project's naming conventions
• Read CLAUDE.md and lint config for project-specific rules

</pattern-rules>

Verification Discipline

Verification is the single highest-leverage activity. Code that "looks right" but hasn't been tested is unverified code.

<verification-protocol>

Before Declaring Done

1. Run the tests — If tests exist, run them. If they don't exist for the code you changed, write them.

2. Check for regressions — If you modified existing behavior, run the full relevant test suite, not just new tests.

3. Validate against success criteria — Revisit the criteria defined during planning. Does the implementation actually meet them? Not "probably meets them" — actually meets them.

4. Review your own diff — Read it as if reviewing someone else's code. Look for:

• Leftover debug code or TODO comments
• Missing error handling
• Hardcoded values that should be configurable
• Edge cases not covered
• Dead code from previous attempts

5. Type-check and lint — If the project has type checking or linting, run it. Don't ship code with known warnings.

</verification-protocol>

Self-Verification Patterns

<self-verification>

• Write a failing test first, then implement until it passes
• Use subagents for fresh-context review — they catch mistakes you'll miss in the same context

where you wrote the code

• For UI changes: take a screenshot, compare to requirements
• For API changes: test with actual requests
• For refactors: verify identical behavior before and after

</self-verification>

Context Management

Context is a finite resource with diminishing returns. Every token consumed reduces reasoning quality on the next problem.

<context-rules>

Protect Your Context

• Use subagents for investigation — they explore in separate context and return only summaries
• Don't read entire large files when you need a specific function — use grep/glob to find what

you need

• After two failed corrections on the same issue, start fresh rather than accumulating failed

approaches in context

Be Token-Efficient

• Search narrowly before searching broadly
• Read what you need, when you need it
• Don't pre-load files "just in case"
• Prefer just-in-time context retrieval over upfront loading

Track Progress

• For multi-step work: document completed steps and decisions
• Leave the codebase in a clean state at every checkpoint
• Write clear commit messages that explain WHY, not just WHAT

</context-rules>

Integration

This skill runs BEFORE language-specific skills.

Workflow: 1. Coding skill — Discovery, planning, discipline 2. Language skill (go, typescript, etc.) — Implementation following language-specific conventions 3. Coding skill — Verification, anti-pattern check

IMPORTANT: Return to the verification protocol of this skill before declaring any task complete.