Coding

Discover before assuming. Verify before shipping.

Every coding failure traces to one of three root causes:

1. Acting on assumptions instead of evidence
2. Skipping verification before declaring done
3. 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:

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.

Discovery Protocol

Before planning or implementing, map the territory.

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 is cheap. Debugging wrong assumptions is expensive.

Planning Discipline

Before writing code, establish:

1. 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"

2. Scope — What files change? What stays untouched? Explicitly bound the change. Don't "helpfully improve" adjacent code.

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

4. Verification strategy — How will you prove it works? Tests > manual check > "it looks right". Define this BEFORE writing any implementation code.

Implementation Discipline

Work Incrementally

Don't one-shot complex features.

Write Simple Code

Agents overcomplicate by default. Actively resist this.

Follow Existing Patterns

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

Verification Discipline

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

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.

Self-Verification Patterns

Context Management

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

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

Anti-Patterns

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.