# Coding Principles

> Code philosophy for writing, modifying, or refactoring code. Use when implementing features, fixing bugs, or reviewing code quality. Covers happy-path-first development, zero duplication, and single source of truth. Use when this capability is needed.

- Skill: `tomevault-io/coding-principles` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/coding-principles`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/coding-principles/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/coding-principles

---


# THE MAKE IT WORK FIRST FIELD GUIDE

## CORE TRUTH
Defensive code before functionality is theater.
Prove it works. Then protect it.

## THE RULES
1. Build the Happy Path First – Code that DOES the thing
2. No Theoretical Defenses – Naked first version
3. Learn from Real Failures – Fix reality, not ghosts
4. Guard Only What Breaks – Add checks only for facts
5. Keep the Engine Visible – Action, not paranoia

## EXCEPTIONS
Security boundaries require defenses from the start:
- Authentication & authorization
- Input sanitization (XSS, SQL injection, command injection)
- Cryptography & key handling
- User-facing error messages (errors ARE the feature)
- System boundaries (external APIs, user input)

## ANTI-PATTERNS TO BURN
- Fortress Validation
- Defensive Exit Theater
- Connection State Paranoia

## PATTERNS TO LIVE BY
- Direct Execution
- Natural Failure
- Continuous Progress

## THE TEST
Can someone grok your code in 10 seconds?
YES → You lived the manifesto
NO  → Delete defenses

---

# THE ZERO DUPLICATION LAW

## CORE TRUTH
Duplicated logic creates blind spots.
One fix leaves the other broken.
Even AI misses duplicates.

## THE RULES
1. Same Logic Twice = Extract Once – No exceptions
2. Before Adding Feature – Grep for similar patterns
3. After Fixing Bug – Search for same logic elsewhere
4. When Refactoring – Kill all copies, keep one source
5. Complex Logic (>20 lines) – Extract immediately

## AI PREVENTION PROTOCOL
Before writing any logic >10 lines, MANDATORY steps:
1. Grep for similar function/method names
2. Grep for key domain terms in the logic
3. Read matching files to verify
4. Found existing? Extend/reuse it - NEVER duplicate
5. Nothing found? Write once, make it reusable from the start

NOT OPTIONAL. NOT AFTER. BEFORE EVERY WRITE.

## DUPLICATION SIGNALS
- "Also update the other one"
- Copy-paste with minor changes
- Bug fixed in one place, appears elsewhere
- Two functions with similar names doing same thing

## EXTRACT THRESHOLDS
- **Identical logic 2+ times** → Extract now
- **Similar logic 2+ times** → Extract if >20 lines
- **Simple logic 2+ times** → Extract if >3 times
- **UI event handlers** → Extract if same pattern appears

## THE TEST
Will a bug fix in one place leave the other broken?
YES → You have duplication
NO  → You passed

---

# THE SINGLE SOURCE OF TRUTH LAW

## CORE TRUTH
Duplicated state creates sync bugs.
One truth updates, the other goes stale.
Even you can't track all copies.

## THE RULES
1. One Canonical Source – Pick one place for each piece of state
2. Derived State is Computed – Calculate from source, don't cache
3. Views Reflect State – UI/output reads from state, not the reverse
4. Before Adding State – Ask "Can I compute this from existing state?"
5. Sync is a Code Smell – If you're syncing two things, one shouldn't exist

## DUPLICATION SIGNALS
- "Keep X and Y in sync"
- `previousX` or `cachedX` state variables
- Update handlers that copy state to another location
- Comments like "Make sure to also update..."

## THE TEST
If state A changes, does state B need manual updating?
YES → You have duplicate state
NO  → You passed

Can you derive B from A instantly?
YES → Delete B, compute it
NO  → Maybe B is the true source

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/shirohana) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->