ds-principles
Compact engineering principles for design, debugging, verification, and delegation, each with a trigger. Use when choosing structure or types, sizing a diff, debugging, writing tests, or when the user types /ds-principles.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- ds-principles
- description
- Compact engineering principles for design, debugging, verification, and delegation, each with a trigger. Use when choosing structure or types, sizing a diff, debugging, writing tests, or when the user types /ds-principles.
03 SKILL.md 正文
Engineering principles
If a trigger matches, apply the rule. Name principles that changed a decision.
Design
- Subtract, then add little. Remove dead code and stale checks first, then make the shortest diff that works. No abstraction with one user. Apply when sizing a diff or tempted to add a layer.
- Data shape first. Choose the core types and structures before logic. Apply before writing new logic.
- Model the domain. Put states in one structure, such as a typed union, state machine, or lookup table, not scattered conditionals. Apply when code branches a lot or repeats a shape across files.
- Redesign for the new need. Fit a new requirement as if it existed from day one. Apply when an addition strains the design.
- Low reader load. Inline one-caller wrappers and shrink mutable scope. Apply when code is hard to trace.
- Guards at boundaries. Validate where input enters: CLI, config, network, files, external APIs. Trust types inside and keep core logic pure. Apply when adding validation or error handling.
- Idempotent steps. Rerunning a step, even after a crash, reaches the same state. Apply to commands, setup, and retries.
- No shared writers. Give each concurrent actor its own file, branch, or key before using locks. Apply when parallel work touches shared state.
- Migrate, then delete. Move every caller and delete the old API in one change. No shims. Apply when replacing an API or rewriting in phases.
- Compare options. For an unprecedented design, sketch two or three. Prefer fewer, polished features. Apply to novel architecture, UX, or scope choices.
Debugging and verification
- Fix root causes. Fix where state first went wrong. A guard fixes only legitimate states. Apply when debugging.
- Attack the premise. After two failed fixes that share an assumption, write it down and test it directly. Apply before a third attempt.
- Prove it works. Run the real thing and read the actual output, not a proxy. Apply before claiming done.
- Verifiable units. Split work into steps that each end in a passing check. Apply to sweeps, migrations, and stacked commits.
- Test behavior. Assert what callers can observe, so tests survive refactors. Apply when writing or keeping a test.
- Explain the number. Find what limits a measurement and confirm it measured the right work. Apply to benchmarks and eval scores.
- Build the tool. Script bulk or repeated work so it can be rerun. Apply to large edit sets or checks.
Process
- Guard the context. Keep summaries, not dumps. Send bulk reading to subagents. Apply when outputs or files are large.
- Do not block on the human. On reversible work, proceed and show the result. Apply when tempted to ask "should I?".
- Encode repeated lessons. A correction given twice becomes a lint, test, or script. Apply when a mistake recurs.
- Comments explain why. Keep a comment only for a reason the code cannot show, such as an external constraint or a public API contract. Delete narration and dead code. Fix code whose surprise needs a comment. Apply when writing or reviewing code.
Types
- Make illegal states unrepresentable. Use discriminated unions, not optional-field bags.
- Parse external data once at the boundary into a named type. Trust it inside.
- Use
unknownfor untrusted input. Neverany. Noascasts before validation. - Derive types from a schema, not hand-written guards.
- Add a
nevercheck in default branches so new variants fail the build. - Brand primitives that must not mix, such as user IDs and order IDs.
Greeneek working contract
This skill is installed in the Greeneek repository. Where a step below conflicts with these rules, these rules win.
- Restate the goal in one line, read the real files before editing, and work on
mainin small vertical slices. Preserve uncommitted and concurrent work; never reset, force-push, or overwrite another session's changes. - Evidence before "done": run the real check and record the exact command and its output. Never weaken a test, add a blind retry, raise a timeout without a diagnosed cause, or delete a failing assertion to get green.
- Agent waves never commit, push, tag, or publish. No npm auto-publish on
main; release tags are immutable and Item 8 stays last. - Live model lanes stay BLOCKED without
GREENEEK_API_KEY; mocked coverage is never reported as real-CLI verification. - Registrations are effects, ESM everywhere, and misconfiguration fails at the earliest resolvable point.
- Source of truth:
.agents/notes/proposed/process/2026-11-01-v0.3.9-master-release-plan.md. Append evidence to its Execution ledger and keep its Resume State current in the same commit as the change.
Greeneek-specific override
In this repo also name the Greeneek principle that changed the decision: registrations are effects; ESM everywhere; fail loud at the earliest resolvable point; no pre-release compatibility shims; a registry's register() returns the disposer; publish an invariant only when independent observations can diverge.
04 同仓库更多 Skills
user-only-skill
Prove model-disabled skills stay outside the model catalog.
snapshot-skill
Exercise project skill discovery and loading in snapshot tests.
model-only-skill
Prove user-disabled skills remain available to the model.
editing-cordis-compositions
Use when creating, changing, or validating a Cordis composition for this harness — writing or editing an agent preset, adding or removing a plugin row, deciding whether something belongs to the host composition or to one session, checking whether a preset you authored actually mounts, or diagnosing a row that mounted but contributed nothing.
cordis-plugin-development
Create, modify, debug, or extend dynamic Cordis Plugins, including Host Services and Events, Client Slot and theme UI, Package-private Client-to-Host calls, dynamic Tools, version updates, approval failures, and runtime diagnostics. Use this Skill to route a user request to the correct platform and Inspect Provider, then define, run, repair, or roll back the Plugin.
preview-tour
Inspect the bundled Preview workspace and its deterministic Session examples.