engineering

Files (1)

• SKILL.md

SKILL.md (first lines)

# Engineering

## Always-On Principles

These constraints bind every code edit without skill invocation. They are the
standing SWE law promoted into the always-on conditioning layer; deviation
requires explicit justification and human approval. Detailed elaboration follows
in the [By-Moment Reference](#by-moment-reference) below.

### Root Cause — Never a Band-Aid

A fix that papers over a symptom — a compatibility shim, a workaround that lets
a broken design survive, an exception added to silence a warning — is a defect,
not a solution. The cause MUST be fixed. If the fix requires more than local
changes, HALT and discuss the scope before proceeding; do not re-architect
silently.

Compatibility hacks are forbidden. Additions beyond the stated task are
forbidden (the Cutting Imperative: do not add features, abstractions, or cleanup
not present in the task). When removing code, cut completely — compatibility
scaffolding for removed code is entropy that must later be audited for meaning.

### No Silent Failures

Every error path MUST be handled or propagated, preserving the causal chain.
Error messages MUST state **what** failed, **why**, and **where** — opaque
messages such as "invalid input" are forbidden. Library code MUST NOT panic; it
MUST return `Result`/`Option` to the caller. Application entry points convert
errors to exit codes with clear messages. Secrets, tokens, and PII MUST NOT
appear in logs.

### Validate at Boundaries; Trust Internal Invariants

All external inputs MUST be validated at system entry points (user input, API
responses, file contents, IPC). Internal call sites MUST NOT add defensive
guards against conditions the type system or framework invariants already rule
out — that is unnecessary error handling that obscures where the real boundaries
are. Validate the perimeter; trust what the perimeter enforced.

### Strong Typing — No Escape Hatches

Use the type system to enforce invariants. `any`, `interface{}`, or their
language equivalents MUST NOT be used unless genuinely necessary; when used, the
specific reason MUST be documented inline. Library code MUST NOT panic.

### Discrepancy Resolution — Never Silent

When specification, tests, and code disagree, HALT immediately. Present the
discrepancy with evidence from each source and propose a resolution. Do not
silently pick a winner; do not proceed until the conflict is resolved.

### Trajectory Freeze Conditions

Stop generating and query for boundary updates whenever:

- Goal or context is contradictory or missing (uncertainty > 0.0).
- Environment state diverges from planned invariants (expected files missing,
  API mismatch).
- Verification tools fail to converge after the corrective loop.
- Multiple valid paths exist with no constraint selecting among them.

Generating under unvalidated assumptions is forbidden. Guessing a corrective
edit from ambiguous feedback is forbidden. Halting to receive parameters is
faster than correcting trajectory drift.

---

## By-Moment Reference

The sections below elaborate *how* to apply the always-on principles in
practice: clarification protocols, uncertainty thresholds, language-specific
rules, and conventions. Load this reference when actively writing or reviewing
code.

---

### Clarification Triggers

Invoke clarification under these conditions:

1. **Undefined Scope:** The request could range from trivial to architecturally significant.
2. **Missing Acceptance Criteria:** There is no clear definition of "done."
3. **Implicit Assumptions:** The request relies on unstated assumptions about the codebase or domain.
4. **Conflicting Constraints:** The request appears to conflict with an existing rule or prior decision.

### Uncertainty Thresholds

| Uncertainty Level | Criteria                                              | Action                                                                          |
| :---------------- | :---------------------------------------------------- | :------------------------------------------------------------------------------ |
| **None (0.0)**    | Clear requirement, established pattern, no ambiguity. | Proceed. If the change is API-breaking, still confirm.                          |
| **Low (0.1-0.3)** | Explicit constraints with minor implementation ambiguities. | Present implementation path and query for targeted constraint boundaries before proceeding. |
| **High (>0.3)**   | Multiple valid interpretations, conflicting constraints. | Halt sequence walk and request specific boundary parameter corrections.           |

When in doubt, err toward halting. Wasted clarification is cheaper than trajectory drift.

> [!NOTE]
> This table applies to general execution. In C.O.R.E. planning, the
> ambiguity gate uses a qualitative `OBSTACLES` list: the list must be
> empty before the sequence may advance from CLARIFY to PLAN. There is
> no numeric uncertainty field in the C.O.R.E. grammar.

---

### Rule 0: Context Acquisition (The "Read-First" Rule)

Before writing code, understand the existing landscape:

1. **Outline First:** Read file outlines to understand structure.
2. **Targeted Read:** Read specific functions, modules, or types relevant to the change.
3. **Contextual Files:** Read related files (tests, interfaces, callers) to understand usage patterns.
4. **Full Read:** Only for small files (<500 lines) or major refactors.

**Pattern Matching:** Mimic existing directory structure and coding style strictly. Do not introduce foreign idioms. When uncertain, search for prior art in the repo (e.g., "How are errors handled elsewhere?") and follow established patterns.

> **Tip:** If MCP tools are available, use them first for structural insight before reading individual files.

### Rule 1: Root Cause Analysis

Never apply band-aid fixes. Analyze root causes; re-architect if the foundation is flawed. If a fix requires more than local changes, stop and discuss the broader implications.

From nrdxp/predicate, MIT.

More from nrdxp/predicate