| name | coding-standards |
| description | Implement an approved MAD task with minimal scope, established architecture, risk-driven validation, diff self-review, and truthful evidence. Use for backend, data, infrastructure, tooling, or mixed implementation work after task preflight. |
Coding Standards
Correctness and evidence outrank code volume. Follow repository-local rules before this generic skill when they are stricter.
Preflight
- Verify assigned workspace, branch, base revision, and clean/expected status.
- Read task contract, acceptance criteria, consumed contracts, allowed/forbidden scope, dependencies, and required checks.
- Inspect the existing implementation, tests, and nearest architectural seam.
- Map each definition-of-done item to a code change and evidence.
- Establish a focused baseline when practical.
- Stop if behavior, authority, scope, dependency, or evidence premise is materially ambiguous.
Completion criterion: work can proceed without inventing behavior or modifying unowned artifacts.
Implementation loop
- Make the smallest coherent change that satisfies one observable criterion.
- Preserve established architecture and invariants; prefer existing seams over new abstractions.
- Add validation at trust boundaries and tests at the lowest effective layer.
- Run focused evidence early.
- Inspect the diff for scope, contract, security, generated-file, and unrelated-change drift.
- Repeat until every criterion is covered.
- Run all contract-required and risk-triggered checks.
- Perform final skeptical self-review and produce the canonical report.
Design discipline
- Keep behavior changes distinct from mechanical cleanup.
- Avoid speculative generality, pass-through wrappers, broad formatting, unrelated dependency upgrades, and opportunistic rewrites.
- Prefer deep modules that hide complexity behind small stable interfaces.
- Make invalid states difficult to represent where local design permits.
- Preserve authorization, validation, privacy, transactions, concurrency/idempotency, errors, observability, and resource lifecycle.
- Comments explain constraints or non-obvious rationale, not syntax.
- Change generated sources, not generated output, unless the contract explicitly owns regeneration.
- Never add secrets, personal data, debug artifacts, machine-specific paths, or silent failure handling.
Risk triggers
Backend/data
Validate authorization, inputs, error mapping, transactions, concurrency/idempotency, persistence compatibility, migrations/rollback, and observability as applicable.
Infrastructure/deployment
Validate least privilege, secret/config handling, idempotence, plan/dry-run, health/readiness, rollout/rollback, state preservation, and environment compatibility.
Tooling/automation
Validate deterministic output, non-zero failure exits, actionable diagnostics, path portability, clean-environment execution, and dry-run before external side effects.
For UI/mobile, load frontend-design-system in addition to this skill.
Testing standard
A useful test protects behavior, fails for the defect it claims to detect, avoids internal implementation coupling, and covers critical negative/recovery behavior. Do not weaken or delete meaningful tests solely to make a change green. Separate pre-existing failures with baseline evidence.
Final diff gate
Confirm:
- every changed file is intentional and within allowed scope
- forbidden/controlled files changed only with explicit authority
- no unrelated refactor, generated drift, secret, or debug artifact remains
- acceptance criteria and critical risks have evidence
- required checks ran against the reported revision
- assumptions, residual risks, and downstream impact are concrete
Use mechanical scope validation when available:
hermes mad check-scope <contract.yaml> --repo . --base <approved-base>
Status rule
Report completed only when definition of done and required evidence passed. Use partial, blocked, or failed according to the global protocol; never convert unavailable or failing evidence into success.
