JordanCoin/codingskills

# Boy Scout Rule

## Before Applying

If `.agents/stack-context.md` exists, read it first. Apply this principle using idiomatic patterns for the detected stack. For framework-specific details, use context7 MCP or web search — don't guess.

## Principle

Leave every file you touch a little better than you found it. Not a lot better — a little better. Incremental improvement compounds into a clean codebase over time.

## Why This Matters in Production

Codebases don't rot overnight. They degrade one shortcut at a time — a hardcoded value here, a skipped rename there, a TODO that lives for three years. The Boy Scout Rule is the antidote: it makes improvement the default, not a scheduled event.

# Convention over Configuration

## Before Applying

If `.agents/stack-context.md` exists, read it first. Apply this principle using idiomatic patterns for the detected stack. For framework-specific details, use context7 MCP or web search — don't guess.

## Principle

Adopt sensible defaults and consistent patterns so that decisions are made once and applied everywhere. Reserve explicit configuration for the cases that genuinely need to differ from the default.

## Why This Matters in Production

Every configuration option is a decision that someone must make, document, understand, and maintain. Misconfigured systems are a top cause of production incidents — wrong environment variables, typos in YAML, conflicting settings between services.

# Detect Stack

Analyze the current codebase and generate `.agents/stack-context.md`. Run this on first use in a project, or when the stack context is missing or stale.

## What to Detect

Scan the project root for these signals:

**Language** — Count file extensions (`.rs`, `.py`, `.ts`, `.go`, `.swift`, `.java`, `.rb`, `.cs`, `.ex`, etc.). Primary = most files. Note secondary languages.

**Framework** — Read the package manifest:
- `Cargo.toml` → check `[dependencies]` for axum, actix, rocket, sqlx, diesel, tokio
- `package.json` → check for react, next, svelte, express, fastify, prisma
- `go.mod` → check for gin, echo, fiber, chi, sqlc

# DRY — Don't Repeat Yourself

## Before Applying

If `.agents/stack-context.md` exists, read it first. Apply this principle using idiomatic patterns for the detected stack. For framework-specific details, use context7 MCP or web search — don't guess.

## Principle

Every piece of knowledge in a system should have a single, authoritative representation. When that knowledge changes, you should only need to change it in one place.

## Why This Matters in Production

Duplicated logic is a ticking time bomb. When a business rule changes and you update it in one place but miss the copy in another, you get inconsistent behavior that's hard to detect and harder to debug. The more copies exist, the more likely one diverges silently.

# KISS — Keep It Simple

## Before Applying

If `.agents/stack-context.md` exists, read it first. Apply this principle using idiomatic patterns for the detected stack. For framework-specific details, use context7 MCP or web search — don't guess.

## Principle

Given two solutions that produce the same result, prefer the one that is easier to read, understand, and change.

## Why This Matters in Production

Simple code survives contact with production. Complex code breaks in ways that are hard to diagnose, hard to fix, and hard to verify the fix didn't break something else. Every incident response starts with someone reading code under pressure — if they can't understand it quickly, the outage gets longer.

# LoD — Law of Demeter (Principle of Least Knowledge)

## Before Applying

If `.agents/stack-context.md` exists, read it first. Apply this principle using idiomatic patterns for the detected stack. For framework-specific details, use context7 MCP or web search — don't guess.

## Principle

A component should only talk to its immediate collaborators. Don't reach through an object to access its internals, its children's internals, or anything deeper.

More precisely: a method should only call methods on (1) itself, (2) its own fields, (3) its parameters, (4) objects it creates, and (5) global/singleton services.

## Why This Matters in Production

# SoC — Separation of Concerns

## Before Applying

If `.agents/stack-context.md` exists, read it first. Apply this principle using idiomatic patterns for the detected stack. For framework-specific details, use context7 MCP or web search — don't guess.

## Principle

Each module, layer, or component in a system should address a single concern. A concern is a distinct aspect of functionality — data access, business rules, presentation, authentication, error handling, logging.

## Why This Matters in Production

When concerns are entangled, changes become dangerous. Modifying the database schema shouldn't break the UI. Changing the logging format shouldn't affect business logic. Adding authentication shouldn't require rewriting every handler.

# SOLID Principles

## Before Applying

If `.agents/stack-context.md` exists, read it first. Apply this principle using idiomatic patterns for the detected stack. For framework-specific details, use context7 MCP or web search — don't guess.

## Principle

Five design principles that produce modular, testable, and resilient systems. While originally framed for object-oriented design, the underlying ideas apply to any paradigm — functions, modules, services, or components.

## Why This Matters in Production

SOLID code is change-friendly code. Production systems change constantly — new features, bug fixes, integrations, scaling. Systems designed with SOLID principles absorb change locally rather than requiring cascading modifications. This means fewer regressions, faster feature delivery, and smaller blast radius when things go wrong.

# YAGNI — You Aren't Gonna Need It

## Before Applying

If `.agents/stack-context.md` exists, read it first. Apply this principle using idiomatic patterns for the detected stack. For framework-specific details, use context7 MCP or web search — don't guess.

## Principle

Do not build for hypothetical future requirements. Build what is needed now, and refactor when actual requirements emerge.

## Why This Matters in Production

Speculative code is the #1 source of accidental complexity. Every abstraction, configuration option, or extension point you add "just in case" has a real cost: it must be understood, tested, maintained, and debugged. Unused code paths are the most dangerous — they rot silently, give false confidence in test coverage, and create surface area for bugs.