Principles index

Each principle is a user-invoked skill in skills/ns-principle-<name>/. Each line names when it applies. Read the full SKILL.md of any principle you apply, and in your report name the principle and the choice it changed.

From a skill directory, link a principle as ../ns-principle-<name>/SKILL.md.

Core

• Laziness Protocol: refactoring, sizing a diff, or tempted to add abstractions, layers, or signal threading. Bias to deletion and the smallest change that solves the problem.
• Foundational Thinking: before writing logic. Core types and data structures, scaffold-vs-feature sequencing, what concurrent actors share.
• Redesign from First Principles: integrating a new requirement into an existing design. Redesign as if it had been foundational from day one.
• Attack the Premise: two or more fixes that share one premise have failed the same gate. Census the actors, then question the premise.
• Subtract Before You Add: sequencing an addition, refactor, or rewrite. Remove dead weight first, then build on the simpler base.
• Minimize Reader Load: reviewing or shaping code that's hard to trace. Count layers and hidden state, collapse one-caller wrappers, shrink mutable scope.
• Outcome-Oriented Execution: planned rewrites and migrations with explicit phase boundaries. Converge on the target, skip throwaway compatibility states.
• Experience First: product, UX, API, or feature-scope tradeoffs. Choose user delight over implementation convenience.
• Exhaust the Design Space: a novel interaction or architectural decision with no precedent. Build 2-3 competing prototypes and compare before committing.
• Build the Lever: any non-trivial work. Build the script, codemod, or generator that does or proves it. The tool is the artifact a reviewer reruns.

Architecture

• Model the Domain: writing stateful logic, or code that branches a lot or repeats a shape assumption across files. Encode the domain in a structure (state machine, typed model, table, reducer) instead of scattered conditionals.
• Boundary Discipline: wiring validation, error handling, framework adapters, or a HAL. Guards at system boundaries, trust internal types, keep business logic pure.
• Type System Discipline: designing types or a signature. Make illegal states unrepresentable, brand primitives, parse external data at boundaries.
• Make Operations Idempotent: commands, lifecycle steps, boot or update paths, or loops that run amid crashes, power cuts, and retries. Converge to the same end state.
• Migrate Callers Then Delete Legacy APIs: introducing a new internal API while old callers exist. Migrate and delete in one wave.
• Separate Before Serializing Shared State: concurrent actors (workers, worktrees, an ISR and the main loop) might write the same file, branch, key, or variable. Eliminate the sharing first.

Verification

• Prove It Works: after a task, before declaring done. Verify against the real artifact, on target when hardware is involved, not a proxy or "it compiles".
• Fix Root Causes: debugging. Reproduce first, ask why until you reach the cause, fix it there.
• Sequence Work into Verifiable Units: multi-step work and how you stack commits and PRs. Small units that each end in a check, verified before the next.
• Test Behavior, Not Implementation: writing, changing, or keeping a test. Assert what users observe against a literal expected value. If it would pass with every import returning None, rewrite or delete it.
• Explain the Number: before you trust, report, or act on a measured number (speedup, regression, latency, eval result). Find what limits it and rule out that it measured something else.

Delegation

• Guard the Context Window: context fills up with large outputs, long files, repeated reads, or fan-out planning. Route bulk to fresh-context agents, keep summaries in the main thread.
• Never Block on the Human: tempted to ask "should I do X?" on reversible work. Proceed, present the result, let the human course-correct.

Meta

• Encode Lessons in Structure: you catch yourself writing the same instruction a second time. Encode it as a lint, metadata flag, runtime check, or script.