tomevault-io 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:
STOP. Ask yourself:
- "Do I have evidence in current context that this exists?"
- "Have I actually read this code, or am I assuming?"
- 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:
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.
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
Run the tests — If tests exist, run them. If they don't exist for the code you changed, write them.
Check for regressions — If you modified existing behavior, run the full relevant test suite, not just new tests.
Validate against success criteria — Revisit the criteria defined during planning. Does the implementation actually meet them? Not "probably meets them" — actually meets them.
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
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
Integration
This skill runs BEFORE language-specific skills.
Workflow:
- Coding skill — Discovery, planning, discipline
- Language skill (go, typescript, etc.) — Implementation following language-specific conventions
- Coding skill — Verification, anti-pattern check
IMPORTANT: Return to the verification protocol of this skill before declaring any task complete.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.